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.3 2006/02/17 19:35:07 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 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 HISTORY 222Started life as Poul-Henning Kamp's ftp driver for the system installation 223utility, later significantly mutated into a more general form as an 224extension of stdio by Jordan Hubbard. Also incorporates some ideas and 225extensions from Jean-Marc Zucconi. 226.Sh AUTHORS 227.An Jordan Hubbard , 228.An Poul-Henning Kamp 229and 230.An Jean-Marc Zucconi 231.Sh BUGS 232I'm sure you can get this thing's internal state machine confused if 233you really work at it, but so far it's proven itself pretty robust in 234all my tests. 235