.TH libfget 3 "January 2004" "Feep Networks" "C Library Calls"
.SH NAME
libfget - FTP client library
.SH VERSION
This man page documents version 1.3 of \fBlibfget\fP.
.SH DESCRIPTION
This document is an overview on how to use the \fBlibfget\fP library
in a C program.  There are specific man pages for each function
mentioned here.

To begin using \fBlibfget\fP, the application must call the
\fBftp_connect\fP(3) function to establish a connection to an FTP server.
This should be immediately followed by calling \fBftp_login\fP(3)
to authenticate to the server.

Once a connection is established, \fBlibfget\fP provides a number of
functions for accessing files on the server.  The \fBlibfget\fP API is
designed to closely resemble the normal Unix filesystem API, so that it
will be familiar to many application developers.  A list of functions
provided by \fBlibfget\fP is included below.

After all communication with the FTP server is complete, the application
should call \fBftp_quit\fP(3) to terminate the connection and free any
allocated memory.
.SH FUNCTION LIST
In the following list, the functions marked with "[1]" are those
that can be safely called while a file transfer is in progress.
The functions marked with "[2]" are those that may or may not succeed
while a file transfer is in progress.  For more information, see the
\fBDATA CONNECTIONS\fP section below.

The following connection management functions are provided:

.RS
.BR ftp_connect (3)
.br
.BR ftp_login (3)
.br
.BR ftp_quit (3)
.br
.BR ftp_set_options "(3) [1]"
.br
.BR ftp_get_options "(3) [1]"
.br
.BR ftp_whoami "(3) [1]"
.br
.BR ftp_get_host "(3) [1]"
.br
.BR ftp_fd "(3) [1]"
.br
.BR ftp_data_fd "(3) [1]"
.br
.BR ftp_url_parse "(3) [1]"
.RE

The directory access functions are:

.RS
.BR ftp_opendir "(3) [2]"
.br
.BR ftp_readdir "(3) [1]"
.br
.BR ftp_rewinddir "(3) [1]"
.br
.BR ftp_telldir "(3) [1]"
.br
.BR ftp_seekdir "(3) [1]"
.br
.BR ftp_closedir "(3) [1]"
.RE

The directory modification functions are:

.RS
.BR ftp_rename (3)
.br
.BR ftp_unlink (3)
.br
.BR ftp_mkdir (3)
.br
.BR ftp_rmdir (3)
.br
.BR ftp_remove (3)
.RE

The directory navigation functions are:

.RS
.BR ftp_chdir (3)
.br
.BR ftp_getcwd "(3) [1]"
.RE

The file access functions are:

.RS
.BR ftp_open (3)
.br
.BR ftp_read "(3) [1]"
.br
.BR ftp_write "(3) [1]"
.br
.BR ftp_lseek "(3) [1]"
.br
.BR ftp_close "(3) [1]"
.RE

The file information functions are:

.RS
.BR ftp_stat "(3) [2]"
.br
.BR ftp_lstat "(3) [2]"
.br
.BR ftp_readlink "(3) [2]"
.RE

A number of utility functions are also provided:

.RS
.BR ftp_glob "(3) [2]"
.br
.BR ftp_globfree "(3) [1]"
.br
.BR ftp_realpath "(3) [2]"
.RE

The following protocol-level functions are provided:

.RS
.BR ftp_site (3)
.br
.BR ftp_site_open (3)
.br
.BR ftp_systype "(3) [1]"
.br
.BR ftp_status (3)
.br
.BR ftp_type (3)
.RE
.SH DATA CONNECTIONS
The FTP protocol uses two seperate TCP/IP connections.  The first
connection, called the "control connection", is established when the
client first connects to the server and is used to send requests from
the client to the server.  When the client issues a request for a file
to be transfered, the second connection, called the "data connection",
is established and used to transfer the contents of the requested file.

Unfortunately, the FTP protocol does not allow any other requests to
be sent over the control connection while the data connection is open.
This means that you may not perform any other requests while you are in
the middle of transferring a file to or from the FTP server.

In the \fBlibfget\fP API, all file transfers are represented by
\fBFTPFILE\fP handles.  The data connection is established when
you obtain a new \fBFTPFILE\fP handle by calling \fBftp_open\fP(3)
(or \fBftp_site_open\fP(3)), and it remains open until you call
\fBftp_close\fP(3) on that handle.  In between those two calls, you
may not call any \fBlibfget\fP functions that would result in a request
being issued to the server.

During a file transfer, you may safely call any of the functions in the
previous section that are marked with a "[1]".

Many functions (those marked with a "[2]" in the previous section)
take advantage of \fBlibfget\fP's built-in directory cache.  For these
functions, if the requested data is available in the cache, these
functions may be able to return that data without needing to issue
a request to the FTP server.  This means that, in many cases, these
functions may succeed even when an \fBFTPFILE\fP handle is open.  However,
applications should not rely on this behavior, since the API does not
provide any guaruntee about whether or not a given piece of information
is in the cache at any given time, and the behavior may change as the
underlying directory cache implementation changes.

Any \fBlibfget\fP function that needs to send a request to the FTP server
while an \fBFTPFILE\fP handle is open will fail.  In most cases, it will
return -1 and set \fIerrno\fP to \fBEAGAIN\fP.  Applications should be
aware that this is a temporary failure, and the operation may be retried
once the \fBFTPFILE\fP handle is closed.
.SH ERRORS
Upon failure, all \fBlibfget\fP functions set \fIerrno\fP.  The
following \fIerrno\fP values are common to all \fBlibfget\fP functions:
.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.
.TP
.B EAGAIN
An attempt was made to send a request to the server while the data
connection is open.
.PP
Almost all \fBlibfget\fP functions may also fail for any of the same
reasons as the underlying \fBpoll\fP(2), \fBread\fP(2), or \fBwrite\fP(2)
system calls.
.SH SYMBOL NAMES
All public functions in the \fBlibfget\fP interface are prefixed with
"ftp_".  You can find other functions in the library source code, but
other prefixes indicate that the functions are private and may change
without further notice in the next release.

Only use documented functions and functionality!
.SH THREAD SAFETY
The author has not tested \fBlibfget\fP in a threaded application, but
it is believed to be thread-safe on platforms that provide the necessary
reentrant library functions.  \fBlibfget\fP provides a boolean variable
called \fBlibfget_is_thread_safe\fP that can be checked at run-time to
determine whether the library was compiled with these functions.

Even when \fBlibfget_is_thread_safe\fP is true, note that you must never
call \fBlibfget\fP functions simultaneously from different threads using
the same FTP handle.  \fBlibfget\fP can be used in any number of threads,
but you must use a separate FTP handle in each thread if you want to
use \fBlibfget\fP in more than one thread at the same time.
.SH STANDARDS
The \fBlibfget\fP library complies with the following RFCs:
.TP
.B RFC-959
"File Transfer Protocol".  The original FTP specification.
.TP
.BR RFC-1123 " (section 4.1)"
"Requirements for Internet Hosts -- Application and Support".  Revisions
to RFC-959.
.TP
.B RFC-1579
"Firewall-Friendly FTP".  Recommends that all FTP clients use PASV
instead of PORT by default.
.TP
.BR RFC-1738 " (section 3.2)"
"Uniform Resource Locators (URL)".  Describes the syntax for FTP URLs.
.TP
.B RFC-2389
"Feature negotiation mechanism for the File Transfer Protocol".
Describes the FEAT and OPTS extensions to FTP.
.TP
.B draft-ietf-ftpext-mlst-16.txt
"Extensions to FTP".  Describes the MLST and MLSD list format and the
REST STREAM extension.
.SH SEE ALSO
.BR ftp_connect (3)