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$
  26 .\"
  27 .Dd June 17, 1996
  28 .Dt FTPIO 3
  29 .Os
  30 .Sh NAME
  31 .Nm ftpLogin ,
  32 .Nm ftpChdir ,
  33 .Nm ftpErrno ,
  34 .Nm ftpGetModtime ,
  35 .Nm ftpGetSize ,
  36 .Nm ftpGet ,
  37 .Nm ftpPut ,
  38 .Nm ftpBinary ,
  39 .Nm ftpPassive ,
  40 .Nm ftpVerbose ,
  41 .Nm ftpGetURL ,
  42 .Nm ftpPutURL ,
  43 .Nm ftpLoginAf ,
  44 .Nm ftpGetURLAf ,
  45 .Nm ftpPutURLAf
  46 .Nd FTPIO user library
  47 .Sh SYNOPSIS
  48 .In ftpio.h
  49 .Ft FILE *
  50 .Fn ftpLogin "char *host" "char *user" "char *passwd" "int ftp_port" "int verbose" "int *retcode"
  51 .Ft int
  52 .Fn ftpChdir "FILE *stream" "char *dirname"
  53 .Ft int
  54 .Fn ftpErrno "FILE *stream"
  55 .Ft const char *
  56 .Fn ftpErrString "int errno"
  57 .Ft time_t
  58 .Fn ftpGetModtime "FILE *stream" "char *file"
  59 .Ft off_t
  60 .Fn ftpGetSize "FILE *stream" "char *file"
  61 .Ft FILE *
  62 .Fn ftpGet "FILE *stream" "char *file" "off_t *seekto"
  63 .Ft FILE *
  64 .Fn ftpPut "FILE *stream" "char *file"
  65 .Ft int
  66 .Fn ftpAscii "FILE *stream"
  67 .Ft int
  68 .Fn ftpBinary "FILE *stream"
  69 .Ft int
  70 .Fn ftpPassive "FILE *stream" "int status"
  71 .Ft void
  72 .Fn ftpVerbose "FILE *stream" "int status"
  73 .Ft FILE *
  74 .Fn ftpGetURL "char *url" "char *user" "char *passwd" "int *retcode"
  75 .Ft FILE *
  76 .Fn ftpPutURL "char *url" "char *user" "char *passwd" "int *retcode"
  77 .Ft FILE *
  78 .Fn ftpLoginAf "char *host" "int af" "char *user" "char *passwd" "int ftp_port" "int verbose" "int *retcode"
  79 .Ft FILE *
  80 .Fn ftpGetURLAf "char *url" "int af" "char *user" "char *passwd" "int *retcode"
  81 .Ft FILE *
  82 .Fn ftpPutURLAf "char *url" "int af" "char *user" "char *passwd" "int *retcode"
  83 .Sh DESCRIPTION
  84 These functions implement a high-level library for managing FTP connections.
  85 .Pp
  86 The
  87 .Fn ftpLogin
  88 function attempts to log in using the supplied
  89 .Fa user ,
  90 .Fa passwd ,
  91 .Fa ftp_port
  92 (if passed as 0,
  93 .Fa ftp_port
  94 defaults to the standard ftp port of 21) and
  95 .Fa verbose
  96 fields.
  97 If it is successful, a
  98 standard stream descriptor is returned which should be passed to
  99 subsequent FTP operations.
 100 On failure, NULL is returned and
 101 .Fa retcode
 102 will have the error code returned by the foreign server.
 103 .Pp
 104 The
 105 .Fn ftpChdir
 106 function attempts to issue a server CD command to the directory named in
 107 .Fa dir .
 108 On success, zero is returned.
 109 On failure, the error code from the server.
 110 .Pp
 111 The
 112 .Fn ftpErrno
 113 function returns the server failure code for the last operation (useful for
 114 seeing more about what happened if you are familiar with FTP error codes).
 115 The
 116 .Fn ftpErrString
 117 function returns a human readable version of the supplied server failure code.
 118 .Pp
 119 The
 120 .Fn ftpGet
 121 function attempts to retrieve the file named by the
 122 .Fa file
 123 argument (which is assumed to be relative to the FTP server's current directory,
 124 see
 125 .Fn ftpChdir )
 126 and returns a new FILE* pointer for the file or NULL on failure.
 127 If
 128 .Fa seekto
 129 is non-NULL, the contents of the integer it points to will be used
 130 as a restart point for the file, that is to say that the stream
 131 returned will point
 132 .Fa *seekto
 133 bytes into the file gotten (this is handy for restarting failed
 134 transfers efficiently).
 135 If the seek operation fails, the value
 136 of
 137 .Fa *seekto
 138 will be zero'd.
 139 .Pp
 140 The
 141 .Fn ftpGetModtime
 142 function returns the last modification time of the file named by the
 143 .Fa file
 144 argument.
 145 If the file could not be opened or stat'd, 0 is returned.
 146 .Pp
 147 The
 148 .Fn ftpGetSize
 149 function returns the size in bytes of the file named by the
 150 .Fa file
 151 argument.
 152 If the file could not be opened or stat'd, -1 is returned.
 153 .Pp
 154 The
 155 .Fn ftpPut
 156 function attempts to create a new file named by the
 157 .Fa file
 158 argument (which is assumed to be relative to the FTP server's current directory,
 159 see
 160 .Fn ftpChdir )
 161 and returns a new
 162 .Fa stream
 163 pointer for the file or NULL on failure.
 164 .Pp
 165 The
 166 .Fn ftpAscii
 167 function sets
 168 .Tn ASCII
 169 mode for the current server connection named by
 170 .Fa stream .
 171 .Pp
 172 The
 173 .Fn ftpBinary
 174 function sets binary mode for the current server connection named by
 175 .Fa stream .
 176 .Pp
 177 The
 178 .Fn ftpPassive
 179 function sets passive mode (for firewalls) for the current server connection
 180 named by
 181 .Fa stream
 182 to boolean value
 183 .Fa status .
 184 .Pp
 185 The
 186 .Fn ftpVerbose
 187 function sets the verbosity mode for the current server connection named by
 188 .Fa stream
 189 to boolean value
 190 .Fa status .
 191 .Pp
 192 The
 193 .Fn ftpGetURL
 194 function attempts to retrieve the file named by the supplied
 195 .Fa URL
 196 and can be considered equivalent to the combined
 197 .Fn ftpLogin ,
 198 .Fn ftpChdir
 199 and
 200 .Fn ftpGet
 201 operations except that no server
 202 .Fa stream
 203 is ever returned - the connection to the server closes when
 204 the file has been completely read.
 205 Use the lower-level routines
 206 if multiple gets are required as it will be far more efficient.
 207 .Pp
 208 The
 209 .Fn ftpPutURL
 210 function attempts to create the file named by the supplied
 211 .Fa URL
 212 and can be considered equivalent to the combined
 213 .Fn ftpLogin ,
 214 .Fn ftpChdir
 215 and
 216 .Fn ftpPut
 217 operations except that no server stream is ever returned - the connection
 218 to the server closes when the file has been completely written.
 219 Use the
 220 lower-level routines if multiple puts are required as it will be far more
 221 efficient.
 222 .Pp
 223 The
 224 .Fn ftpLoginAf ,
 225 .Fn ftpGetURLAf ,
 226 .Fn ftpPutURLAf
 227 functions are same as
 228 .Fn ftpLogin ,
 229 .Fn ftpGetURL ,
 230 .Fn ftpPutURL
 231 except that they are able to specify address family
 232 .Fa af .
 233 .Sh ENVIRONMENT
 234 .Bl -tag -width FTP_PASSIVE_MODE -offset 3n
 235 .It Ev FTP_TIMEOUT
 236 Maximum time, in seconds, to wait for a response
 237 from the peer before aborting an
 238 .Tn FTP
 239 connection.
 240 .It Ev FTP_PASSIVE_MODE
 241 If defined, forces the use of passive mode, unless equal
 242 to ``NO'' or ``no'' in which case active mode is forced.
 243 If defined, the setting of this variable always overrides any calls to
 244 .Fn ftpPassive .
 245 .El
 246 .Sh HISTORY
 247 Started life as Poul-Henning Kamp's ftp driver for the system installation
 248 utility, later significantly mutated into a more general form as an
 249 extension of stdio by Jordan Hubbard.
 250 Also incorporates some ideas and
 251 extensions from Jean-Marc Zucconi.
 252 .Sh AUTHORS
 253 .An Jordan Hubbard ,
 254 .An Poul-Henning Kamp
 255 and
 256 .An Jean-Marc Zucconi
 257 .Sh BUGS
 258 I am sure you can get this thing's internal state machine confused if
 259 you really work at it, but so far it has proven itself pretty robust in
 260 all my tests.