DragonFly On-Line Manual Pages
FTPIO(3) DragonFly Library Functions Manual FTPIO(3)
NAME
ftpLogin, ftpChdir, ftpErrno, ftpErrString, ftpGetModtime, ftpGetSize,
ftpGet, ftpPut, ftpAscii, ftpBinary, ftpPassive, ftpVerbose, ftpGetURL,
ftpPutURL, ftpLoginAf, ftpGetURLAf, ftpPutURLAf -- FTPIO user library
LIBRARY
FTP Connection Management Library (libftpio, -lftpio)
SYNOPSIS
#include <ftpio.h>
FILE *
ftpLogin(const char *host, const char *user, const 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, const char *file);
off_t
ftpGetSize(FILE *stream, const char *file);
FILE *
ftpGet(FILE *stream, const char *file, off_t *seekto);
FILE *
ftpPut(FILE *stream, const char *file);
int
ftpAscii(FILE *stream);
int
ftpBinary(FILE *stream);
int
ftpPassive(FILE *stream, int status);
void
ftpVerbose(FILE *stream, int status);
FILE *
ftpGetURL(const char *url, const char *user, const char *passwd,
int *retcode);
FILE *
ftpPutURL(const char *url, const char *user, const char *passwd,
int *retcode);
FILE *
ftpLoginAf(const char *host, int af, const char *user,
const char *passwd, int ftp_port, int verbose, int *retcode);
FILE *
ftpGetURLAf(const char *url, int af, const char *user,
const char *passwd, int *retcode);
FILE *
ftpPutURLAf(const char *url, int af, const char *user,
const char *passwd, int *retcode);
DESCRIPTION
These functions implement a high-level library for managing FTP connec-
tions.
ftpLogin() attempts to log in using the supplied 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 fail-
ure, NULL is returned and retcode will have the error code returned by
the foreign server.
ftpChdir() attempts to issue a server CD command to the directory named
in dir. On success, zero is returned. On failure, the error code from
the server.
ftpErrno() returns the server failure code for the last operation (useful
for seeing more about what happened if you're familiar with FTP error
codes). ftpErrString() returns a human readable version of the supplied
server failure code.
ftpGet() attempts to retrieve the file named by the file argument (which
is assumed to be relative to the FTP server's current directory, see
ftpChdir()) and returns a new FILE* pointer for the file or NULL on fail-
ure. 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 opera-
tion fails, the value of *seekto will be zero'd.
ftpGetModtime() 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.
ftpGetSize() 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.
ftpPut() attempts to create a new file named by the file argument (which
is assumed to be relative to the FTP server's current directory, see
ftpChdir()) and returns a new stream pointer for the file or NULL on
failure.
ftpAscii() sets ASCII mode for the current server connection named by
stream.
ftpBinary() sets binary mode for the current server connection named by
stream.
ftpPassive() sets passive mode (for firewalls) for the current server
connection named by stream to boolean value status.
ftpVerbose() sets the verbosity mode for the current server connection
named by stream to boolean value status.
ftpGetURL() 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.
ftpPutURL() 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 writ-
ten. Use the lower-level routines if multiple puts are required as it
will be far more efficient.
ftpLoginAf(), ftpGetURLAf(), ftpPutURLAf() 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 system installa-
tion utility, later significantly mutated into a more general 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'm sure you can get this thing's internal state machine confused if you
really work at it, but so far it's proven itself pretty robust in all my
tests.
DragonFly 3.5 June 17, 1996 DragonFly 3.5