ftp_set_options(3) C Library Calls ftp_set_options(3)NAME
ftp_set_options, ftp_get_options - set or get options for an FTP handle
SYNOPSIS
#include <libfget.h>
void ftp_set_options(FTP *ftp, ...);
void ftp_get_options(FTP *ftp, ...);
VERSION
This man page documents version 1.3 of libfget.
DESCRIPTION
The ftp_set_options() and ftp_get_options() functions allow the appli‐
cation to set or get options associated with the FTP handle ftp.
For the ftp_set_options() function, additional arguments must be speci‐
fied in pairs, where the first argument indicates which option to set,
and the second argument indicates the value for the specified option.
The type of the value argument depends upon the particular option (see
below). After all desired option arguments have been specified, the
final argument to ftp_set_options() must be a 0.
For the ftp_get_options() function, additional arguments must be speci‐
fied in pairs, where the first argument indicates which option to get,
and the second argument is a pointer to a variable which will be set to
the current value of the requested option. The type of the value vari‐
able depends upon the particular option (see below). After all desired
option arguments have been specified, the final argument to
ftp_get_options() must be a 0.
The supported options (along with their respective value types and
defaults) are as follows:
FTP_OPT_PASSIVE (unsigned short, 1)
A boolean value indicating whether passive mode should be used
for data transfers.
FTP_OPT_USE_MLST (unsigned short, 0)
A boolean value indicating whether the MLST/MLSD protocol exten‐
sion should be used to request directory listings from servers
that support it.
Note that this feature should be considered experimental, and is
disabled by default. In particular, there are a number of prob‐
lems identifying symlinks in an MLSD listing.
FTP_OPT_USE_ABOR (unsigned short, 0)
A boolean value indicating whether the ABOR command should be
used to abort file transfers. By default, file transfers will
be aborted by simply closing the data connection and waiting for
the server to send an error response.
FTP_OPT_IO_TIMEOUT (time_t, -1)
Sets the number of seconds to wait for I/O operations with the
FTP server to complete. A value of -1 means no timeout
(although the kernel may still enforce timeouts for certain
operations, such as establishing a new TCP connection). This
value is used by all libfget functions for all communication
with the FTP server. If the timeout elapses before the opera‐
tion is finished, the function will return with errno set to
ETIMEDOUT.
FTP_OPT_CACHE_MAXSIZE (long, -1)
Specifies the maximum number of valid directory entries to be
cached at any given time. If set to -1, there is no limit.
FTP_OPT_CACHE_EXPIRE (long, -1)
Specifies the maximum number of seconds for which a directory
cache entry is valid. 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.
FTP_OPT_SEND_HOOK, FTP_OPT_RECV_HOOK (ftp_hookfunc_t, NULL)
Specifies the send and receive hook functions, which are typi‐
cally used by the application to monitor and debug the protocol-
level communication between libfget and the FTP server. The
hook functions are of the following type:
typedef void (*ftp_hookfunc_t)(char *, FTP *, void *);
When each line of data is sent to or received from the FTP
server, the appropriate function is called. Its first argument
is a pointer to the line which was sent to or received from the
server. Its second argument is a pointer to the FTP handle
associated with the FTP server. Its third argument is an appli‐
cation data pointer which can optionally be supplied by the
application to point to any application-specific data (see the
FTP_OPT_HOOK_DATA option, below).
To unset the send and receive hooks, the FTP_OPT_SEND_HOOK and
FTP_OPT_RECV_HOOK options can be set to NULL.
FTP_OPT_HOOK_DATA (void *, NULL)
Specifies the application data pointer to be passed to the send
and receive hook functions (see the FTP_OPT_SEND_HOOK and
FTP_OPT_RECV_HOOK options, above).
Note that options can also be set by passing option arguments to the
ftp_connect(3) function when the FTP handle is created.
EXAMPLE
The following code shows how to set the FTP_OPT_USE_ABOR and
FTP_OPT_CACHE_EXPIRE options:
ftp_set_options(ftp,
FTP_OPT_USE_ABOR, (unsigned short)1,
FTP_OPT_CACHE_EXPIRE, (long)600, /* 10 mins */
0);
The following code shows how to get the current value of the
FTP_OPT_CACHE_MAXSIZE option:
long cache_max_size;
ftp_get_options(ftp,
FTP_OPT_CACHE_MAXSIZE, &cache_max_size,
0);
SEE ALSOlibfget(3), ftp_connect(3)Feep Networks January 2004 ftp_set_options(3)
