DragonFly On-Line Manual Pages

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)