NAME
stat — get file status
SYNOPSIS
#include <sys/types.h>
#include <sys/stat.h>
int stat(const char *path, struct stat *buf);
DESCRIPTION
The
stat()
function obtains information about the
named file and writes it to the area pointed to by
the
buf
argument. The path argument points to a
pathname naming a file. Read, write or execute
permission of the named file is not required, but
all directories listed in the pathname leading to
the file must be searchable. An implementation that
provides additional or alternate file access control
mechanisms may, under implementation-dependent
conditions, cause
stat()
to fail. In particular, the system may deny the existence
of the file specified by
path.
The
buf
argument is a pointer to a
stat
structure, as defined in the header
<sys/stat.h>,
into which information is placed concerning the file.
The
stat()
function updates any time-related fields (as described in
the definition of File Times Update in the XBD specification),
before writing into the
stat
structure.
The structure members
st_mode,
st_ino,
st_dev,
st_uid,
st_gid,
st_atime,
st_ctime,
and
st_mtime
will
have meaningful values for all file types defined in
this document. The value of the member
st_nlink
will be set to the number of links to the file.
RETURN VALUE
Upon successful completion, 0 is returned.
Otherwise, -1 is returned and
errno
is set to indicate the error.
ERRORS
The
stat()
function will fail if:
- [EACCES]
Search permission is denied for a component of the
path
prefix.
- [EIO]
An error occurred while reading from the file system.
- [ELOOP]
Too many symbolic links were encountered in resolving path.
- [ENAMETOOLONG]
The length of the
path
argument exceeds
{PATH_MAX}
or a pathname component is longer than
{NAME_MAX}.
- [ENOENT]
A component of
path
does not name an existing file or path is an empty string.
- [ENOTDIR]
A component of the
path
prefix is not a directory.
The
stat()
function may fail if:
- [ENAMETOOLONG]
Pathname resolution of a symbolic link produced an intermediate
result whose length exceeds
{PATH_MAX}.
- [EOVERFLOW]
A value to be stored would overflow one of the members of the
stat
structure.
CHANGE HISTORY
First released in Issue 1.
Derived from Issue 1 of the SVID.
Issue 4
The following changes are incorporated for alignment
with the ISO POSIX-1 standard:
The type of argument
path
is changed from
char *
to
const char *.
In the
DESCRIPTION
section, (a) statements
indicating the purpose of this interface and a
paragraph defining the contents of
stat
structure members are added, and (b) the words
"extended security controls" are replaced by
"additional or alternate file access control mechanisms."
The following change is incorporated for alignment
with the FIPS requirements:
In the ERRORS section, the condition whereby
[ENAMETOOLONG]
will be returned if a pathname
component is larger that
{NAME_MAX}
is now defined as mandatory and marked as an extension.
Another change is incorporated as follows:
The header
<sys/types.h>
is now marked as optional (OH); this header need not be included
on XSI-conformant systems.
Issue 4, Version 2
The
ERRORS
section is updated for X/OPEN UNIX conformance as follows:
In the mandatory section,
EIO
is added to indicate that a physical I/O error has
occurred, and
ELOOP
to indicate that too many symbolic links were
encountered during pathname resolution.
In the optional section, a second
ENAMETOOLONG
condition is defined that may
report excessive length of an intermediate result of pathname
resolution of a symbolic link.
In the optional section,
EOVERFLOW
is added to indicate that a value to be stored in a
member of the
stat
structure would cause overflow.
DESCRIPTION
If the chosen path name or file descriptor refers to a
Multi-Level Directory (MLD), and the process does not have the
multilevel effective privilege, the
i-node
number returned in
st_ino
is the
i-node
of the MLD itself.
The parameters for the
stat()
function are as follows:
- path
is a pointer to a path name of any file within the mounted file
system. (All directories listed in the path name must be searchable.)
- buf
is a pointer to a
stat
structure, which is where the file status information is stored.
The
stat
structure contains the following members:
(Note that the position of items in this list does not necessarily
reflect the order of the members in the structure.)
ERRORS
- [EFAULT]
buf
or
path
points to an invalid address.
The reliable detection of this error is implementation dependent.
- [EOVERFLOW]
The file size in bytes or the number of blocks allocated to the file cannot
be represented correctly in the structure pointed to by
buf.
NFS
The
st_basemode
and
st_acl
fields are zero on files accessed remotely.
st_acl
field is applicable to HFS File Systems only.
WARNINGS
Access Control Lists - HFS File Systems only
Access control list descriptions in this entry apply only to HFS
file systems on standard HP-UX operating systems.
DEPENDENCIES
CD-ROM
The
st_uid
and
st_gid
fields are set to -1 if they are not specified
on the disk for a given file.
AUTHOR
stat()
and
fstat()
were developed by AT&T.
lstat()
was developed by the University of California, Berkeley.
SEE ALSO
touch(1),
chmod(2),
chown(2),
creat(2),
link(2),
mknod(2),
pipe(2),
read(2),
rename(2),
setacl(2),
stat64(2),
sysfs(2),
time(2),
truncate(2),
unlink(2),
utime(2),
write(2),
acl(5),
stat(5).
STANDARDS CONFORMANCE
stat(): AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1
