ftp_connect(3) C Library Calls ftp_connect(3)NAME
ftp_connect, ftp_login, ftp_quit - manage FTP connections
SYNOPSIS
#include <libfget.h>
int ftp_connect(FTP **ftp, char *hostname, char *banner, size_t banner‐
size, unsigned short flags, ...);
int ftp_login(FTP *ftp, char *login, char *pass);
int ftp_quit(FTP *ftp, unsigned short flags);
VERSION
This man page documents version 1.3 of libfget.
DESCRIPTION
The ftp_connect() function connects to an FTP server and creates an FTP
handle for the connection. Upon successful completion, the pointer
pointed to by ftp will be set to point to the new handle. The handle
can then be passed to other libfget calls to access files on the
server.
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 banner argument points to a buffer of size bannersize. If banner
is not NULL, the welcome banner sent by the FTP server will be written
to this buffer. If the message is longer than bannersize bytes, it
will be silently truncated.
The flags argument is a bitmask of zero or more of the following val‐
ues:
FTP_CONNECT_DNS_RR
If hostname is a round-robin DNS entry, try all IP addresses
before giving up.
Additional arguments may be specified after the flags argument to set
libfget options for the resulting FTP handle. Arguments must be speci‐
fied in pairs, where the first argument indicates which option is being
set, and the second argument indicates the value for the specified
option. The type of the value argument depends upon the particular
option; for a complete list of options, see ftp_set_options(3). After
all desired option arguments have been specified, the final argument to
ftp_connect() must be a 0.
The ftp_login() function attempts to login to the server as user login
with password pass. It should be called right after a successful call
to ftp_connect().
The ftp_quit() function closes the FTP connection and frees memory
associated with ftp. The flags argument is a bitmask of zero or more
of the following values:
FTP_QUIT_FAST
Close the connection without sending the FTP "quit" command.
RETURN VALUE
On successful completion, ftp_connect(), ftp_quit(), and ftp_login()
return 0. On failure, they return -1 and set errno to an appropriate
value.
ERRORS
The ftp_connect(), ftp_quit(), and ftp_login() functions fail if:
ECONNRESET
The server shut down the connection. The caller is then respon‐
sible for calling ftp_quit() with the FTP_QUIT_FAST flag set.
ETIMEDOUT
The operation timed out. (The timeout interval can be set via
the FTP_OPT_IO_TIMEOUT option; see the ftp_set_options(3) man
page for details.)
EINVAL Unexpected response code received from server.
They may also fail for any of the errors specified for the underlying
poll(2), send(2), write(2), or read(2) system calls.
The ftp_connect() function fails if:
EINVAL Unknown hostname specified.
EINVAL Unknown service name specified for port number.
It also fails for any of the errors specified for the underlying
socket(2), connect(2), fcntl(2) (using F_GETFL and F_SETFL), or cal‐
loc(3) system and library calls.
The ftp_login() function fails if:
EACCES Authentication failed.
EXAMPLE
The following code shows how to establish a connection to an FTP
server:
FTP *ftp;
char buf[1024];
/* connect to the FTP server */
if (ftp_connect(&ftp, "ftp.example.com", buf, sizeof(buf),
FTP_CONNECT_DNS_RR, 0) == -1)
{
perror("ftp_connect()");
exit(1);
}
/* login as anonymous */
if (ftp_login(ftp, "anonymous", "roth@feep.net") == -1)
{
perror("ftp_login()");
exit(1);
}
/* ... perform FTP operations here ... */
/* now disconnect */
if (ftp_quit(ftp, 0) == -1)
{
perror("ftp_quit()");
exit(1);
}
SEE ALSOlibfget(3), ftp_set_options(3)Feep Networks January 2004 ftp_connect(3)
