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
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.5 2008/05/04 00:55:01 swildner Exp $
49 .Nd FTPIO user library
55 .Fn ftpLogin "char *host" "char *user" "char *passwd" "int ftp_port" "int verbose" "int *retcode"
57 .Fn ftpChdir "FILE *stream" "char *dirname"
59 .Fn ftpErrno "FILE *stream"
61 .Fn ftpErrString "int errno"
63 .Fn ftpGetModtime "FILE *stream" "char *file"
65 .Fn ftpGetSize "FILE *stream" "char *file"
67 .Fn ftpGet "FILE *stream" "char *file" "off_t *seekto"
69 .Fn ftpPut "FILE *stream" "char *file"
71 .Fn ftpAscii "FILE *stream"
73 .Fn ftpBinary "FILE *stream"
75 .Fn ftpPassive "FILE *stream" "int status"
77 .Fn ftpVerbose "FILE *stream" "int status"
79 .Fn ftpGetURL "char *url" "char *user" "char *passwd" "int *retcode"
81 .Fn ftpPutURL "char *url" "char *user" "char *passwd" "int *retcode"
83 .Fn ftpLoginAf "char *host" "int af" "char *user" "char *passwd" "int ftp_port" "int verbose" "int *retcode"
85 .Fn ftpGetURLAf "char *url" "int af" "char *user" "char *passwd" "int *retcode"
87 .Fn ftpPutURLAf "char *url" "int af" "char *user" "char *passwd" "int *retcode"
89 These functions implement a high-level library for managing FTP connections.
92 attempts to log in using the supplied
98 defaults to the standard ftp port of 21) and
100 fields. If it is successful, a
101 standard stream descriptor is returned which should be passed to
102 subsequent FTP operations.
103 On failure, NULL is returned and
105 will have the error code returned by the foreign server.
108 attempts to issue a server CD command to the directory named in
110 On success, zero is returned. On failure, the error code from the server.
113 returns the server failure code for the last operation (useful for seeing
114 more about what happened if you're familiar with FTP error codes).
116 returns a human readable version of the supplied server failure code.
119 attempts to retrieve the file named by the
121 argument (which is assumed to be relative to the FTP server's current directory,
124 and returns a new FILE* pointer for the file or NULL on failure. If
126 is non-NULL, the contents of the integer it points to will be used
127 as a restart point for the file, that is to say that the stream
130 bytes into the file gotten (this is handy for restarting failed
131 transfers efficiently). If the seek operation fails, the value
137 returns the last modification time of the file named by the
139 argument. If the file could not be opened or stat'd, 0 is returned.
142 returns the size in bytes of the file named by the
144 argument. If the file could not be opened or stat'd, -1 is returned.
147 attempts to create a new file named by the
149 argument (which is assumed to be relative to the FTP server's current directory,
154 pointer for the file or NULL on failure.
157 sets ASCII mode for the current server connection named by
161 sets binary mode for the current server connection named by
165 sets passive mode (for firewalls) for the current server connection named by
171 sets the verbosity mode for the current server connection named by
177 attempts to retrieve the file named by the supplied
179 and can be considered equivalent to the combined
184 operations except that no server
186 is ever returned - the connection to the server closes when
187 the file has been completely read. Use the lower-level routines
188 if multiple gets are required as it will be far more efficient.
191 attempts to create the file named by the supplied
193 and can be considered equivalent to the combined
198 operations except that no server stream is ever returned - the connection
199 to the server closes when the file has been completely written. Use the
200 lower-level routines if multiple puts are required as it will be far more
210 except that they are able to specify address family
213 .Bl -tag -width FTP_PASSIVE_MODE -offset 3n
215 Maximum time, in seconds, to wait for a response
216 from the peer before aborting an
219 .It Ev FTP_PASSIVE_MODE
220 If defined, forces the use of passive mode, unless equal
221 to ``NO'' or ``no'' in which case active mode is forced.
222 If defined, the setting of this variable always overrides any calls to
226 Started life as Poul-Henning Kamp's ftp driver for the system installation
227 utility, later significantly mutated into a more general form as an
228 extension of stdio by Jordan Hubbard. Also incorporates some ideas and
229 extensions from Jean-Marc Zucconi.
232 .An Poul-Henning Kamp
234 .An Jean-Marc Zucconi
236 I'm sure you can get this thing's internal state machine confused if
237 you really work at it, but so far it's proven itself pretty robust in