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