/* Since glibc 2.10: */ _POSIX_C_SOURCE >= 200112L
These functions return information about a file. No permissions are required on the file itself, but-in the case of stat() and lstat() -execute (search) permission is required on all of the directories in path that lead to the file.
stat() stats the file pointed to by path and fills in buf.
lstat() is identical to stat(), except that if path is a symbolic link, then the link itself is stat-ed, not the file that it refersto.
fstat() is identical to stat(), except that the file to be stat-ed is specified by the file descriptor fd.
All of these system calls return a stat structure, which contains the following fields:
The st_dev field describes the device on which this file resides. (The major(3) and minor(3) macros may be useful to decompose thedevice ID in this field.)The st_rdev field describes the device that this file (inode) represents.
The st_size field gives the size of the file (if it is a regular file or a symbolic link) in bytes. The size of a symbolic link is the length of thepathname it contains, without a terminating null byte.
The st_blocks field indicates the number of blocks allocated to the file, 512-byte units. (This may be smaller than st_size/512 when the filehas holes.)
The st_blksize field gives the " preferred'="" blocksize="" for="" efficient="" file="" system="" i="" o.="" (writing="" to="" a="" in="" smaller="" chunks="" may="" cause="" an="">
Not all of the Linux file systems implement all of the time fields. Some file system types allow mounting in such a way that file and/or directory accessesdo not cause an update of the st_atime field. (See noatime, nodiratime, and relatime in mount(8), and related information inmount(2).) In addition, st_atime is not updated if a file is opened with the O_NOATIME; see open(2).
The field st_atime is changed by file accesses, for example, by execve(2), mknod(2), pipe(2), utime(2) and read(2)(of more than zero bytes). Other routines, like mmap(2), may or may not update st_atime.
The field st_mtime is changed by file modifications, for example, by mknod(2), truncate(2), utime(2) and write(2) (ofmore than zero bytes). Moreover, st_mtime of a directory is changed by the creation or deletion of files in that directory. The st_mtime field isnot changed for changes in owner, group, hard link count, or mode.
The field st_ctime is changed by writing or by setting inode information (i.e., owner, group, link count, mode, etc.).
The following POSIX macros are defined to check the file type using the st_mode field:
S_ISREG(m)is it a regular file?
S_ISDIR(m)
directory?
S_ISCHR(m)
character device?
S_ISBLK(m)
block device?
S_ISFIFO(m)
FIFO (named pipe)?
S_ISLNK(m)
symbolic link? (Not in POSIX.1-1996.)
S_ISSOCK(m)
socket? (Not in POSIX.1-1996.)
The sticky bit (S_ISVTX) on a directory means that a file in that directory can be renamed or deleted only by the owner of the file, by the owner ofthe directory, and by a privileged process.
On success, zero is returned. On error, -1 is returned, and errno is set appropriately.
Search permission is denied for one of the directories in the path prefix of path. (See also path_resolution(7).)
EBADF
fd is bad.
EFAULT
Bad address.
ELOOP
Too many symbolic links encountered while traversing the path.
A component of path does not exist, or path is an empty string.
ENOMEM
Out of memory (i.e., kernel memory).
These system calls conform to SVr4, 4.3BSD, POSIX.1-2001.
According to POSIX.1-2001, lstat() on a symbolic link need return valid information only in the st_size field and the file-type component ofthe st_mode field of the stat structure. POSIX.-2008 tightens the specification, requiring lstat() to return valid information in allfields except the permission bits in st_mode.
Use of the st_blocks and st_blksize fields may be less portable. (They were introduced in BSD. The interpretation differs between systems, andpossibly on a single system when NFS mounts are involved.) If you need to obtain the definition of the blkcnt_t or blksize_t types from<sys/stat.h>, then define _XOPEN_SOURCE with the value 500 or greater (before including any header files).
POSIX.1-1990 did not describe the S_IFMT, S_IFSOCK, S_IFLNK, S_IFREG, S_IFBLK, S_IFDIR, S_IFCHR,S_IFIFO, S_ISVTX constants, but instead demanded the use of the macros S_ISDIR(), etc. The S_IF* constants are present inPOSIX.1-2001 and later.
The S_ISLNK() and S_ISSOCK() macros are not in POSIX.1-1996, but both are present in POSIX.1-2001; the former is from SVID 4, the latter fromSUSv2.
UNIX V7 (and later systems) had S_IREAD, S_IWRITE, S_IEXEC, where POSIX prescribes the synonyms S_IRUSR, S_IWUSR,S_IXUSR.
Other systems
Since kernel 2.5.48, the stat structure supports nanosecond resolution for the three file timestamp fields. Glibc exposes the nanosecond component ofeach field using names of the form st_atim.tv_nsec if the _BSD_SOURCE or _SVID_SOURCE feature test macro is defined. These fields arespecified in POSIX.1-2008, and, starting with version 2.12, glibc also exposes these field names if _POSIX_C_SOURCE is defined with the value 200809L orgreater, or _XOPEN_SOURCE is defined with the value 700 or greater. If none of the aforementioned macros are defined, then the nanosecond values areexposed with names of the form st_atimensec. On file systems that do not support subsecond timestamps, the nanosecond fields are returned with the value0.
On Linux, lstat() will generally not trigger automounter action, whereas stat() will (but see fstatat(2)).
For most files under the /proc directory, stat() does not return the file size in the st_size field; instead the field is returned withthe value 0.
Underlying kernel interface