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