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