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