DragonFly On-Line Manual Pages

ftp_open(3)                     C Library Calls                    ftp_open(3)

NAME
       ftp_open - open a file on an FTP server

SYNOPSIS
       #include <libfget.h>

       int ftp_open(FTPFILE **ftpfile, FTP *ftp, char *file, int mode);

VERSION
       This man page documents version 1.3 of libfget.

DESCRIPTION
       The ftp_open() function opens the file file on the FTP server
       associated with ftp.  It creates an FTPFILE handle and sets ftpfile to
       point to the newly created handle.  The mode argument must be one of
       the following values:

       O_RDONLY
              The file is opened in read-only mode.

       O_WRONLY
              The file is opened in write-only mode.

RETURN VALUE
       The ftp_open() function returns 0 on success, or -1 on error (and set
       errno).

ERRORS
       The ftp_open() function fails 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.

       EAGAIN An attempt was made to send a request to the server while the
              data connection is open.

       ENOSYS The mode argument was set to an unsupported value.

       ETXTBSY
              File busy.

       EAGAIN The data connection is already in use (see NOTES below).

       EAGAIN Temporary server error.

       ENOSPC Server has insufficient space to complete the request.

       EACCES User does not have permission to perform the requested
              operation.

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

NOTES
       The ftp_open() function does not support O_RDWR, since the FTP protocol
       does not provide a mechanism for opening a file for both reading and
       writing.

       Because the FTP protocol allows only one data connection to be
       established at any given time, you cannot open multiple FTPFILE handles
       at the same time using the same FTP handle.  If you have an open
       FTPFILE handle, you must call ftp_close() on it before you can call
       ftp_open() to create another one.

EXAMPLE
       The following code shows how to display a file from a remote FTP
       server:

              FTP *ftp;
              FTPFILE *ftpfile;
              char buf[1024];
              ssize_t sz;

              /* ... call ftp_connect(3) and ftp_login(3) ... */

              if (ftp_open(&ftpfile, ftp, "/path/to/file", O_RDONLY) == -1)
              {
                   perror("ftp_open()");
                   exit(1);
              }

              while (1)
              {
                   sz = ftp_read(ftpfile, buf, sizeof(buf));
                   if (sz == -1)
                   {
                        perror("ftp_read()");
                        exit(1);
                   }
                   if (sz == 0)
                        break;

                   /* write buffer to stdout */
                   write(fileno(stdout), buf, sz);
              }

              if (ftp_close(ftpfile) == -1)
              {
                   perror("ftp_close()");
                   exit(1);
              }

SEE ALSO
       libfget(3), ftp_read(3), ftp_write(3), ftp_close(3), open(2)

Feep Networks                    January 2004                      ftp_open(3)