Manual page for STAT(2P)
stat, fstat - (POSIX version) get file status
SYNOPSIS
#include <sys/types.h>
#include <sys/stat.h>
int stat(const char *path, struct stat *buf);
int fstat(int fd, struct stat *buf);
DESCRIPTION
The information in this specification applies
only to POSIX applications.
This is the POSIX specification for stat.
For the BSD specification, see stat(2).
The
stat
function obtains information about the file
whose name is given by path.
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.
The
fstat
function obtains the same information about an open file
referenced by the file descriptor fd.
The buf argument is a pointer to a stat
structure, into which information is placed concerning the file.
The stat structure is defined in the header
<sys/stat.h>
and includes the following members:
-
- Member Type Member Name
-
Description
- mode_t st_mode
-
File mode.
- ino_t st_ino
-
File's inode number.
- dev_t st_dev
-
ID of device containing the file.
- nlink_t st_nlink
-
Number of links to the file.
- uid_t st_uid
-
User ID of the file's owner.
- gid_t st_gid
-
Group ID of the file's group.
- off_t st_size
-
File size in bytes.
- time_t st_atime
-
Time of last access.
- time_t st_mtime
-
Time of last data modification.
- time_t st_ctime
-
Time of last file status change.
The values of the time-related fields are given in seconds since
the Epoch.
The header
<sys/stat.h>
also defines the following macros which can be used
to test whether a file is of the specified type.
The value m supplied to the macros must be the the value of
the st_mode member of a stat structure.
Each macro evaluates to a nonzero value if the test is true, and zero if
the test is false.
-
- S_ISDIR(m)
-
Test macro for a directory.
- S_ISCHR(m)
-
Test macro for a character special file.
- S_ISBLK(m)
-
Test macro for a block special file.
- S_ISREG(m)
-
Test macro for a regular file.
- S_ISFIFO(m)
-
Test macro for a FIFO.
Furthermore,
<sys/stat.h>
includes the following masks and bits which can
used to encode or decode the file modes portion of values of type
mode_t, such as the st_mode member of the stat structure.
-
- S_IRWXU
-
Read, write, execute (if a non-directory), or search
(if a directory) ``owner'' permissions mask.
-
- S_IRUSR
-
``Owner'' read permission bit.
- S_IWUSR
-
``Owner'' write permission bit.
- S_IXUSR
-
``Owner'' execute (if a non-directory) or search (if a directory)
permission bit.
- S_IRWXG
-
Read, write, execute (if a non-directory), or search
(if a directory) ``group'' permissions mask.
-
- S_IRGRP
-
``Group'' read permission bit.
- S_IWGRP
-
``Group'' write permission bit.
- S_IXGRP
-
``Group'' execute (if a non-directory) or search (if a directory)
permission bit.
- S_IRWXO
-
Read, write, execute (if a non-directory), or search
(if a directory) ``other'' permissions mask.
-
- S_IROTH
-
``Other'' read permission bit.
- S_IWOTH
-
``Other'' write permission bit.
- S_IXOTH
-
``Other'' execute (if a non-directory) or search (if a directory)
permission bit.
- S_ISUID
-
Set-user-id bit.
The effective user ID of the process is set to that of the file's owner
when the file is executed.
On a regular file, this bit is cleared on any write.
- S_ISGID
-
Set-group-id bit.
The effective group ID of the process is set to that of the file's group
when the file is executed.
On a regular file, this bit is cleared on any write.
The S_IRWXU mask is the bitwise inclusive OR of the S_IRUSR, S_IWUSR and
S_IXUSR bits.
The S_IRWXG mask is the bitwise inclusive OR of the S_IRGRP, S_IWGRP and
S_IXGRP bits.
The S_IRWXO mask is the bitwise inclusive OR of the S_IROTH, S_IWOTH and
S_IXOTH bits.
Both
stat
and
fstat
functions update any time-related fields of the named file before writing into the stat structure.
RETURN VALUE
Upon successful completion a value of zero is returned.
Otherwise, a value of -1 is returned and errno
is set to indicate the error.
ERRORS
If any of the following conditions occurs,
stat
returns -1 and sets errno to the corresponding value:
- [EACCES]
-
Search permission is denied for a component of the path prefix.
- [EFAULT]
-
Either path or buf points outside the process's allocated
address space.
- [EINVAL]
-
The pathname contains a character with the high-order bit set.
- [EIO]
-
An I/O error occurred while reading from or writing to the file system.
- [ELOOP]
-
Too many symbolic links were encountered in translating the pathname.
- [ENAMETOOLONG]
-
A component of path exceeds {NAME_MAX} (see <limits.h>)
characters,
or the entire pathname exceeds {PATH_MAX} (see <limits.h>)
characters.
- [ENOENT]
-
The named file does not exist.
- [ENOENT]
-
The path argument points to an empty string.
- [ENOTDIR]
-
A component of the path prefix is not a directory.
If any of the following conditions occurs,
fstat
returns -1 and sets errno to the corresponding value:
- [EBADF]
-
The fd argument
is not a valid open file descriptor.
- [EFAULT]
-
The buf argument points outside the process's allocated
address space.
- [EIO]
-
An I/O error occurred while reading from or writing to the file system.
SEE ALSO
chmod(2P),
chown(2P),
creat(2P),
dup(2P),
fcntl(2P),
open(2P),
pipe(2P),
stat(2)
Created by unroff & hp-tools.
© somebody (See intro for details). All Rights Reserved.
Last modified 11/5/97
