ftp_connect(3)

NAME
ftp_connect, ftp_login, ftp_quit, ftp_fd - manage FTP connections

SYNOPSIS
#include <libfget.h>

typedef void (*ftp_hookfunc_t)(char *);

int ftp_connect(FTP **ftp, char *hostname, char *banner, size_t bannersize, unsigned short flags, time_t timeout, long cache_maxsize, time_t cache_expire, ftp_hookfunc_t sendhook, ftp_hookfunc_t recvhook);

int ftp_login(FTP *ftp, char *login, char *pass);

int ftp_quit(FTP *ftp, unsigned short flags);

int ftp_fd(FTP *ftp);

int ftp_data_fd(FTP *ftp);

VERSION
This man page documents version 1.2 of libfget.

DESCRIPTION
The ftp_connect() function connects to the FTP server on hostname. If hostname is suffixed with the string ":port", then port is used instead of the default FTP port. The welcome banner sent by the server is written to the buffer pointed to by banner, which will be at most bannersize bytes (including the trailing NUL).

The ftp_connect() function allocates memory for an FTP handle and sets the ftp argument to point to the allocated handle. The handle can then be passed to other libfget calls to access files on the server.

The flags argument is a bitwise-or of zero or more of the following values:

FTP_PASSIVE
    Use passive mode for data transfers.

FTP_ROUNDROBIN
    If server is a round-robin DNS entry, try all IP addresses before giving up.

The timeout argument specifies the number of seconds to wait for I/O operations with the FTP server to complete. A value of 0 means no timeout. This value is used by all libfget functions for all communication with the FTP server, and can be changed after the handle is created via the ftp_set_io_timeout(3) function. If the timeout elapses before the operation is finished, the function will return with errno set to ETIMEDOUT.

The cache_maxsize argument specifies the maximum number of valid directory entries to be cached at any given time. If set to -1, there is no limit.

The cache_expire argument specifies the maximum number of seconds a directory cache entry is valid for. If a cache entry is found which is older than this value, the directory is refreshed from the server. If set to -1, there is no limit.

The sendhook and recvhook functions are used for debugging. For more information on these arguments, see ftp_set_sendhook(3) and ftp_set_recvhook(3).

The ftp_quit() function closes the FTP connection and frees memory associated with ftp. If flags is set to FTP_FASTCLOSE, the connection is closed without sending the FTP "quit" command.

The ftp_login() function attempts to login to the server as user login with password pass.

The ftp_fd() function returns the file descriptor of the FTP control connection associated with the FTP handle ftp.

The ftp_data_fd() function returns the file descriptor of the FTP data connection associated with the FTP handle ftp.

RETURN VALUE
On successful completion, ftp_connect(), ftp_quit(), and ftp_login() will return 0. On failure, they will return -1 and set errno to an appropriate value.

If errno is set to ECONNRESET, it indicates that the server shut down the connection. The caller is then responsible for calling ftp_quit() with the FTP_FASTCLOSE flag set.

The ftp_fd() function returns the file descriptor of the FTP control connection associated with the FTP handle ftp. It cannot fail.

The ftp_data_fd() function returns the file descriptor of the FTP data connection associated with the FTP handle ftp. It cannot fail.

SEE ALSO
ftp_open(3), ftp_set_sendhook(3), ftp_set_recvhook(3)