ftpio(3)

NAME

ftpLogin, ftpChdir, ftpErrno, ftpGetModtime, ftpGetSize,

ftpGet, ftpPut,
ftpBinary, ftpPassive, ftpVerbose, ftpGetURL, ftpPutURL,

ftpLoginAf,
ftpGetURLAf, ftpPutURLAf - FTPIO user library

SYNOPSIS

#include <ftpio.h>
FILE *
ftpLogin(char *host, char *user, char *passwd, int ftp_port,
int verbose,
        int *retcode);
int
ftpChdir(FILE *stream, char *dirname);
int
ftpErrno(FILE *stream);
const char *
ftpErrString(int errno);
time_t
ftpGetModtime(FILE *stream, char *file);
off_t
ftpGetSize(FILE *stream, char *file);
FILE *
ftpGet(FILE *stream, char *file, off_t *seekto);
FILE *
ftpPut(FILE *stream, char *file);
int
ftpAscii(FILE *stream);
int
ftpBinary(FILE *stream);
int
ftpPassive(FILE *stream, int status);
void
ftpVerbose(FILE *stream, int status);
FILE *
ftpGetURL(char   *url,   char   *user,   char  *passwd,  int
*retcode);
FILE *
ftpPutURL(char  *url,  char   *user,   char   *passwd,   int
*retcode);
FILE *
ftpLoginAf(char *host, int af, char *user, char *passwd, int
ftp_port,
        int verbose, int *retcode);
FILE *
ftpGetURLAf(char *url, int af, char *user, char *passwd, int
*retcode);
FILE *
ftpPutURLAf(char *url, int af, char *user, char *passwd, int
*retcode);

DESCRIPTION

These functions implement a high-level library for managing

FTP connections.

The ftpLogin() function attempts to log in using the sup

plied user,
passwd, ftp_port (if passed as 0, ftp_port defaults to the

standard ftp
port of 21) and verbose fields. If it is successful, a

standard stream
descriptor is returned which should be passed to subsequent

FTP operations. On failure, NULL is returned and retcode will have

the error code
returned by the foreign server.

The ftpChdir() function attempts to issue a server CD com

mand to the
directory named in dir. On success, zero is returned. On

failure, the
error code from the server.

The ftpErrno() function returns the server failure code for

the last
operation (useful for seeing more about what happened if you

are familiar
with FTP error codes). The ftpErrString() function returns

a human readable version of the supplied server failure code.

The ftpGet() function attempts to retrieve the file named by

the file
argument (which is assumed to be relative to the FTP serv

er's current
directory, see ftpChdir()) and returns a new FILE* pointer

for the file
or NULL on failure. If seekto is non-NULL, the contents of

the integer
it points to will be used as a restart point for the file,

that is to say
that the stream returned will point *seekto bytes into the

file gotten
(this is handy for restarting failed transfers efficiently).

If the seek
operation fails, the value of *seekto will be zero'd.

The ftpGetModtime() function returns the last modification

time of the
file named by the file argument. If the file could not be

opened or
stat'd, 0 is returned.

The ftpGetSize() function returns the size in bytes of the

file named by
the file argument. If the file could not be opened or

stat'd, -1 is
returned.

The ftpPut() function attempts to create a new file named by

the file
argument (which is assumed to be relative to the FTP serv

er's current
directory, see ftpChdir()) and returns a new stream pointer

for the file
or NULL on failure.

The ftpAscii() function sets ASCII mode for the current

server connection
named by stream.

The ftpBinary() function sets binary mode for the current

server connection named by stream.

The ftpPassive() function sets passive mode (for firewalls)

for the current server connection named by stream to boolean value

status.

The ftpVerbose() function sets the verbosity mode for the

current server
connection named by stream to boolean value status.

The ftpGetURL() function attempts to retrieve the file named

by the supplied URL and can be considered equivalent to the combined

ftpLogin(),
ftpChdir() and ftpGet() operations except that no server

stream is ever
returned - the connection to the server closes when the file

has been
completely read. Use the lower-level routines if multiple

gets are
required as it will be far more efficient.

The ftpPutURL() function attempts to create the file named

by the supplied URL and can be considered equivalent to the combined

ftpLogin(),
ftpChdir() and ftpPut() operations except that no server

stream is ever
returned - the connection to the server closes when the file

has been
completely written. Use the lower-level routines if multi

ple puts are
required as it will be far more efficient.

The ftpLoginAf(), ftpGetURLAf(), ftpPutURLAf() functions are

same as
ftpLogin(), ftpGetURL(), ftpPutURL() except that they are

able to specify
address family af.

ENVIRONMENT

FTP_TIMEOUT Maximum time, in seconds, to wait for a

response

from the peer before aborting an FTP

connection.

FTP_PASSIVE_MODE If defined, forces the use of passive

mode, unless

equal to ``NO'' or ``no'' in which case

active mode
is forced. If defined, the setting of

this variable
always overrides any calls to

ftpPassive().

HISTORY

Started life as Poul-Henning Kamp's ftp driver for the sys

tem installation utility, later significantly mutated into a more gener

al form as an
extension of stdio by Jordan Hubbard. Also incorporates

some ideas and
extensions from Jean-Marc Zucconi.

AUTHORS

Jordan Hubbard,
Poul-Henning Kamp and
Jean-Marc Zucconi

BUGS

I am sure you can get this thing's internal state machine

confused if you
really work at it, but so far it has proven itself pretty

robust in all
my tests.

BSD June 17, 1996

BSD