.TH ftp_set_options 3 "January 2004" "Feep Networks" "C Library Calls"
.SH NAME
ftp_set_options, ftp_get_options \- set or get options for an FTP handle
.SH SYNOPSIS
.B #include <libfget.h>

.BI "void ftp_set_options(FTP *" ftp ", ...);"

.BI "void ftp_get_options(FTP *" ftp ", ...);"
.SH VERSION
This man page documents version 1.3 of \fBlibfget\fP.
.SH DESCRIPTION
The \fBftp_set_options\fP() and \fBftp_get_options\fP() functions allow
the application to set or get options associated with the \fBFTP\fP
handle \fIftp\fP.

For the \fBftp_set_options\fP() 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 \fBftp_set_options\fP() must be a 0.

For the \fBftp_get_options\fP() 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
\fBftp_get_options\fP() must be a 0.

The supported options (along with their respective value types and
defaults) are as follows:
.TP
.BR FTP_OPT_PASSIVE " (unsigned short, 1)"
A boolean value indicating whether passive mode should be used for data
transfers.
.TP
.BR 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.
.TP
.BR 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.
.TP
.BR 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 \fBlibfget\fP functions for
all communication with the FTP server.  If the timeout elapses before
the operation is finished, the function will return with \fIerrno\fP
set to \fBETIMEDOUT\fP.
.TP
.BR 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.
.TP
.BR 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.
.TP
.BR 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 \fBlibfget\fP and the FTP server.  The hook functions are of the
following type:

.RS
.RS
.BI "typedef void (*" ftp_hookfunc_t ")(char *, FTP *, void *);"
.RE

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 \fBFTP\fP 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 \fBFTP_OPT_HOOK_DATA\fP option, below).

To unset the send and receive hooks, the \fBFTP_OPT_SEND_HOOK\fP and
\fBFTP_OPT_RECV_HOOK\fP options can be set to \fBNULL\fP.
.RE
.TP
.BR FTP_OPT_HOOK_DATA " (void *, NULL)"
Specifies the application data pointer to be passed to the send and
receive hook functions (see the \fBFTP_OPT_SEND_HOOK\fP and
\fBFTP_OPT_RECV_HOOK\fP options, above).
.PP
Note that options can also be set by passing option arguments to the
\fBftp_connect\fP(3) function when the FTP handle is created.
.SH EXAMPLE
The following code shows how to set the \fBFTP_OPT_USE_ABOR\fP and
\fBFTP_OPT_CACHE_EXPIRE\fP options:

.RS
.nf
ftp_set_options(ftp,
		FTP_OPT_USE_ABOR,	(unsigned short)1,
		FTP_OPT_CACHE_EXPIRE,	(long)600,	/* 10 mins */
		0);
.fi
.RE

The following code shows how to get the current value of the
\fBFTP_OPT_CACHE_MAXSIZE\fP option:

.RS
.nf
long cache_max_size;

ftp_get_options(ftp,
		FTP_OPT_CACHE_MAXSIZE,	&cache_max_size,
		0);
.fi
.RE
.SH SEE ALSO
.BR libfget (3),
.BR ftp_connect (3)