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 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 .Fn ftpLogin
  87 attempts to log in using the supplied
  88 .Fa user ,
  89 .Fa passwd ,
  90 .Fa ftp_port
  91 (if passed as 0,
  92 .Fa ftp_port
  93 defaults to the standard ftp port of 21) and
  94 .Fa verbose
  95 fields.  If it is successful, a
  96 standard stream descriptor is returned which should be passed to
  97 subsequent FTP operations.
  98 On failure, NULL is returned and
  99 .Fa retcode
 100 will have the error code returned by the foreign server.
 101 .Pp
 102 .Fn ftpChdir
 103 attempts to issue a server CD command to the directory named in
 104 .Fa dir .
 105 On success, zero is returned.  On failure, the error code from the server.
 106 .Pp
 107 .Fn ftpErrno
 108 returns the server failure code for the last operation (useful for seeing
 109 more about what happened if you're familiar with FTP error codes).
 110 .Fn ftpErrString
 111 returns a human readable version of the supplied server failure code.
 112 .Pp
 113 .Fn ftpGet
 114 attempts to retrieve the file named by the
 115 .Fa file
 116 argument (which is assumed to be relative to the FTP server's current directory,
 117 see
 118 .Fn ftpChdir )
 119 and returns a new FILE* pointer for the file or NULL on failure.  If
 120 .Fa seekto
 121 is non-NULL, the contents of the integer it points to will be used
 122 as a restart point for the file, that is to say that the stream
 123 returned will point
 124 .Fa *seekto
 125 bytes into the file gotten (this is handy for restarting failed
 126 transfers efficiently).  If the seek operation fails, the value
 127 of
 128 .Fa *seekto
 129 will be zero'd.
 130 .Pp
 131 .Fn ftpGetModtime
 132 returns the last modification time of the file named by the
 133 .Fa file
 134 argument.  If the file could not be opened or stat'd, 0 is returned.
 135 .Pp
 136 .Fn ftpGetSize
 137 returns the size in bytes of the file named by the
 138 .Fa file
 139 argument.  If the file could not be opened or stat'd, -1 is returned.
 140 .Pp
 141 .Fn ftpPut
 142 attempts to create a new file named by the
 143 .Fa file
 144 argument (which is assumed to be relative to the FTP server's current directory,
 145 see
 146 .Fn ftpChdir )
 147 and returns a new
 148 .Fa stream
 149 pointer for the file or NULL on failure.
 150 .Pp
 151 .Fn ftpAscii
 152 sets ASCII mode for the current server connection named by
 153 .Fa stream .
 154 .Pp
 155 .Fn ftpBinary
 156 sets binary mode for the current server connection named by
 157 .Fa stream .
 158 .Pp
 159 .Fn ftpPassive
 160 sets passive mode (for firewalls) for the current server connection named by
 161 .Fa stream
 162 to boolean value
 163 .Fa status .
 164 .Pp
 165 .Fn ftpVerbose
 166 sets the verbosity mode for the current server connection named by
 167 .Fa stream
 168 to boolean value
 169 .Fa status .
 170 .Pp
 171 .Fn ftpGetURL
 172 attempts to retrieve the file named by the supplied
 173 .Fa URL
 174 and can be considered equivalent to the combined
 175 .Fn ftpLogin ,
 176 .Fn ftpChdir
 177 and
 178 .Fn ftpGet
 179 operations except that no server
 180 .Fa stream
 181 is ever returned - the connection to the server closes when
 182 the file has been completely read.  Use the lower-level routines
 183 if multiple gets are required as it will be far more efficient.
 184 .Pp
 185 .Fn ftpPutURL
 186 attempts to create the file named by the supplied
 187 .Fa URL
 188 and can be considered equivalent to the combined
 189 .Fn ftpLogin ,
 190 .Fn ftpChdir
 191 and
 192 .Fn ftpPut
 193 operations except that no server stream is ever returned - the connection
 194 to the server closes when the file has been completely written.  Use the
 195 lower-level routines if multiple puts are required as it will be far more
 196 efficient.
 197 .Pp
 198 .Fn ftpLoginAf ,
 199 .Fn ftpGetURLAf ,
 200 .Fn ftpPutURLAf
 201 are same as
 202 .Fn ftpLogin ,
 203 .Fn ftpGetURL ,
 204 .Fn ftpPutURL
 205 except that they are able to specify address family
 206 .Fa af .
 207 .Sh ENVIRONMENT
 208 .Bl -tag -width FTP_PASSIVE_MODE -offset 3n
 209 .It Ev FTP_TIMEOUT
 210 Maximum time, in seconds, to wait for a response
 211 from the peer before aborting an
 212 .Tn FTP
 213 connection.
 214 .It Ev FTP_PASSIVE_MODE
 215 If defined, forces the use of passive mode, unless equal
 216 to ``NO'' or ``no'' in which case active mode is forced.
 217 If defined, the setting of this variable always overrides any calls to
 218 .Fn ftpPassive .
 219 .El
 220 .Sh BUGS
 221 I'm sure you can get this thing's internal state machine confused if
 222 you really work at it, but so far it's proven itself pretty robust in
 223 all my tests.
 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