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