stat(2)stat(2)NAME
stat, fstat, lstat - Provide information about a file
SYNOPSIS
#include <sys/types.h> #include <sys/stat.h>
int stat(
const char *path,
struct stat *buffer ); int lstat(
const char *path,
struct stat *buffer ); int fstat(
int filedes,
struct stat *buffer );
STANDARDS
Interfaces documented on this reference page conform to industry stan‐
dards as follows:
fstat(), stat(): POSIX.1, XSH4.0, XSH4.2, XSH5.0
lstat(): POSIX.1, XSH4.2, XSH5.0
Refer to the standards(5) reference page for more information about
industry standards and associated tags.
PARAMETERS
Specifies the pathname identifying the file. Specifies the file
descriptor identifying the open file. Points to the stat structure in
which information is returned. The stat structure is described in the
<sys/stat.h> header file.
DESCRIPTION
The stat() function obtains information about the file named by the
path parameter. Read, write, or execute permission for the named file
is not required, but all directories listed in the pathname leading to
the file must be searchable. The file information is written to the
area specified by the buffer parameter, which is a pointer to a stat
structure, defined in <sys/stat.h>.
The values of the stat structure's member, mode_t, are defined in
<sys/mode.h>.
The fstat() function is like the stat() function except that the infor‐
mation obtained is about an open file referenced by the filedes parame‐
ter.
The lstat() function is like the stat() function except in the case
where the named file is a symbolic link. In this case, the lstat()
function returns information about the link, while the stat() and
fstat() functions return information about the file the link refer‐
ences. In the case of a symbolic link, the stat() functions set the
st_size field of the stat structure to the length of the symbolic link,
and sets the st_mode field to indicate the file type.
The stat(), lstat(), and fstat() functions update any time-related
fields associated with the file before writing into the stat structure.
[Tru64 UNIX] When run on a file in an AdvFS clone fileset, the value
returned in the st_blocks field is the number of blocks in the original
file at the time the clone fileset was created.
NOTES
Two structure members in <sys/stat.h> uniquely identify a file in a
file system: st_ino, the file serial number, and st_dev, the device id
for the directory that contains the file.
[Tru64 UNIX] However, in the rare case when a user application has
been deleting open files, and a file serial number is reused, a third
structure member in <sys/stat.h>, the file generation number, is needed
to uniquely identify a file. This member, st_gen, is used in addition
to st_ino and st_dev.
RETURN VALUES
Upon successful completion, a value of 0 (zero) is returned. Otherwise,
a value of -1 is returned and errno is set to indicate the error.
ERRORS
If the stat() or lstat() function fails, errno may be set to one of the
following values: Search permission is denied for a component of the
path parameter. [Tru64 UNIX] Either the buffer parameter or the path
parameter points to a location outside of the allocated address space
of the process. An I/O error occurred while reading from the file sys‐
tem. Too many links were encountered in translating path. The length
of the path parameter exceeds PATH_MAX or a pathname component is
longer than NAME_MAX. The file named by the path parameter does not
exist or is an empty string. A component of the path parameter is not
a directory.
[Tru64 UNIX] For NFS file access, if the stat() or lstat() function
fails, errno may also be set to one of the following values: The file
position pointer associated with the filedes parameter was negative.
Indicates either that the request was for a write access to a file but
the specified file name was actually a directory, or that the function
was trying to rename a directory as a file. Indicates either that the
system file table is full, or that there are too many files currently
open in the system. Indicates a stale NFS file handle. An opened file
was deleted by the server or another client; a client cannot open a
file because the server has unmounted or unexported the remote direc‐
tory; or the directory that contains an opened file was either
unmounted or unexported by the server.
If the fstat() function fails, errno may be set to one of the following
values: The filedes parameter is not a valid file descriptor. [Tru64
UNIX] The buffer parameter points to a location outside of the allo‐
cated address space of the process. An I/O error occurred while read‐
ing from the file system.
SEE ALSO
Functions: chmod(2), chown(2), link(2), mknod(2), open(2), pipe(2),
symlink(2), utime(2)
Standards: standards(5)stat(2)