.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved 
.TH "FSTAT" 3P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual"
.\" fstat 
.SH PROLOG
This manual page is part of the POSIX Programmer's Manual.
The Linux implementation of this interface may differ (consult
the corresponding Linux manual page for details of Linux behavior),
or the interface may not be implemented on Linux.
.SH NAME
fstat \- get file status
.SH SYNOPSIS
.LP
\fB#include <sys/stat.h>
.br
.sp
int fstat(int\fP \fIfildes\fP\fB, struct stat *\fP\fIbuf\fP\fB);
.br
\fP
.SH DESCRIPTION
.LP
The \fIfstat\fP() function shall obtain information about an open
file associated with the file descriptor \fIfildes\fP, and
shall write it to the area pointed to by \fIbuf\fP.
.LP
If \fIfildes\fP references a shared memory object, the implementation
shall update in the \fBstat\fP structure pointed to by the
\fIbuf\fP argument only the \fIst_uid\fP, \fIst_gid\fP, \fIst_size\fP,
and \fIst_mode\fP fields, and only the S_IRUSR,
S_IWUSR, S_IRGRP, S_IWGRP, S_IROTH, and S_IWOTH file permission bits
need be valid. The implementation may update other fields and
flags. 
.LP
If \fIfildes\fP references a typed memory object, the implementation
shall update in the \fBstat\fP structure pointed to by the
\fIbuf\fP argument only the \fIst_uid\fP, \fIst_gid\fP, \fIst_size\fP,
and \fIst_mode\fP fields, and only the S_IRUSR,
S_IWUSR, S_IRGRP, S_IWGRP, S_IROTH, and S_IWOTH file permission bits
need be valid. The implementation may update other fields and
flags. 
.LP
The \fIbuf\fP argument is a pointer to a \fBstat\fP structure, as
defined in \fI<sys/stat.h>\fP, into which information is placed concerning
the file.
.LP
The structure members \fIst_mode\fP, \fIst_ino\fP, \fIst_dev\fP, \fIst_uid\fP,
\fIst_gid\fP, \fIst_atime\fP,
\fIst_ctime\fP, and \fIst_mtime\fP shall have meaningful values for
all other file types defined in this volume of
IEEE\ Std\ 1003.1-2001. The value of the member \fIst_nlink\fP shall
be set to the number of links to the file.
.LP
An implementation that provides additional or alternative file access
control mechanisms may, under implementation-defined
conditions, cause \fIfstat\fP() to fail.
.LP
The \fIfstat\fP() function shall update any time-related fields as
described in the Base Definitions volume of
IEEE\ Std\ 1003.1-2001, Section 4.7, File Times Update, before writing
into the \fBstat\fP structure.
.SH RETURN VALUE
.LP
Upon successful completion, 0 shall be returned. Otherwise, -1 shall
be returned and \fIerrno\fP set to indicate the error.
.SH ERRORS
.LP
The \fIfstat\fP() function shall fail if:
.TP 7
.B EBADF
The \fIfildes\fP argument is not a valid file descriptor.
.TP 7
.B EIO
An I/O error occurred while reading from the file system.
.TP 7
.B EOVERFLOW
The file size in bytes or the number of blocks allocated to the file
or the file serial number cannot be represented correctly
in the structure pointed to by \fIbuf\fP.
.sp
.LP
The \fIfstat\fP() function may fail if:
.TP 7
.B EOVERFLOW
One of the values is too large to store into the structure pointed
to by the \fIbuf\fP argument.
.sp
.LP
\fIThe following sections are informative.\fP
.SH EXAMPLES
.SS Obtaining File Status Information
.LP
The following example shows how to obtain file status information
for a file named \fB/home/cnd/mod1\fP. The structure variable
\fIbuffer\fP is defined for the \fBstat\fP structure. The \fB/home/cnd/mod1\fP
file is opened with read/write privileges and is
passed to the open file descriptor \fIfildes\fP.
.sp
.RS
.nf

\fB#include <sys/types.h>
#include <sys/stat.h>
#include <fcntl.h>
.sp

struct stat buffer;
int         status;
\&...
fildes = open("/home/cnd/mod1", O_RDWR);
status = fstat(fildes, &buffer);
\fP
.fi
.RE
.SH APPLICATION USAGE
.LP
None.
.SH RATIONALE
.LP
None.
.SH FUTURE DIRECTIONS
.LP
None.
.SH SEE ALSO
.LP
\fIlstat\fP(), \fIstat\fP(), the Base Definitions volume of
IEEE\ Std\ 1003.1-2001, \fI<sys/stat.h>\fP, \fI<sys/types.h>\fP
.SH COPYRIGHT
Portions of this text are reprinted and reproduced in electronic form
from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
-- Portable Operating System Interface (POSIX), The Open Group Base
Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of
Electrical and Electronics Engineers, Inc and The Open Group. In the
event of any discrepancy between this version and the original IEEE and
The Open Group Standard, the original IEEE and The Open Group Standard
is the referee document. The original Standard can be obtained online at
http://www.opengroup.org/unix/online.html .