.TH ftp_opendir 3 "January 2004" "Feep Networks" "C Library Calls"
.SH NAME
ftp_opendir, ftp_readdir, ftp_rewinddir, ftp_telldir, ftp_seekdir, ftp_closedir \- FTP directory access functions
.SH SYNOPSIS
.B #include <libfget.h>

.BI "int ftp_opendir(FTPDIR **" ftpdir ","
.BI "FTP *" ftp ", char *" dir ");"

.BI "int ftp_readdir(FTPDIR *" ftpdir ", struct ftpdirent *" ftpdirent ");"

.BI "void ftp_rewinddir(FTPDIR *" ftpdir ");"

.BI "off_t ftp_telldir(FTPDIR *" ftpdir ");"

.BI "void ftp_seekdir(FTPDIR *" ftpdir ", off_t " loc ");"

.BI "void ftp_closedir(FTPDIR *" ftpdir ");"
.SH VERSION
This man page documents version 1.3 of \fBlibfget\fP.
.SH DESCRIPTION
The \fBftp_opendir\fP() function opens the directory \fIdir\fP on the FTP
server associated with \fIftp\fP.  It allocates memory for an \fBFTPDIR\fP
handle and changes \fIftpdir\fP to point to the newly-allocated memory.

The \fBftp_readdir\fP() function writes a description of the next file
in directory \fIftpdir\fP to the structure pointed to by \fIftpdirent\fP.

The \fBftp_rewinddir\fP() function resets \fIftpdir\fP such that the next
call to \fBftp_readdir\fP() will return the first file in the directory.

The \fBftp_telldir\fP() function returns the current index into directory
\fIftpdir\fP.

The \fBftp_seekdir\fP() function sets the current index in directory
\fIftpdir\fP to \fIloc\fP.

The \fBftp_closedir\fP() function closes the directory handle and frees
memory associated with \fIftpdir\fP.
.SH RETURN VALUE
The \fBftp_opendir\fP() function returns 0 on success, or -1 on error (and
sets \fIerrno\fP).

The \fBftp_readdir\fP() function returns 1 when an entry is returned, or
0 at the end of the directory.  It cannot fail.

The \fBftp_telldir\fP() function returns the requested index.  It cannot
fail.
.SH ERRORS
The \fBftp_opendir\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.
.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),
\fBshutdown\fP(2), \fBclose\fP(2), or \fBcalloc\fP(3) system and library
calls.
.SH NOTES
Because of the limitations of the FTP protocol, applications must not
rely on being able to call \fBftp_opendir\fP() while an \fIFTPFILE\fP 
handle is open.  See \fBlibfget\fP(3) for more information.
.SH EXAMPLE
The following code shows how to read a directory from an FTP server:

.RS
.nf
FTP *ftp;
FTPDIR *ftpdir;
struct ftpdirent fde;

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

if (ftp_opendir(&ftpdir, ftp, "/path/to/directory") == -1)
{
	perror("ftp_opendir()");
	exit(1);
}

while (ftp_readdir(ftpdir, &fde))
{
	puts(fde.fd_name);
}

ftp_closedir(ftpdir);
.fi
.RE
.SH SEE ALSO
.BR libfget (3),
.BR opendir (3),
.BR readdir (3),
.BR rewinddir (3),
.BR seekdir (3),
.BR telldir (3),
.BR closedir (3)