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