lib/libftpio/ftpio.3

   1 .\" Copyright (c) 1996 Jordan Hubbard (jkh@FreeBSD.org)
   2 .\" All rights reserved.
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, are permitted provided that the following conditions
   6 .\" are met:
   7 .\" 1. Redistributions of source code must retain the above copyright
   8 .\"    notice, this list of conditions and the following disclaimer.
   9 .\" 2. Redistributions in binary form must reproduce the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer in the
  11 .\"    documentation and/or other materials provided with the distribution.
  12 .\"
  13 .\" THIS SOFTWARE IS PROVIDED BY JORDAN HUBBARD ``AS IS'' AND
  14 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  15 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  16 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  17 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  18 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  19 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  20 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  21 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  22 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  23 .\" SUCH DAMAGE.
  24 .\"
  25 .\" $FreeBSD: src/lib/libftpio/ftpio.3,v 1.21.2.9 2002/12/29 16:35:35 schweikh Exp $
  26 .\" $DragonFly: src/lib/libftpio/ftpio.3,v 1.5 2008/05/04 00:55:01 swildner Exp $
  27 .\"
  28 .Dd June 17, 1996
  29 .Dt FTPIO 3
  30 .Os
  31 .Sh NAME
  32 .Nm ftpLogin ,
  33 .Nm ftpChdir ,
  34 .Nm ftpErrno ,
  35 .Nm ftpErrString ,
  36 .Nm ftpGetModtime ,
  37 .Nm ftpGetSize ,
  38 .Nm ftpGet ,
  39 .Nm ftpPut ,
  40 .Nm ftpAscii ,
  41 .Nm ftpBinary ,
  42 .Nm ftpPassive ,
  43 .Nm ftpVerbose ,
  44 .Nm ftpGetURL ,
  45 .Nm ftpPutURL ,
  46 .Nm ftpLoginAf ,
  47 .Nm ftpGetURLAf ,
  48 .Nm ftpPutURLAf
  49 .Nd FTPIO user library
  50 .Sh LIBRARY
  51 .Lb libftpio
  52 .Sh SYNOPSIS
  53 .In ftpio.h
  54 .Ft FILE *
  55 .Fn ftpLogin "char *host" "char *user" "char *passwd" "int ftp_port" "int verbose" "int *retcode"
  56 .Ft int
  57 .Fn ftpChdir "FILE *stream" "char *dirname"
  58 .Ft int
  59 .Fn ftpErrno "FILE *stream"
  60 .Ft const char *
  61 .Fn ftpErrString "int errno"
  62 .Ft time_t
  63 .Fn ftpGetModtime "FILE *stream" "char *file"
  64 .Ft off_t
  65 .Fn ftpGetSize "FILE *stream" "char *file"
  66 .Ft FILE *
  67 .Fn ftpGet "FILE *stream" "char *file" "off_t *seekto"
  68 .Ft FILE *
  69 .Fn ftpPut "FILE *stream" "char *file"
  70 .Ft int
  71 .Fn ftpAscii "FILE *stream"
  72 .Ft int
  73 .Fn ftpBinary "FILE *stream"
  74 .Ft int
  75 .Fn ftpPassive "FILE *stream" "int status"
  76 .Ft void
  77 .Fn ftpVerbose "FILE *stream" "int status"
  78 .Ft FILE *
  79 .Fn ftpGetURL "char *url" "char *user" "char *passwd" "int *retcode"
  80 .Ft FILE *
  81 .Fn ftpPutURL "char *url" "char *user" "char *passwd" "int *retcode"
  82 .Ft FILE *
  83 .Fn ftpLoginAf "char *host" "int af" "char *user" "char *passwd" "int ftp_port" "int verbose" "int *retcode"
  84 .Ft FILE *
  85 .Fn ftpGetURLAf "char *url" "int af" "char *user" "char *passwd" "int *retcode"
  86 .Ft FILE *
  87 .Fn ftpPutURLAf "char *url" "int af" "char *user" "char *passwd" "int *retcode"
  88 .Sh DESCRIPTION
  89 These functions implement a high-level library for managing FTP connections.
  90 .Pp
  91 .Fn ftpLogin
  92 attempts to log in using the supplied
  93 .Fa user ,
  94 .Fa passwd ,
  95 .Fa ftp_port
  96 (if passed as 0,
  97 .Fa ftp_port
  98 defaults to the standard ftp port of 21) and
  99 .Fa verbose
 100 fields.  If it is successful, a
 101 standard stream descriptor is returned which should be passed to
 102 subsequent FTP operations.
 103 On failure, NULL is returned and
 104 .Fa retcode
 105 will have the error code returned by the foreign server.
 106 .Pp
 107 .Fn ftpChdir
 108 attempts to issue a server CD command to the directory named in
 109 .Fa dir .
 110 On success, zero is returned.  On failure, the error code from the server.
 111 .Pp
 112 .Fn ftpErrno
 113 returns the server failure code for the last operation (useful for seeing
 114 more about what happened if you're familiar with FTP error codes).
 115 .Fn ftpErrString
 116 returns a human readable version of the supplied server failure code.
 117 .Pp
 118 .Fn ftpGet
 119 attempts to retrieve the file named by the
 120 .Fa file
 121 argument (which is assumed to be relative to the FTP server's current directory,
 122 see
 123 .Fn ftpChdir )
 124 and returns a new FILE* pointer for the file or NULL on failure.  If
 125 .Fa seekto
 126 is non-NULL, the contents of the integer it points to will be used
 127 as a restart point for the file, that is to say that the stream
 128 returned will point
 129 .Fa *seekto
 130 bytes into the file gotten (this is handy for restarting failed
 131 transfers efficiently).  If the seek operation fails, the value
 132 of
 133 .Fa *seekto
 134 will be zero'd.
 135 .Pp
 136 .Fn ftpGetModtime
 137 returns the last modification time of the file named by the
 138 .Fa file
 139 argument.  If the file could not be opened or stat'd, 0 is returned.
 140 .Pp
 141 .Fn ftpGetSize
 142 returns the size in bytes of the file named by the
 143 .Fa file
 144 argument.  If the file could not be opened or stat'd, -1 is returned.
 145 .Pp
 146 .Fn ftpPut
 147 attempts to create a new file named by the
 148 .Fa file
 149 argument (which is assumed to be relative to the FTP server's current directory,
 150 see
 151 .Fn ftpChdir )
 152 and returns a new
 153 .Fa stream
 154 pointer for the file or NULL on failure.
 155 .Pp
 156 .Fn ftpAscii
 157 sets ASCII mode for the current server connection named by
 158 .Fa stream .
 159 .Pp
 160 .Fn ftpBinary
 161 sets binary mode for the current server connection named by
 162 .Fa stream .
 163 .Pp
 164 .Fn ftpPassive
 165 sets passive mode (for firewalls) for the current server connection named by
 166 .Fa stream
 167 to boolean value
 168 .Fa status .
 169 .Pp
 170 .Fn ftpVerbose
 171 sets the verbosity mode for the current server connection named by
 172 .Fa stream
 173 to boolean value
 174 .Fa status .
 175 .Pp
 176 .Fn ftpGetURL
 177 attempts to retrieve the file named by the supplied
 178 .Fa URL
 179 and can be considered equivalent to the combined
 180 .Fn ftpLogin ,
 181 .Fn ftpChdir
 182 and
 183 .Fn ftpGet
 184 operations except that no server
 185 .Fa stream
 186 is ever returned - the connection to the server closes when
 187 the file has been completely read.  Use the lower-level routines
 188 if multiple gets are required as it will be far more efficient.
 189 .Pp
 190 .Fn ftpPutURL
 191 attempts to create the file named by the supplied
 192 .Fa URL
 193 and can be considered equivalent to the combined
 194 .Fn ftpLogin ,
 195 .Fn ftpChdir
 196 and
 197 .Fn ftpPut
 198 operations except that no server stream is ever returned - the connection
 199 to the server closes when the file has been completely written.  Use the
 200 lower-level routines if multiple puts are required as it will be far more
 201 efficient.
 202 .Pp
 203 .Fn ftpLoginAf ,
 204 .Fn ftpGetURLAf ,
 205 .Fn ftpPutURLAf
 206 are same as
 207 .Fn ftpLogin ,
 208 .Fn ftpGetURL ,
 209 .Fn ftpPutURL
 210 except that they are able to specify address family
 211 .Fa af .
 212 .Sh ENVIRONMENT
 213 .Bl -tag -width FTP_PASSIVE_MODE -offset 3n
 214 .It Ev FTP_TIMEOUT
 215 Maximum time, in seconds, to wait for a response
 216 from the peer before aborting an
 217 .Tn FTP
 218 connection.
 219 .It Ev FTP_PASSIVE_MODE
 220 If defined, forces the use of passive mode, unless equal
 221 to ``NO'' or ``no'' in which case active mode is forced.
 222 If defined, the setting of this variable always overrides any calls to
 223 .Fn ftpPassive .
 224 .El
 225 .Sh HISTORY
 226 Started life as Poul-Henning Kamp's ftp driver for the system installation
 227 utility, later significantly mutated into a more general form as an
 228 extension of stdio by Jordan Hubbard.  Also incorporates some ideas and
 229 extensions from Jean-Marc Zucconi.
 230 .Sh AUTHORS
 231 .An Jordan Hubbard ,
 232 .An Poul-Henning Kamp
 233 and
 234 .An Jean-Marc Zucconi
 235 .Sh BUGS
 236 I'm sure you can get this thing's internal state machine confused if
 237 you really work at it, but so far it's proven itself pretty robust in
 238 all my tests.