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