]>
Commit | Line | Data |
---|---|---|
49821a6a AC |
1 | .\" Copyright (c) 2020-2022 by Alejandro Colomar <colomar.6.4.3@gmail.com> |
2 | .\" and Copyright (c) 2020 by Michael Kerrisk <mtk.manpages@gmail.com> | |
3 | .\" | |
4 | .\" SPDX-License-Identifier: Linux-man-pages-copyleft | |
5 | .\" | |
6 | .\" | |
45186a5d | 7 | .TH stat 3type 2022-07-22 "Linux man-pages (unreleased)" |
49821a6a AC |
8 | .SH NAME |
9 | stat \- file status | |
10 | .SH LIBRARY | |
11 | Standard C library | |
12 | .RI ( libc ) | |
13 | .SH SYNOPSIS | |
14 | .nf | |
15 | .B #include <sys/stat.h> | |
16 | .PP | |
17 | .B struct stat { | |
18 | .BR " dev_t st_dev;" " /* ID of device containing file */" | |
19 | .BR " ino_t st_ino;" " /* Inode number */" | |
20 | .BR " mode_t st_mode;" " /* File type and mode */" | |
21 | .BR " nlink_t st_nlink;" " /* Number of hard links */" | |
22 | .BR " uid_t st_uid;" " /* User ID of owner */" | |
23 | .BR " gid_t st_gid;" " /* Group ID of owner */" | |
24 | .BR " dev_t st_rdev;" " /* Device ID (if special file) */" | |
25 | .BR " off_t st_size;" " /* Total size, in bytes */" | |
26 | .BR " blksize_t st_blksize;" " /* Block size for filesystem I/O */" | |
27 | .BR " blkcnt_t st_blocks;" " /* Number of 512 B blocks allocated */" | |
28 | ||
29 | /* Since POSIX.1-2008, this structure supports nanosecond | |
30 | precision for the following timestamp fields. | |
31 | For the details before POSIX.1-2008, see VERSIONS. */ | |
32 | ||
33 | .BR " struct timespec st_atim;" " /* Time of last access */" | |
34 | .BR " struct timespec st_mtim;" " /* Time of last modification */" | |
35 | .BR " struct timespec st_ctim;" " /* Time of last status change */" | |
36 | ||
37 | .BR "#define st_atime st_atim.tv_sec" " /* Backward compatibility */" | |
38 | .B "#define st_mtine st_mtim.tv_sec" | |
39 | .B "#define st_ctime st_ctim.tv_sec" | |
40 | .B }; | |
41 | .fi | |
42 | .PP | |
43 | .RS -4 | |
44 | Feature Test Macro Requirements for glibc (see | |
45 | .BR feature_test_macros (7)): | |
46 | .RE | |
47 | .PP | |
48 | .IR st_atim , | |
49 | .IR st_mtim , | |
50 | .IR st_ctim : | |
51 | .nf | |
52 | Since glibc 2.12: | |
53 | _POSIX_C_SOURCE >= 200809L || _XOPEN_SOURCE >= 700 | |
54 | Glibc 2.19 and earlier: | |
55 | _BSD_SOURCE || _SVID_SOURCE | |
56 | .fi | |
57 | .SH DESCRIPTION | |
58 | Describes information about a file. | |
59 | .PP | |
60 | The fields are as follows: | |
61 | .TP | |
62 | .I st_dev | |
63 | This field describes the device on which this file resides. | |
64 | (The | |
65 | .BR major (3) | |
66 | and | |
67 | .BR minor (3) | |
68 | macros may be useful to decompose the device ID in this field.) | |
69 | .TP | |
70 | .I st_ino | |
71 | This field contains the file's inode number. | |
72 | .TP | |
73 | .I st_mode | |
74 | This field contains the file type and mode. | |
75 | See | |
76 | .BR inode (7) | |
77 | for further information. | |
78 | .TP | |
79 | .I st_nlink | |
80 | This field contains the number of hard links to the file. | |
81 | .TP | |
82 | .I st_uid | |
83 | This field contains the user ID of the owner of the file. | |
84 | .TP | |
85 | .I st_gid | |
86 | This field contains the ID of the group owner of the file. | |
87 | .TP | |
88 | .I st_rdev | |
89 | This field describes the device that this file (inode) represents. | |
90 | .TP | |
91 | .I st_size | |
92 | This field gives the size of the file (if it is a regular | |
93 | file or a symbolic link) in bytes. | |
94 | The size of a symbolic link is the length of the pathname | |
95 | it contains, without a terminating null byte. | |
96 | .TP | |
97 | .I st_blksize | |
98 | This field gives the "preferred" block size for efficient filesystem I/O. | |
99 | .TP | |
100 | .I st_blocks | |
101 | This field indicates the number of blocks allocated to the file, | |
102 | in 512-byte units. | |
103 | (This may be smaller than | |
104 | .IR st_size /512 | |
105 | when the file has holes.) | |
106 | .TP | |
107 | .I st_atime | |
108 | This is the time of the last access of file data. | |
109 | .TP | |
110 | .I st_mtime | |
111 | This is the time of last modification of file data. | |
112 | .TP | |
113 | .I st_ctime | |
114 | This is the file's last status change timestamp | |
115 | (time of last change to the inode). | |
116 | .PP | |
117 | For further information on the above fields, see | |
118 | .BR inode (7). | |
119 | .SH VERSIONS | |
120 | Old kernels and old standards did not support nanosecond timestamp fields. | |
121 | Instead, there were three timestamp | |
122 | .RI fields\(em st_atime , | |
123 | .IR st_mtime , | |
124 | and | |
125 | .IR st_ctime \(emtyped | |
126 | as | |
127 | .I time_t | |
128 | that recorded timestamps with one-second precision. | |
129 | .PP | |
130 | Since Linux 2.5.48, the | |
131 | .I stat | |
132 | structure supports nanosecond resolution for the three file timestamp fields. | |
133 | The nanosecond components of each timestamp are available | |
134 | via names of the form | |
135 | .IR st_atim.tv_nsec , | |
136 | if suitable test macros are defined. | |
137 | Nanosecond timestamps were standardized in POSIX.1-2008, | |
138 | and, starting with version 2.12, | |
139 | glibc exposes the nanosecond component names if | |
140 | .B _POSIX_C_SOURCE | |
141 | is defined with the value 200809L or greater, or | |
142 | .B _XOPEN_SOURCE | |
143 | is defined with the value 700 or greater. | |
144 | Up to and including glibc 2.19, | |
145 | the definitions of the nanoseconds components are also defined if | |
146 | .B _BSD_SOURCE | |
147 | or | |
148 | .B _SVID_SOURCE | |
149 | is defined. | |
150 | If none of the aforementioned macros are defined, | |
151 | then the nanosecond values are exposed with names of the form | |
152 | .IR st_atimensec . | |
3113c7f3 | 153 | .SH STANDARDS |
49821a6a AC |
154 | POSIX.1-2001 and later. |
155 | .SH NOTES | |
156 | The following header also provides this type: | |
157 | .IR <ftw.h> . | |
158 | .SH SEE ALSO | |
159 | .BR stat (2), | |
160 | .BR inode (7) |