1 .\" Copyright (c) 1996 Jordan Hubbard <jkh@FreeBSD.org>
2 .\" All rights reserved.
4 .\" Redistribution and use in source and binary forms, with or without
5 .\" modification, are permitted provided that the following conditions
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.
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
46 .Nd FTPIO user library
50 .Fn ftpLogin "char *host" "char *user" "char *passwd" "int ftp_port" "int verbose" "int *retcode"
52 .Fn ftpChdir "FILE *stream" "char *dirname"
54 .Fn ftpErrno "FILE *stream"
56 .Fn ftpErrString "int errno"
58 .Fn ftpGetModtime "FILE *stream" "char *file"
60 .Fn ftpGetSize "FILE *stream" "char *file"
62 .Fn ftpGet "FILE *stream" "char *file" "off_t *seekto"
64 .Fn ftpPut "FILE *stream" "char *file"
66 .Fn ftpAscii "FILE *stream"
68 .Fn ftpBinary "FILE *stream"
70 .Fn ftpPassive "FILE *stream" "int status"
72 .Fn ftpVerbose "FILE *stream" "int status"
74 .Fn ftpGetURL "char *url" "char *user" "char *passwd" "int *retcode"
76 .Fn ftpPutURL "char *url" "char *user" "char *passwd" "int *retcode"
78 .Fn ftpLoginAf "char *host" "int af" "char *user" "char *passwd" "int ftp_port" "int verbose" "int *retcode"
80 .Fn ftpGetURLAf "char *url" "int af" "char *user" "char *passwd" "int *retcode"
82 .Fn ftpPutURLAf "char *url" "int af" "char *user" "char *passwd" "int *retcode"
84 These functions implement a high-level library for managing FTP connections.
88 function attempts to log in using the supplied
94 defaults to the standard ftp port of 21) and
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
102 will have the error code returned by the foreign server.
106 function attempts to issue a server CD command to the directory named in
108 On success, zero is returned.
109 On failure, the error code from the server.
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).
117 function returns a human readable version of the supplied server failure code.
121 function attempts to retrieve the file named by the
123 argument (which is assumed to be relative to the FTP server's current directory,
126 and returns a new FILE* pointer for the file or NULL on failure.
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
133 bytes into the file gotten (this is handy for restarting failed
134 transfers efficiently).
135 If the seek operation fails, the value
142 function returns the last modification time of the file named by the
145 If the file could not be opened or stat'd, 0 is returned.
149 function returns the size in bytes of the file named by the
152 If the file could not be opened or stat'd, -1 is returned.
156 function attempts to create a new file named by the
158 argument (which is assumed to be relative to the FTP server's current directory,
163 pointer for the file or NULL on failure.
169 mode for the current server connection named by
174 function sets binary mode for the current server connection named by
179 function sets passive mode (for firewalls) for the current server connection
187 function sets the verbosity mode for the current server connection named by
194 function attempts to retrieve the file named by the supplied
196 and can be considered equivalent to the combined
201 operations except that no server
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.
210 function attempts to create the file named by the supplied
212 and can be considered equivalent to the combined
217 operations except that no server stream is ever returned - the connection
218 to the server closes when the file has been completely written.
220 lower-level routines if multiple puts are required as it will be far more
227 functions are same as
231 except that they are able to specify address family
234 .Bl -tag -width FTP_PASSIVE_MODE -offset 3n
236 Maximum time, in seconds, to wait for a response
237 from the peer before aborting an
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
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.
254 .An Poul-Henning Kamp
256 .An Jean-Marc Zucconi
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