DragonFly On-Line Manual Pages

ftp_connect(3)                  C Library Calls                 ftp_connect(3)

NAME
       ftp_connect, ftp_login, ftp_quit - manage FTP connections

SYNOPSIS
       #include <libfget.h>

       int ftp_connect(FTP **ftp, char *hostname, char *banner, size_t
       bannersize, unsigned short flags, ...);

       int ftp_login(FTP *ftp, char *login, char *pass);

       int ftp_quit(FTP *ftp, unsigned short flags);

VERSION
       This man page documents version 1.3 of libfget.

DESCRIPTION
       The ftp_connect() function connects to an FTP server and creates an FTP
       handle for the connection.  Upon successful completion, the pointer
       pointed to by ftp will be set to point to the new handle.  The handle
       can then be passed to other libfget calls to access files on the
       server.

       The ftp_connect() function connects to the FTP server on hostname.  If
       hostname is suffixed with the string ":port", then port is used instead
       of the default FTP port.

       The banner argument points to a buffer of size bannersize.  If banner
       is not NULL, the welcome banner sent by the FTP server will be written
       to this buffer.  If the message is longer than bannersize bytes, it
       will be silently truncated.

       The flags argument is a bitmask of zero or more of the following
       values:

       FTP_CONNECT_DNS_RR
              If hostname is a round-robin DNS entry, try all IP addresses
              before giving up.

       Additional arguments may be specified after the flags argument to set
       libfget options for the resulting FTP handle.  Arguments must be
       specified in pairs, where the first argument indicates which option is
       being set, and the second argument indicates the value for the
       specified option.  The type of the value argument depends upon the
       particular option; for a complete list of options, see
       ftp_set_options(3).  After all desired option arguments have been
       specified, the final argument to ftp_connect() must be a 0.

       The ftp_login() function attempts to login to the server as user login
       with password pass.  It should be called right after a successful call
       to ftp_connect().

       The ftp_quit() function closes the FTP connection and frees memory
       associated with ftp.  The flags argument is a bitmask of zero or more
       of the following values:

       FTP_QUIT_FAST
              Close the connection without sending the FTP "quit" command.

RETURN VALUE
       On successful completion, ftp_connect(), ftp_quit(), and ftp_login()
       return 0.  On failure, they return -1 and set errno to an appropriate
       value.

ERRORS
       The ftp_connect(), ftp_quit(), and ftp_login() functions fail if:

       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.

       They may also fail for any of the errors specified for the underlying
       poll(2), send(2), write(2), or read(2) system calls.

       The ftp_connect() function fails if:

       EINVAL Unknown hostname specified.

       EINVAL Unknown service name specified for port number.

       It also fails for any of the errors specified for the underlying
       socket(2), connect(2), fcntl(2) (using F_GETFL and F_SETFL), or
       calloc(3) system and library calls.

       The ftp_login() function fails if:

       EACCES Authentication failed.

EXAMPLE
       The following code shows how to establish a connection to an FTP
       server:

              FTP *ftp;
              char buf[1024];

              /* connect to the FTP server */
              if (ftp_connect(&ftp, "ftp.example.com", buf, sizeof(buf),
                        FTP_CONNECT_DNS_RR, 0) == -1)
              {
                   perror("ftp_connect()");
                   exit(1);
              }

              /* login as anonymous */
              if (ftp_login(ftp, "anonymous", "roth@feep.net") == -1)
              {
                   perror("ftp_login()");
                   exit(1);
              }

              /* ... perform FTP operations here ... */

              /* now disconnect */
              if (ftp_quit(ftp, 0) == -1)
              {
                   perror("ftp_quit()");
                   exit(1);
              }

SEE ALSO
       libfget(3), ftp_set_options(3)

Feep Networks                    January 2004                   ftp_connect(3)