| .\" Copyright (c) 2020-2022 by Alejandro Colomar <alx@kernel.org> |
| .\" and Copyright (c) 2020 by Michael Kerrisk <mtk.manpages@gmail.com> |
| .\" |
| .\" SPDX-License-Identifier: Linux-man-pages-copyleft |
| .\" |
| .\" |
| .TH stat 3type (date) "Linux man-pages (unreleased)" |
| .SH NAME |
| stat \- file status |
| .SH LIBRARY |
| Standard C library |
| .RI ( libc ) |
| .SH SYNOPSIS |
| .EX |
| .B #include <sys/stat.h> |
| .P |
| .B struct stat { |
| .BR " dev_t st_dev;" " /* ID of device containing file */" |
| .BR " ino_t st_ino;" " /* Inode number */" |
| .BR " mode_t st_mode;" " /* File type and mode */" |
| .BR " nlink_t st_nlink;" " /* Number of hard links */" |
| .BR " uid_t st_uid;" " /* User ID of owner */" |
| .BR " gid_t st_gid;" " /* Group ID of owner */" |
| .BR " dev_t st_rdev;" " /* Device ID (if special file) */" |
| .BR " off_t st_size;" " /* Total size, in bytes */" |
| .BR " blksize_t st_blksize;" " /* Block size for filesystem I/O */" |
| .BR " blkcnt_t st_blocks;" " /* Number of 512 B blocks allocated */" |
| \& |
| /* Since POSIX.1-2008, this structure supports nanosecond |
| precision for the following timestamp fields. |
| For the details before POSIX.1-2008, see VERSIONS. */ |
| \& |
| .BR " struct timespec st_atim;" " /* Time of last access */" |
| .BR " struct timespec st_mtim;" " /* Time of last modification */" |
| .BR " struct timespec st_ctim;" " /* Time of last status change */" |
| \& |
| .BR "#define st_atime st_atim.tv_sec" " /* Backward compatibility */" |
| .B "#define st_mtime st_mtim.tv_sec" |
| .B "#define st_ctime st_ctim.tv_sec" |
| .B }; |
| .EE |
| .P |
| .RS -4 |
| Feature Test Macro Requirements for glibc (see |
| .BR feature_test_macros (7)): |
| .RE |
| .P |
| .IR st_atim , |
| .IR st_mtim , |
| .IR st_ctim : |
| .nf |
| Since glibc 2.12: |
| _POSIX_C_SOURCE >= 200809L || _XOPEN_SOURCE >= 700 |
| glibc 2.19 and earlier: |
| _BSD_SOURCE || _SVID_SOURCE |
| .fi |
| .SH DESCRIPTION |
| Describes information about a file. |
| .P |
| The fields are as follows: |
| .TP |
| .I st_dev |
| This field describes the device on which this file resides. |
| (The |
| .BR major (3) |
| and |
| .BR minor (3) |
| macros may be useful to decompose the device ID in this field.) |
| .TP |
| .I st_ino |
| This field contains the file's inode number. |
| .TP |
| .I st_mode |
| This field contains the file type and mode. |
| See |
| .BR inode (7) |
| for further information. |
| .TP |
| .I st_nlink |
| This field contains the number of hard links to the file. |
| .TP |
| .I st_uid |
| This field contains the user ID of the owner of the file. |
| .TP |
| .I st_gid |
| This field contains the ID of the group owner of the file. |
| .TP |
| .I st_rdev |
| This field describes the device that this file (inode) represents. |
| .TP |
| .I st_size |
| This 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 the pathname |
| it contains, without a terminating null byte. |
| .TP |
| .I st_blksize |
| This field gives the "preferred" block size for efficient filesystem I/O. |
| .TP |
| .I st_blocks |
| This field indicates the number of blocks allocated to the file, |
| in 512-byte units. |
| (This may be smaller than |
| .IR st_size /512 |
| when the file has holes.) |
| .TP |
| .I st_atime |
| This is the time of the last access of file data. |
| .TP |
| .I st_mtime |
| This is the time of last modification of file data. |
| .TP |
| .I st_ctime |
| This is the file's last status change timestamp |
| (time of last change to the inode). |
| .P |
| For further information on the above fields, see |
| .BR inode (7). |
| .SH STANDARDS |
| POSIX.1-2008. |
| .SH HISTORY |
| POSIX.1-2001. |
| .P |
| Old kernels and old standards did not support nanosecond timestamp fields. |
| Instead, there were three timestamp |
| .RI fields\[em] st_atime , |
| .IR st_mtime , |
| and |
| .IR st_ctime \[em]typed |
| as |
| .I time_t |
| that recorded timestamps with one-second precision. |
| .P |
| Since Linux 2.5.48, the |
| .I stat |
| structure supports nanosecond resolution for the three file timestamp fields. |
| The nanosecond components of each timestamp are available |
| via names of the form |
| .IR st_atim.tv_nsec , |
| if suitable test macros are defined. |
| Nanosecond timestamps were standardized in POSIX.1-2008, |
| and, starting with glibc 2.12, |
| glibc exposes the nanosecond component names if |
| .B _POSIX_C_SOURCE |
| is defined with the value 200809L or greater, or |
| .B _XOPEN_SOURCE |
| is defined with the value 700 or greater. |
| Up to and including glibc 2.19, |
| the definitions of the nanoseconds components are also defined if |
| .B _BSD_SOURCE |
| or |
| .B _SVID_SOURCE |
| is defined. |
| If none of the aforementioned macros are defined, |
| then the nanosecond values are exposed with names of the form |
| .IR st_atimensec . |
| .SH NOTES |
| The following header also provides this type: |
| .IR <ftw.h> . |
| .SH SEE ALSO |
| .BR stat (2), |
| .BR inode (7) |
