.TH ftp_open 3 "January 2004" "Feep Networks" "C Library Calls"
.SH NAME
ftp_open \- open a file on an FTP server
.SH SYNOPSIS
.B #include <libfget.h>

.BI "int ftp_open(FTPFILE **" ftpfile ", FTP *" ftp ","
.BI "char *" file ", int " mode ");"
.SH VERSION
This man page documents version 1.3 of \fBlibfget\fP.
.SH DESCRIPTION
The \fBftp_open\fP() function opens the file \fIfile\fP on the FTP server
associated with \fIftp\fP.  It creates an \fBFTPFILE\fP handle and sets
\fIftpfile\fP to point to the newly created handle.  The \fImode\fP
argument must be one of the following values:
.TP
.B O_RDONLY
The file is opened in read-only mode.
.TP
.B O_WRONLY
The file is opened in write-only mode.
.SH RETURN VALUE
The \fBftp_open\fP() function returns 0 on success, or -1 on error
(and set \fIerrno\fP).
.SH ERRORS
The \fBftp_open\fP() function fails if:
.TP
.B ECONNRESET
The server shut down the connection.  The caller is then responsible
for calling \fBftp_quit\fP() with the \fBFTP_QUIT_FAST\fP flag set.
.TP
.B ETIMEDOUT
The operation timed out.  (The timeout interval can be set via the
\fBFTP_OPT_IO_TIMEOUT\fP option; see the \fBftp_set_options\fP(3) man
page for details.)
.TP
.B EINVAL
Unexpected response code received from server.
.TP
.B EAGAIN
An attempt was made to send a request to the server while the data
connection is open.
.TP
.B ENOSYS
The \fImode\fP argument was set to an unsupported value.
.TP
.B ETXTBSY
File busy.
.TP
.B EAGAIN
The data connection is already in use (see \fBNOTES\fP below).
.TP
.B EAGAIN
Temporary server error.
.TP
.B ENOSPC
Server has insufficient space to complete the request.
.TP
.B EACCES
User does not have permission to perform the requested operation.
.PP
It may also fail for any of the errors specified for the underlying
\fBpoll\fP(2), \fBread\fP(2), \fBwrite\fP(2), \fBsocket\fP(2),
\fBconnect\fP(2), \fBfcntl\fP(2) (using \fBF_GETFL\fP and \fBF_SETFL\fP),
or \fBcalloc\fP(3) system and library calls.
.SH NOTES
The \fBftp_open\fP() function does not support \fBO_RDWR\fP, 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 \fIFTPFILE\fP handles at
the same time using the same \fIFTP\fP handle.  If you have an open
\fIFTPFILE\fP handle, you must call \fBftp_close\fP() on it before you
can call \fBftp_open\fP() to create another one.
.SH EXAMPLE
The following code shows how to display a file from a remote FTP server:

.RS
.nf
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);
}
.fi
.RE
.SH SEE ALSO
.BR libfget (3),
.BR ftp_read (3),
.BR ftp_write (3),
.BR ftp_close (3),
.BR open (2)