DragonFly On-Line Manual Pages
libfget(3) C Library Calls libfget(3)
NAME
libfget - FTP client library
VERSION
This man page documents version 1.3 of libfget.
DESCRIPTION
This document is an overview on how to use the libfget library in a C
program. There are specific man pages for each function mentioned
here.
To begin using libfget, the application must call the ftp_connect(3)
function to establish a connection to an FTP server. This should be
immediately followed by calling ftp_login(3) to authenticate to the
server.
Once a connection is established, libfget provides a number of
functions for accessing files on the server. The libfget 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 libfget is included below.
After all communication with the FTP server is complete, the
application should call ftp_quit(3) to terminate the connection and
free any allocated memory.
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 DATA
CONNECTIONS section below.
The following connection management functions are provided:
ftp_connect(3)
ftp_login(3)
ftp_quit(3)
ftp_set_options(3) [1]
ftp_get_options(3) [1]
ftp_whoami(3) [1]
ftp_get_host(3) [1]
ftp_fd(3) [1]
ftp_data_fd(3) [1]
ftp_url_parse(3) [1]
The directory access functions are:
ftp_opendir(3) [2]
ftp_readdir(3) [1]
ftp_rewinddir(3) [1]
ftp_telldir(3) [1]
ftp_seekdir(3) [1]
ftp_closedir(3) [1]
The directory modification functions are:
ftp_rename(3)
ftp_unlink(3)
ftp_mkdir(3)
ftp_rmdir(3)
ftp_remove(3)
The directory navigation functions are:
ftp_chdir(3)
ftp_getcwd(3) [1]
The file access functions are:
ftp_open(3)
ftp_read(3) [1]
ftp_write(3) [1]
ftp_lseek(3) [1]
ftp_close(3) [1]
The file information functions are:
ftp_stat(3) [2]
ftp_lstat(3) [2]
ftp_readlink(3) [2]
A number of utility functions are also provided:
ftp_glob(3) [2]
ftp_globfree(3) [1]
ftp_realpath(3) [2]
The following protocol-level functions are provided:
ftp_site(3)
ftp_site_open(3)
ftp_systype(3) [1]
ftp_status(3)
ftp_type(3)
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 libfget API, all file transfers are represented by FTPFILE
handles. The data connection is established when you obtain a new
FTPFILE handle by calling ftp_open(3) (or ftp_site_open(3)), and it
remains open until you call ftp_close(3) on that handle. In between
those two calls, you may not call any libfget 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 libfget'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 FTPFILE 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 libfget function that needs to send a request to the FTP server
while an FTPFILE handle is open will fail. In most cases, it will
return -1 and set errno to EAGAIN. Applications should be aware that
this is a temporary failure, and the operation may be retried once the
FTPFILE handle is closed.
ERRORS
Upon failure, all libfget functions set errno. The following errno
values are common to all libfget functions:
ECONNRESET
The server shut down the connection. The caller is then
responsible 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.
EAGAIN An attempt was made to send a request to the server while the
data connection is open.
Almost all libfget functions may also fail for any of the same reasons
as the underlying poll(2), read(2), or write(2) system calls.
SYMBOL NAMES
All public functions in the libfget 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!
THREAD SAFETY
The author has not tested libfget in a threaded application, but it is
believed to be thread-safe on platforms that provide the necessary
reentrant library functions. libfget provides a boolean variable
called libfget_is_thread_safe that can be checked at run-time to
determine whether the library was compiled with these functions.
Even when libfget_is_thread_safe is true, note that you must never call
libfget functions simultaneously from different threads using the same
FTP handle. libfget can be used in any number of threads, but you must
use a separate FTP handle in each thread if you want to use libfget in
more than one thread at the same time.
STANDARDS
The libfget library complies with the following RFCs:
RFC-959
"File Transfer Protocol". The original FTP specification.
RFC-1123 (section 4.1)
"Requirements for Internet Hosts -- Application and Support".
Revisions to RFC-959.
RFC-1579
"Firewall-Friendly FTP". Recommends that all FTP clients use
PASV instead of PORT by default.
RFC-1738 (section 3.2)
"Uniform Resource Locators (URL)". Describes the syntax for FTP
URLs.
RFC-2389
"Feature negotiation mechanism for the File Transfer Protocol".
Describes the FEAT and OPTS extensions to FTP.
draft-ietf-ftpext-mlst-16.txt
"Extensions to FTP". Describes the MLST and MLSD list format
and the REST STREAM extension.
SEE ALSO
ftp_connect(3)
Feep Networks January 2004 libfget(3)