.TH ftp_stat 3 "January 2004" "Feep Networks" "C Library Calls"
.SH NAME
ftp_stat, ftp_lstat \- get file status from an FTP server
.SH SYNOPSIS
.B #include <libfget.h>

.BI "int ftp_stat(FTP *" ftp ", char *" pathname ","
.BI "struct ftpstat *" fsp ");"

.BI "int ftp_lstat(FTP *" ftp ", char *" pathname ","
.BI "struct ftpstat *" fsp ");"
.SH VERSION
This man page documents version 1.3 of \fBlibfget\fP.
.SH DESCRIPTION
The \fBftp_stat\fP() function writes a description of the file \fIpathname\fP
on the FTP server associated with \fIftp\fP to the structure pointed to by
\fIfsp\fP.

The \fBftp_lstat\fP() function is the same as the \fBftp_stat\fP() function,
except that it does not follow symbolic links.

Both functions set the following fields of the structure pointed to by
\fIfsp\fP:
.TP
.B mode_t fs_mode;
The file's mode.
.TP
.B nlink_t fs_nlink;
Number of hard links to the file.  This will be set to 1 if not provided
by the server.
.TP
.B char fs_username[MAXUSERNAMELEN];
The name of the owner of the file.  In some cases, this may be a
printable-ASCII representation of the user's uid instead of the user's
login.  This will be set to the string "-1" if not provided by the server.
.TP
.B char fs_groupname[MAXPATHLEN];
The name of the file's group.  In some cases, this may be a
printable-ASCII representation of the group's gid instead of the group's
name.  This will be set to the string "-1" if not provided by the server.
.TP
.B off_t fs_size;
The size of the file.
.TP
.B time_t fs_mtime;
The modification time of the file.  Note that this value may or may not
be in UTC, depending on the server.
.TP
.B dev_t fs_rdev;
The device ID, if the file is a character or block device.
.SH RETURN VALUE
The \fBftp_stat\fP() and \fBftp_lstat\fP() functions return 0 on success,
or -1 on error (and set \fIerrno\fP).
.SH ERRORS
The \fBftp_stat\fP() and \fBftp_lstat\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.
.TP
.B ENOTDIR
A component of the path prefix is not a directory.
.TP
.B ELOOP
Too many symlinks were traversed while locating the specified path.
.TP
.B ENOENT
The specified path does not exist.
.PP
They 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_readlink\fP() while an \fIFTPFILE\fP 
handle is open.  See \fBlibfget\fP(3) for more information.
.SH SEE ALSO
.BR libfget (3),
.BR stat (2),
.BR lstat (2)