.TH ftp_site 3 "January 2004" "Feep Networks" "C Library Calls"
.SH NAME
ftp_site, ftp_site_open \- perform a site-specific FTP operation
.SH SYNOPSIS
.B #include <libfget.h>

.BI "int ftp_site(FTP *" ftp ", char *" fmt ", ...);"

.BI "int ftp_site_open(FTPFILE **" ftpfile ", "
.BI "FTP *" ftp ", int " mode ", "
.BI "char *" fmt ", ...);"
.SH VERSION
This man page documents version 1.3 of \fBlibfget\fP.
.SH DESCRIPTION
The \fBftp_site\fP() function executes an FTP "SITE" command on the FTP
server associated with \fIftp\fP.

The \fBftp_site_open\fP() function is used to execute a "SITE" command
that opens a data connection.  It creates a new \fBFTPFILE\fP handle
for the new data connection and sets \fIftpfile\fP to point to
the newly created handle.  The \fImode\fP argument must be one of the
following values:
.IP \fBO_RDONLY\fP
The data connection is opened in read-only mode.
.IP \fBO_WRONLY\fP
The data connection is opened in write-only mode.
.PP
The \fBFTPFILE\fP handle returned in \fIftpfile\fP may be used the same
way as an \fBFTPFILE\fP handle returned by \fBftp_open\fP(3).  In other
words, it can be passed to \fBftp_read\fP(3) or \fBftp_write\fP(3) to
read or write data, and it must be freed by calling \fBftp_close\fP(3)
before another \fBFTPFILE\fP may be opened.

For both functions, the \fIfmt\fP argument is a \fBprintf\fP(3)-style
format string.  It, along with any optional arguments that may follow
it, specifies the site command to be executed (i.e., the text sent to
the FTP server after the "SITE" verb itself).
.SH RETURN VALUE
The \fBftp_site\fP() and \fBftp_site_open\fP() functions return 0 on
success, or -1 on error (and set \fIerrno\fP).
.SH ERRORS
The \fBftp_site\fP() and \fBftp_site_open\fP() functions fail 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.
.PP
They may also fail for any of the errors specified for the underlying
\fBpoll\fP(2), \fBread\fP(2) or \fBwrite\fP(2) system calls.

The \fBftp_site_open\fP() function will also fail if:
.TP
.B ENOSYS
The \fImode\fP argument was set to an unsupported value.
.PP
It will also fail for any of the errors specified for the underlying
\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 SEE ALSO
.BR libfget (3),
.BR ftp_open (3)