.TH ftp_connect 3 "January 2004" "Feep Networks" "C Library Calls"
.SH NAME
ftp_connect, ftp_login, ftp_quit \- manage FTP connections
.SH SYNOPSIS
.B #include <libfget.h>

.BI "int ftp_connect(FTP **" ftp ", char *" hostname ","
.BI "char *" banner ", size_t " bannersize ","
.BI "unsigned short " flags ", ...);"

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

.BI "int ftp_quit(FTP *" ftp ", unsigned short " flags ");"
.SH VERSION
This man page documents version 1.3 of \fBlibfget\fP.
.SH DESCRIPTION
The \fBftp_connect\fP() function connects to an FTP server and creates
an \fBFTP\fP handle for the connection.  Upon successful completion, the
pointer pointed to by \fIftp\fP will be set to point to the new handle.
The handle can then be passed to other \fBlibfget\fP calls to access
files on the server.

The \fBftp_connect\fP() function connects to the FTP server on
\fIhostname\fP.  If \fIhostname\fP is suffixed with the string
":\fIport\fP", then \fIport\fP is used instead of the default FTP port.

The \fIbanner\fP argument points to a buffer of size \fIbannersize\fP.
If \fIbanner\fP is not \fBNULL\fP, the welcome banner sent by the FTP
server will be written to this buffer.  If the message is longer than
\fIbannersize\fP bytes, it will be silently truncated.

The \fIflags\fP argument is a bitmask of zero or more of the
following values:
.TP
.B FTP_CONNECT_DNS_RR
If \fIhostname\fP is a round-robin DNS entry, try all IP addresses
before giving up.
.PP
Additional arguments may be specified after the \fIflags\fP
argument to set \fBlibfget\fP options for the resulting \fBFTP\fP
handle.  Arguments must be specified 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 \fBftp_set_options\fP(3).  After all desired option arguments have
been specified, the final argument to \fBftp_connect\fP() must be a 0.

The \fBftp_login\fP() function attempts to login to the server as user
\fIlogin\fP with password \fIpass\fP.  It should be called right
after a successful call to \fBftp_connect\fP().

The \fBftp_quit\fP() function closes the FTP connection and frees
memory associated with \fIftp\fP.  The \fIflags\fP argument is a bitmask
of zero or more of the following values:
.TP
.B FTP_QUIT_FAST
Close the connection without sending the FTP "quit" command.
.PP
.SH RETURN VALUE
On successful completion, \fBftp_connect\fP(), \fBftp_quit\fP(), and
\fBftp_login\fP() return 0.  On failure, they return -1 and
set \fIerrno\fP to an appropriate value.
.SH ERRORS
The \fBftp_connect\fP(), \fBftp_quit\fP(), and \fBftp_login\fP()
functions fail if:
.TP
.B ECONNRESET
The server shut down the connection.  The caller is then responsible
for calling \fBftp_quit\fP() with the \fBFTP_QUIT_FAST\fP flag set.
.TP
.B ETIMEDOUT
The operation timed out.  (The timeout interval can be set via the
\fBFTP_OPT_IO_TIMEOUT\fP option; see the \fBftp_set_options\fP(3) man 
page for details.)
.TP
.B EINVAL
Unexpected response code received from server.
.PP
They may also fail for any of the errors specified for the underlying
\fBpoll\fP(2), \fBsend\fP(2), \fBwrite\fP(2), or \fBread\fP(2) system
calls.

The \fBftp_connect\fP() function fails if:
.TP
.B EINVAL
Unknown hostname specified.
.TP
.B EINVAL
Unknown service name specified for port number.
.PP
It also fails for any of the errors specified for the underlying
\fBsocket\fP(2), \fBconnect\fP(2), \fBfcntl\fP(2) (using \fBF_GETFL\fP
and \fBF_SETFL\fP), or \fBcalloc\fP(3) system and library calls.

The \fBftp_login\fP() function fails if:
.TP
.B EACCES
Authentication failed.
.SH EXAMPLE
The following code shows how to establish a connection to an FTP server:

.RS
.nf
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);
}
.fi
.RE
.SH SEE ALSO
.BR libfget (3),
.BR ftp_set_options (3)