DragonFly On-Line Manual Pages

Search: Section:  


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 application to set or get options associated with the FTP handle ftp. For the ftp_set_options() function, additional arguments must be specified 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 specified 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 variable 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 extension 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 problems 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 operation 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 typically 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 application 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 ALSO

libfget(3), ftp_connect(3) Feep Networks January 2004 ftp_set_options(3)

Search: Section: