]>
Commit | Line | Data |
---|---|---|
fea681da | 1 | '\" t |
fea681da MK |
2 | .\" Copyright (c) 1992 Drew Eckhardt (drew@cs.colorado.edu), March 28, 1992 |
3 | .\" Parts Copyright (c) 1995 Nicolai Langfeldt (janl@ifi.uio.no), 1/1/95 | |
40084043 | 4 | .\" and Copyright (c) 2006, 2007, 2014 Michael Kerrisk <mtk.manpages@gmail.com> |
fea681da | 5 | .\" |
93015253 | 6 | .\" %%%LICENSE_START(VERBATIM) |
fea681da MK |
7 | .\" Permission is granted to make and distribute verbatim copies of this |
8 | .\" manual provided the copyright notice and this permission notice are | |
9 | .\" preserved on all copies. | |
10 | .\" | |
11 | .\" Permission is granted to copy and distribute modified versions of this | |
12 | .\" manual under the conditions for verbatim copying, provided that the | |
13 | .\" entire resulting derived work is distributed under the terms of a | |
14 | .\" permission notice identical to this one. | |
c13182ef | 15 | .\" |
fea681da MK |
16 | .\" Since the Linux kernel and libraries are constantly changing, this |
17 | .\" manual page may be incorrect or out-of-date. The author(s) assume no | |
18 | .\" responsibility for errors or omissions, or for damages resulting from | |
19 | .\" the use of the information contained herein. The author(s) may not | |
20 | .\" have taken the same level of care in the production of this manual, | |
21 | .\" which is licensed free of charge, as they might when working | |
22 | .\" professionally. | |
c13182ef | 23 | .\" |
fea681da MK |
24 | .\" Formatted or processed versions of this manual, if unaccompanied by |
25 | .\" the source, must acknowledge the copyright and authors of this work. | |
4b72fb64 | 26 | .\" %%%LICENSE_END |
fea681da MK |
27 | .\" |
28 | .\" Modified by Michael Haardt <michael@moria.de> | |
29 | .\" Modified 1993-07-24 by Rik Faith <faith@cs.unc.edu> | |
30 | .\" Modified 1995-05-18 by Todd Larason <jtl@molehill.org> | |
31 | .\" Modified 1997-01-31 by Eric S. Raymond <esr@thyrsus.com> | |
32 | .\" Modified 1995-01-09 by Richard Kettlewell <richard@greenend.org.uk> | |
33 | .\" Modified 1998-05-13 by Michael Haardt <michael@cantor.informatik.rwth-aachen.de> | |
34 | .\" Modified 1999-07-06 by aeb & Albert Cahalan | |
35 | .\" Modified 2000-01-07 by aeb | |
c11b1abf | 36 | .\" Modified 2004-06-23 by Michael Kerrisk <mtk.manpages@gmail.com> |
bc7ff20e | 37 | .\" 2007-06-08 mtk: Added example program |
cd667553 | 38 | .\" 2007-07-05 mtk: Added details on underlying system call interfaces |
c13182ef | 39 | .\" |
31a1b45e | 40 | .TH STAT 2 2017-03-13 "Linux" "Linux Programmer's Manual" |
fea681da | 41 | .SH NAME |
40084043 | 42 | stat, fstat, lstat, fstatat \- get file status |
fea681da | 43 | .SH SYNOPSIS |
40084043 | 44 | .nf |
fea681da MK |
45 | .B #include <sys/types.h> |
46 | .br | |
47 | .B #include <sys/stat.h> | |
48 | .br | |
49 | .B #include <unistd.h> | |
50 | .sp | |
66cbeaf4 | 51 | .BI "int stat(const char *" pathname ", struct stat *" buf ); |
fea681da | 52 | .br |
d3b03141 | 53 | .BI "int fstat(int " fd ", struct stat *" buf ); |
fea681da | 54 | .br |
66cbeaf4 | 55 | .BI "int lstat(const char *" pathname ", struct stat *" buf ); |
8179def1 | 56 | .sp |
40084043 MK |
57 | .BR "#include <fcntl.h> " "/* Definition of AT_* constants */" |
58 | .B #include <sys/stat.h> | |
59 | .sp | |
60 | .BI "int fstatat(int " dirfd ", const char *" pathname ", struct stat *" \ | |
61 | buf , | |
62 | .BI " int " flags ); | |
63 | .fi | |
64 | .sp | |
8179def1 MK |
65 | .in -4n |
66 | Feature Test Macro Requirements for glibc (see | |
67 | .BR feature_test_macros (7)): | |
68 | .in | |
43e0fe7d MK |
69 | .ad l |
70 | .PD 0 | |
8179def1 MK |
71 | .sp |
72 | .BR lstat (): | |
43e0fe7d | 73 | .RS 4 |
cf7fa0a1 | 74 | /* glibc 2.19 and earlier */ _BSD_SOURCE |
afb9bd5d | 75 | .br |
cf7fa0a1 | 76 | || /* Since glibc 2.20 */ _DEFAULT_SOURCE |
afb9bd5d | 77 | .br |
cf7fa0a1 MK |
78 | || _XOPEN_SOURCE\ >=\ 500 |
79 | .\" _XOPEN_SOURCE\ &&\ _XOPEN_SOURCE_EXTENDED | |
3ba63d80 | 80 | .br |
cf7fa0a1 | 81 | || /* Since glibc 2.10: */ _POSIX_C_SOURCE\ >=\ 200112L |
43e0fe7d | 82 | .RE |
40084043 MK |
83 | .sp |
84 | .BR fstatat (): | |
85 | .PD 0 | |
86 | .ad l | |
87 | .RS 4 | |
88 | .TP 4 | |
89 | Since glibc 2.10: | |
b0da7b8b | 90 | _POSIX_C_SOURCE\ >=\ 200809L |
40084043 MK |
91 | .TP |
92 | Before glibc 2.10: | |
93 | _ATFILE_SOURCE | |
94 | .RE | |
43e0fe7d MK |
95 | .PD |
96 | .ad | |
fea681da MK |
97 | .SH DESCRIPTION |
98 | .PP | |
e096bd70 | 99 | These functions return information about a file, in the buffer pointed to by |
06fd1bb6 | 100 | .IR buf . |
5503c85e | 101 | No permissions are required on the file itself, but\(emin the case of |
071d1c4f MK |
102 | .BR stat (), |
103 | .BR fstatat (), | |
c13182ef | 104 | and |
827edbd2 MK |
105 | .BR lstat ()\(emexecute |
106 | (search) permission is required on all of the directories in | |
66cbeaf4 | 107 | .I pathname |
da2d9dad | 108 | that lead to the file. |
fea681da | 109 | .PP |
da2d9dad | 110 | .BR stat () |
071d1c4f MK |
111 | and |
112 | .BR fstatat () | |
e096bd70 MK |
113 | retrieve information about the file pointed to by |
114 | .IR pathname ; | |
071d1c4f MK |
115 | the differences for |
116 | .BR fstatat () | |
117 | are described below. | |
fea681da | 118 | |
da2d9dad | 119 | .BR lstat () |
fea681da | 120 | is identical to |
da2d9dad MK |
121 | .BR stat (), |
122 | except that if | |
66cbeaf4 | 123 | .I pathname |
e096bd70 | 124 | is a symbolic link, then it returns information about the link itself, |
fea681da MK |
125 | not the file that it refers to. |
126 | ||
da2d9dad | 127 | .BR fstat () |
fea681da | 128 | is identical to |
da2d9dad | 129 | .BR stat (), |
5201bb40 | 130 | except that the file about which information is to be retrieved |
e096bd70 | 131 | is specified by the file descriptor |
d3b03141 | 132 | .IR fd . |
fea681da | 133 | .PP |
da2d9dad | 134 | All of these system calls return a |
fea681da MK |
135 | .I stat |
136 | structure, which contains the following fields: | |
137 | .PP | |
bd191423 | 138 | .in +4n |
fea681da MK |
139 | .nf |
140 | struct stat { | |
e9e9e87e MK |
141 | dev_t st_dev; /* ID of device containing file */ |
142 | ino_t st_ino; /* inode number */ | |
f4a44ac6 | 143 | mode_t st_mode; /* file type and mode */ |
e9e9e87e MK |
144 | nlink_t st_nlink; /* number of hard links */ |
145 | uid_t st_uid; /* user ID of owner */ | |
146 | gid_t st_gid; /* group ID of owner */ | |
147 | dev_t st_rdev; /* device ID (if special file) */ | |
148 | off_t st_size; /* total size, in bytes */ | |
149 | blksize_t st_blksize; /* blocksize for filesystem I/O */ | |
150 | blkcnt_t st_blocks; /* number of 512B blocks allocated */ | |
151 | ||
152 | /* Since Linux 2.6, the kernel supports nanosecond | |
153 | precision for the following timestamp fields. | |
154 | For the details before Linux 2.6, see NOTES. */ | |
155 | ||
156 | struct timespec st_atim; /* time of last access */ | |
157 | struct timespec st_mtim; /* time of last modification */ | |
158 | struct timespec st_ctim; /* time of last status change */ | |
159 | ||
160 | #define st_atime st_atim.tv_sec /* Backward compatibility */ | |
161 | #define st_mtime st_mtim.tv_sec | |
162 | #define st_ctime st_ctim.tv_sec | |
fea681da MK |
163 | }; |
164 | .fi | |
bd191423 | 165 | .in |
496bdb56 MK |
166 | |
167 | .I Note: | |
168 | the order of fields in the | |
169 | .I stat | |
170 | structure varies somewhat | |
171 | across architectures. | |
172 | In addition, | |
173 | the definition above does not show the padding bytes | |
174 | that may be present between some fields on various architectures. | |
409b0278 | 175 | Consult the glibc and kernel source code |
496bdb56 MK |
176 | if you need to know the details. |
177 | ||
64639e9a MK |
178 | .\" Background: inode attributes are modified with i_mutex held, but |
179 | .\" read by stat() without taking the mutex. | |
f240296d JH |
180 | .I Note: |
181 | For performance and simplicity reasons, different fields in the | |
182 | .I stat | |
183 | structure may contain state information from different moments | |
64639e9a MK |
184 | during the execution of the system call. |
185 | For example, if | |
addfd6c3 MK |
186 | .IR st_mode |
187 | or | |
f240296d | 188 | .IR st_uid |
addfd6c3 MK |
189 | is changed by another process by calling |
190 | .BR chmod (2) | |
191 | or | |
64639e9a | 192 | .BR chown (2), |
f240296d JH |
193 | .BR stat () |
194 | might return the old | |
195 | .I st_mode | |
196 | together with the new | |
197 | .IR st_uid , | |
198 | or the old | |
199 | .I st_uid | |
200 | together with the new | |
201 | .IR st_mode . | |
202 | ||
53cb52e5 MK |
203 | The fields in the |
204 | .I stat | |
205 | structure are as follows: | |
206 | .TP | |
29de83af | 207 | .I st_dev |
53cb52e5 | 208 | This field describes the device on which this file resides. |
e9ef777f MK |
209 | (The |
210 | .BR major (3) | |
211 | and | |
212 | .BR minor (3) | |
213 | macros may be useful to decompose the device ID in this field.) | |
53cb52e5 | 214 | .TP |
c61617be MK |
215 | .I st_ino |
216 | This field contains the file's inode number. | |
217 | .TP | |
cafa9752 MK |
218 | .I st_mode |
219 | See the discussion of file type and mode, below. | |
220 | .TP | |
d41bfb20 MK |
221 | .I st_nlink |
222 | This field contains the number of hard links to the file. | |
223 | .TP | |
78909f3e MK |
224 | .I st_uid |
225 | This field contains the user ID of the owner of the file. | |
226 | .TP | |
227 | .I st_gid | |
228 | This field contains the ID of the group owner of the file. | |
229 | .TP | |
da2d9dad | 230 | .I st_rdev |
53cb52e5 MK |
231 | This field describes the device that this file (inode) represents. |
232 | .TP | |
fea681da | 233 | .I st_size |
53cb52e5 | 234 | This field gives the size of the file (if it is a regular |
c13182ef | 235 | file or a symbolic link) in bytes. |
280ff209 MK |
236 | The size of a symbolic link is the length of the pathname |
237 | it contains, without a terminating null byte. | |
53cb52e5 | 238 | .TP |
fea681da | 239 | .I st_blocks |
53cb52e5 MK |
240 | This field indicates the number of blocks allocated to the file, |
241 | 512-byte units. | |
fea681da | 242 | (This may be smaller than |
eee0a2ec MK |
243 | .IR st_size /512 |
244 | when the file has holes.) | |
53cb52e5 | 245 | .TP |
0daa9e92 | 246 | .I st_blksize |
53cb52e5 | 247 | This field gives the "preferred" blocksize for efficient filesystem I/O. |
fea681da MK |
248 | (Writing to a file in smaller chunks may cause |
249 | an inefficient read-modify-rewrite.) | |
53cb52e5 | 250 | .TP |
fea681da | 251 | .I st_atime |
53cb52e5 MK |
252 | This is the file's last access timestamp. |
253 | It is changed by file accesses, for example, by | |
fea681da MK |
254 | .BR execve (2), |
255 | .BR mknod (2), | |
256 | .BR pipe (2), | |
9af134cd | 257 | .BR utime (2), |
fea681da MK |
258 | and |
259 | .BR read (2) | |
7c93fec0 MK |
260 | (of more than zero bytes). |
261 | Other routines, like | |
fea681da MK |
262 | .BR mmap (2), |
263 | may or may not update | |
264 | .IR st_atime . | |
53cb52e5 | 265 | .TP |
fea681da | 266 | .I st_mtime |
53cb52e5 MK |
267 | This is the file's last modification timestamp. |
268 | It is changed by file modifications, for example, by | |
fea681da MK |
269 | .BR mknod (2), |
270 | .BR truncate (2), | |
9af134cd | 271 | .BR utime (2), |
fea681da MK |
272 | and |
273 | .BR write (2) | |
274 | (of more than zero bytes). | |
275 | Moreover, | |
276 | .I st_mtime | |
277 | of a directory is changed by the creation or deletion of files | |
278 | in that directory. | |
279 | The | |
280 | .I st_mtime | |
281 | field is | |
282 | .I not | |
283 | changed for changes in owner, group, hard link count, or mode. | |
53cb52e5 | 284 | .TP |
fea681da | 285 | .I st_ctime |
53cb52e5 MK |
286 | This is the file's last status change timestamp. |
287 | It is changed by writing or by setting inode information | |
fea681da MK |
288 | (i.e., owner, group, link count, mode, etc.). |
289 | .PP | |
53cb52e5 MK |
290 | Not all of the Linux filesystems implement all of the time fields. |
291 | Some filesystem types allow mounting in such a way that file | |
292 | and/or directory accesses do not cause an update of the | |
293 | .I st_atime | |
294 | field. | |
295 | (See | |
296 | .IR noatime , | |
297 | .IR nodiratime , | |
298 | and | |
299 | .I relatime | |
300 | in | |
301 | .BR mount (8), | |
302 | and related information in | |
303 | .BR mount (2).) | |
304 | In addition, | |
305 | .I st_atime | |
306 | is not updated if a file is opened with the | |
307 | .BR O_NOATIME | |
308 | flag; see | |
309 | .BR open (2). | |
310 | .PP | |
44b1f5a0 MK |
311 | POSIX refers to the |
312 | .I st_mode | |
313 | bits corresponding to the mask | |
314 | .B S_IFMT | |
315 | (see below) as the | |
316 | .IR "file type" , | |
317 | the 12 bits corresponding to the mask 07777 as the | |
318 | .IR "file mode bits" | |
319 | and the least significant 9 bits (0777) as the | |
320 | .IR "file permission bits" . | |
321 | .PP | |
322 | The following mask values are defined for the file type of the | |
ff3976ce MK |
323 | .I st_mode |
324 | field: | |
325 | .in +4n | |
326 | .TS | |
327 | lB l l. | |
44b1f5a0 | 328 | S_IFMT 0170000 bit mask for the file type bit field |
ff3976ce MK |
329 | |
330 | S_IFSOCK 0140000 socket | |
331 | S_IFLNK 0120000 symbolic link | |
332 | S_IFREG 0100000 regular file | |
333 | S_IFBLK 0060000 block device | |
334 | S_IFDIR 0040000 directory | |
335 | S_IFCHR 0020000 character device | |
336 | S_IFIFO 0010000 FIFO | |
337 | .TE | |
338 | .in | |
339 | .PP | |
3779bbef MK |
340 | Thus, to test for a regular file (for example), one could write: |
341 | ||
342 | .nf | |
343 | .in +4n | |
344 | stat(pathname, &sb); | |
345 | if ((sb.st_mode & S_IFMT) == S_IFREG) { | |
346 | /* Handle regular file */ | |
347 | } | |
348 | .in | |
349 | .fi | |
350 | .PP | |
351 | Because tests of the above form are common, additional | |
352 | macros are defined by POSIX to allow the test of the file type in | |
168df940 | 353 | .I st_mode |
3779bbef | 354 | to be written more concisely: |
bd191423 | 355 | .RS 4 |
fea681da | 356 | .TP 1.2i |
c91e381d | 357 | .BR S_ISREG (m) |
fea681da MK |
358 | is it a regular file? |
359 | .TP | |
c91e381d | 360 | .BR S_ISDIR (m) |
fea681da MK |
361 | directory? |
362 | .TP | |
c91e381d | 363 | .BR S_ISCHR (m) |
fea681da MK |
364 | character device? |
365 | .TP | |
c91e381d | 366 | .BR S_ISBLK (m) |
fea681da MK |
367 | block device? |
368 | .TP | |
c91e381d | 369 | .BR S_ISFIFO (m) |
da2d9dad | 370 | FIFO (named pipe)? |
fea681da | 371 | .TP |
c91e381d | 372 | .BR S_ISLNK (m) |
77b99918 | 373 | symbolic link? (Not in POSIX.1-1996.) |
fea681da | 374 | .TP |
c91e381d | 375 | .BR S_ISSOCK (m) |
77b99918 | 376 | socket? (Not in POSIX.1-1996.) |
fea681da MK |
377 | .RE |
378 | .PP | |
3779bbef MK |
379 | The preceding code snippet could thus be rewritten as: |
380 | ||
381 | .nf | |
382 | .in +4n | |
383 | stat(pathname, &sb); | |
384 | if (S_ISREG(sb.st_mode)) { | |
385 | /* Handle regular file */ | |
386 | } | |
387 | .in | |
388 | .fi | |
389 | .PP | |
390 | The definitions of most of the above file type test macros | |
cc2b44eb | 391 | are provided if any of the following feature test macros is defined: |
3779bbef MK |
392 | .BR _BSD_SOURCE |
393 | (in glibc 2.19 and earlier), | |
394 | .BR _SVID_SOURCE | |
395 | (in glibc 2.19 and earlier), | |
396 | or | |
397 | .BR _DEFAULT_SOURCE | |
398 | (in glibc 2.20 and later). | |
399 | In addition, definitions of all of the above macros except | |
400 | .BR S_IFSOCK | |
401 | and | |
402 | .BR S_ISSOCK () | |
403 | are provided if | |
404 | .BR _XOPEN_SOURCE | |
405 | is defined. | |
406 | The definition of | |
407 | .BR S_IFSOCK | |
408 | can also be exposed by defining | |
409 | .BR _XOPEN_SOURCE | |
410 | with a value of 500 or greater. | |
411 | ||
412 | The definition of | |
413 | .BR S_ISSOCK () | |
414 | is exposed if any of the following feature test macros is defined: | |
415 | .BR _BSD_SOURCE | |
416 | (in glibc 2.19 and earlier), | |
417 | .BR _DEFAULT_SOURCE | |
418 | (in glibc 2.20 and later), | |
419 | .BR _XOPEN_SOURCE | |
420 | with a value of 500 or greater, or | |
421 | .BR _POSIX_C_SOURCE | |
422 | with a value of 200112L or greater. | |
423 | .PP | |
ff0afc3f | 424 | The following mask values are defined for |
7901c9c3 | 425 | the file mode component of the |
ff0afc3f MK |
426 | .I st_mode |
427 | field: | |
428 | .in +4n | |
429 | .TS | |
430 | lB l l. | |
bba094e3 MK |
431 | S_ISUID 04000 set-user-ID bit |
432 | S_ISGID 02000 set-group-ID bit (see below) | |
433 | S_ISVTX 01000 sticky bit (see below) | |
ff0afc3f | 434 | |
70b53bc0 | 435 | S_IRWXU 00700 owner has read, write, and execute permission |
51c6aa6e MK |
436 | S_IRUSR 00400 owner has read permission |
437 | S_IWUSR 00200 owner has write permission | |
438 | S_IXUSR 00100 owner has execute permission | |
ff0afc3f | 439 | |
70b53bc0 | 440 | S_IRWXG 00070 group has read, write, and execute permission |
51c6aa6e MK |
441 | S_IRGRP 00040 group has read permission |
442 | S_IWGRP 00020 group has write permission | |
443 | S_IXGRP 00010 group has execute permission | |
ff0afc3f | 444 | |
51c6aa6e | 445 | S_IRWXO 00007 T{ |
70b53bc0 | 446 | others (not in group) have read, write, and execute permission |
a211773a | 447 | T} |
51c6aa6e MK |
448 | S_IROTH 00004 others have read permission |
449 | S_IWOTH 00002 others have write permission | |
450 | S_IXOTH 00001 others have execute permission | |
fea681da | 451 | .TE |
bd191423 | 452 | .in |
fea681da | 453 | .P |
2f0af33b MK |
454 | The set-group-ID bit |
455 | .RB ( S_ISGID ) | |
456 | has several special uses. | |
5c3122b1 | 457 | For a directory, it indicates that BSD semantics is to be used |
fea681da MK |
458 | for that directory: files created there inherit their group ID from |
459 | the directory, not from the effective group ID of the creating process, | |
2f0af33b MK |
460 | and directories created there will also get the |
461 | .B S_ISGID | |
462 | bit set. | |
66ee0c7e | 463 | For a file that does not have the group execution bit |
2f0af33b MK |
464 | .RB ( S_IXGRP ) |
465 | set, | |
da2d9dad | 466 | the set-group-ID bit indicates mandatory file/record locking. |
fea681da | 467 | .P |
2d986c92 | 468 | The sticky bit |
2f0af33b MK |
469 | .RB ( S_ISVTX ) |
470 | on a directory means that a file | |
fea681da MK |
471 | in that directory can be renamed or deleted only by the owner |
472 | of the file, by the owner of the directory, and by a privileged | |
473 | process. | |
40084043 MK |
474 | .\" |
475 | .\" | |
1fef0fa3 | 476 | .SS fstatat() |
40084043 MK |
477 | The |
478 | .BR fstatat () | |
479 | system call operates in exactly the same way as | |
cadd38ba | 480 | .BR stat (), |
40084043 MK |
481 | except for the differences described here. |
482 | ||
483 | If the pathname given in | |
484 | .I pathname | |
485 | is relative, then it is interpreted relative to the directory | |
486 | referred to by the file descriptor | |
487 | .I dirfd | |
488 | (rather than relative to the current working directory of | |
489 | the calling process, as is done by | |
cadd38ba | 490 | .BR stat () |
40084043 MK |
491 | for a relative pathname). |
492 | ||
493 | If | |
494 | .I pathname | |
495 | is relative and | |
496 | .I dirfd | |
497 | is the special value | |
498 | .BR AT_FDCWD , | |
499 | then | |
500 | .I pathname | |
501 | is interpreted relative to the current working | |
502 | directory of the calling process (like | |
cadd38ba | 503 | .BR stat ()). |
40084043 MK |
504 | |
505 | If | |
506 | .I pathname | |
507 | is absolute, then | |
508 | .I dirfd | |
509 | is ignored. | |
510 | ||
511 | .I flags | |
512 | can either be 0, or include one or more of the following flags ORed: | |
513 | .TP | |
514 | .BR AT_EMPTY_PATH " (since Linux 2.6.39)" | |
515 | .\" commit 65cfc6722361570bfe255698d9cd4dccaf47570d | |
516 | If | |
517 | .I pathname | |
518 | is an empty string, operate on the file referred to by | |
519 | .IR dirfd | |
520 | (which may have been obtained using the | |
521 | .BR open (2) | |
522 | .B O_PATH | |
523 | flag). | |
b78969ac MŚ |
524 | In this case, |
525 | .I dirfd | |
526 | can refer to any type of file, not just a directory. | |
a6fcbdf8 MK |
527 | If |
528 | .I dirfd | |
529 | is | |
530 | .BR AT_FDCWD , | |
531 | the call operates on the current working directory. | |
40084043 MK |
532 | This flag is Linux-specific; define |
533 | .B _GNU_SOURCE | |
534 | .\" Before glibc 2.16, defining _ATFILE_SOURCE sufficed | |
535 | to obtain its definition. | |
536 | .TP | |
537 | .BR AT_NO_AUTOMOUNT " (since Linux 2.6.38)" | |
538 | Don't automount the terminal ("basename") component of | |
539 | .I pathname | |
540 | if it is a directory that is an automount point. | |
541 | This allows the caller to gather attributes of an automount point | |
542 | (rather than the location it would mount). | |
543 | This flag can be used in tools that scan directories | |
544 | to prevent mass-automounting of a directory of automount points. | |
545 | The | |
546 | .B AT_NO_AUTOMOUNT | |
547 | flag has no effect if the mount point has already been mounted over. | |
548 | This flag is Linux-specific; define | |
549 | .B _GNU_SOURCE | |
550 | .\" Before glibc 2.16, defining _ATFILE_SOURCE sufficed | |
551 | to obtain its definition. | |
552 | .TP | |
553 | .B AT_SYMLINK_NOFOLLOW | |
554 | If | |
555 | .I pathname | |
556 | is a symbolic link, do not dereference it: | |
557 | instead return information about the link itself, like | |
cadd38ba | 558 | .BR lstat (). |
40084043 MK |
559 | (By default, |
560 | .BR fstatat () | |
561 | dereferences symbolic links, like | |
cadd38ba | 562 | .BR stat ().) |
40084043 MK |
563 | .PP |
564 | See | |
565 | .BR openat (2) | |
566 | for an explanation of the need for | |
567 | .BR fstatat (). | |
47297adb | 568 | .SH RETURN VALUE |
c13182ef MK |
569 | On success, zero is returned. |
570 | On error, \-1 is returned, and | |
fea681da MK |
571 | .I errno |
572 | is set appropriately. | |
573 | .SH ERRORS | |
574 | .TP | |
575 | .B EACCES | |
576 | Search permission is denied for one of the directories | |
577 | in the path prefix of | |
66cbeaf4 | 578 | .IR pathname . |
fea681da | 579 | (See also |
ad7cc990 | 580 | .BR path_resolution (7).) |
fea681da MK |
581 | .TP |
582 | .B EBADF | |
d3b03141 | 583 | .I fd |
0fa890e0 | 584 | is not a valid open file descriptor. |
fea681da MK |
585 | .TP |
586 | .B EFAULT | |
587 | Bad address. | |
588 | .TP | |
589 | .B ELOOP | |
590 | Too many symbolic links encountered while traversing the path. | |
591 | .TP | |
592 | .B ENAMETOOLONG | |
66cbeaf4 | 593 | .I pathname |
c066b169 | 594 | is too long. |
fea681da MK |
595 | .TP |
596 | .B ENOENT | |
5cf0b3b4 | 597 | A component of |
66cbeaf4 | 598 | .I pathname |
5cf0b3b4 | 599 | does not exist, or |
66cbeaf4 | 600 | .I pathname |
5cf0b3b4 | 601 | is an empty string. |
fea681da MK |
602 | .TP |
603 | .B ENOMEM | |
75b94dc3 | 604 | Out of memory (i.e., kernel memory). |
fea681da MK |
605 | .TP |
606 | .B ENOTDIR | |
94ea1e9d | 607 | A component of the path prefix of |
66cbeaf4 | 608 | .I pathname |
5cf0b3b4 | 609 | is not a directory. |
9dcc4605 MK |
610 | .TP |
611 | .B EOVERFLOW | |
66cbeaf4 | 612 | .I pathname |
fec75159 SP |
613 | or |
614 | .I fd | |
615 | refers to a file whose size, inode number, | |
616 | or number of blocks cannot be represented in, respectively, the types | |
617 | .IR off_t , | |
618 | .IR ino_t , | |
619 | or | |
620 | .IR blkcnt_t . | |
621 | This error can occur when, for example, | |
622 | an application compiled on a 32-bit platform without | |
5e4dc269 | 623 | .I -D_FILE_OFFSET_BITS=64 |
9dcc4605 MK |
624 | calls |
625 | .BR stat () | |
626 | on a file whose size exceeds | |
4d69ed2e | 627 | .I (1<<31)-1 |
fec75159 | 628 | bytes. |
40084043 | 629 | .PP |
40084043 MK |
630 | The following additional errors can occur for |
631 | .BR fstatat (): | |
632 | .TP | |
633 | .B EBADF | |
634 | .I dirfd | |
635 | is not a valid file descriptor. | |
636 | .TP | |
637 | .B EINVAL | |
638 | Invalid flag specified in | |
639 | .IR flags . | |
640 | .TP | |
641 | .B ENOTDIR | |
642 | .I pathname | |
643 | is relative and | |
644 | .I dirfd | |
645 | is a file descriptor referring to a file other than a directory. | |
646 | .SH VERSIONS | |
647 | .BR fstatat () | |
648 | was added to Linux in kernel 2.6.16; | |
649 | library support was added to glibc in version 2.4. | |
47297adb | 650 | .SH CONFORMING TO |
40084043 MK |
651 | .BR stat (), |
652 | .BR fstat (), | |
653 | .BR lstat (): | |
282daba9 | 654 | SVr4, 4.3BSD, POSIX.1-2001, POSIX.1.2008. |
97c1eac8 MK |
655 | .\" SVr4 documents additional |
656 | .\" .BR fstat () | |
657 | .\" error conditions EINTR, ENOLINK, and EOVERFLOW. SVr4 | |
658 | .\" documents additional | |
659 | .\" .BR stat () | |
660 | .\" and | |
661 | .\" .BR lstat () | |
662 | .\" error conditions EINTR, EMULTIHOP, ENOLINK, and EOVERFLOW. | |
663 | ||
40084043 MK |
664 | .BR fstatat (): |
665 | POSIX.1-2008. | |
40084043 | 666 | |
d3e8b141 MK |
667 | According to POSIX.1-2001, |
668 | .BR lstat () | |
669 | on a symbolic link need return valid information only in the | |
670 | .I st_size | |
44b1f5a0 | 671 | field and the file type of the |
d3e8b141 MK |
672 | .IR st_mode |
673 | field of the | |
674 | .IR stat | |
675 | structure. | |
a03c016c | 676 | POSIX.1-2008 tightens the specification, requiring |
d3e8b141 | 677 | .BR lstat () |
7901c9c3 | 678 | to return valid information in all fields except the mode bits in |
d3e8b141 MK |
679 | .IR st_mode . |
680 | ||
fea681da MK |
681 | Use of the |
682 | .I st_blocks | |
683 | and | |
684 | .I st_blksize | |
c13182ef MK |
685 | fields may be less portable. |
686 | (They were introduced in BSD. | |
687 | The interpretation differs between systems, | |
688 | and possibly on a single system when NFS mounts are involved.) | |
34c909ac MK |
689 | If you need to obtain the definition of the |
690 | .IR blkcnt_t | |
691 | or | |
692 | .IR blksize_t | |
693 | types from | |
694 | .IR <sys/stat.h> , | |
695 | then define | |
696 | .BR _XOPEN_SOURCE | |
697 | with the value 500 or greater (before including | |
698 | .I any | |
699 | header files). | |
fea681da | 700 | .LP |
beb0ebc8 | 701 | POSIX.1-1990 did not describe the |
66ee0c7e MK |
702 | .BR S_IFMT , |
703 | .BR S_IFSOCK , | |
704 | .BR S_IFLNK , | |
705 | .BR S_IFREG , | |
c91e381d | 706 | .BR S_IFBLK , |
66ee0c7e MK |
707 | .BR S_IFDIR , |
708 | .BR S_IFCHR , | |
709 | .BR S_IFIFO , | |
0daa9e92 | 710 | .B S_ISVTX |
beb0ebc8 | 711 | constants, but instead demanded the use of |
c91e381d MK |
712 | the macros |
713 | .BR S_ISDIR (), | |
f78ed33a | 714 | and so on. |
beb0ebc8 MK |
715 | The |
716 | .BR S_IF* | |
318c8142 | 717 | constants are present in POSIX.1-2001 and later. |
beb0ebc8 | 718 | |
1274071a | 719 | The |
c91e381d | 720 | .BR S_ISLNK () |
1274071a | 721 | and |
c91e381d | 722 | .BR S_ISSOCK () |
1274071a | 723 | macros are not in |
97c1eac8 MK |
724 | POSIX.1-1996, but both are present in POSIX.1-2001; |
725 | the former is from SVID 4, the latter from SUSv2. | |
fea681da | 726 | .LP |
b4112efb | 727 | UNIX\ V7 (and later systems) had |
66ee0c7e MK |
728 | .BR S_IREAD , |
729 | .BR S_IWRITE , | |
c91e381d MK |
730 | .BR S_IEXEC , |
731 | where POSIX | |
66ee0c7e MK |
732 | prescribes the synonyms |
733 | .BR S_IRUSR , | |
734 | .BR S_IWUSR , | |
c91e381d | 735 | .BR S_IXUSR . |
73d8cece | 736 | .SS Other systems |
fea681da | 737 | Values that have been (or are) in use on various systems: |
77b99918 | 738 | .ad l |
fea681da MK |
739 | .TS |
740 | l l l l l. | |
741 | hex name ls octal description | |
742 | f000 S_IFMT 170000 mask for file type | |
77b99918 BIG |
743 | 0000 000000 T{ |
744 | SCO out-of-service inode; BSD unknown type; SVID-v2 and XPG2 | |
745 | have both 0 and 0100000 for ordinary file | |
746 | T} | |
da2d9dad | 747 | 1000 S_IFIFO p| 010000 FIFO (named pipe) |
fea681da MK |
748 | 2000 S_IFCHR c 020000 character special (V7) |
749 | 3000 S_IFMPC 030000 multiplexed character special (V7) | |
750 | 4000 S_IFDIR d/ 040000 directory (V7) | |
77b99918 BIG |
751 | 5000 S_IFNAM 050000 T{ |
752 | XENIX named special file with two subtypes, distinguished by | |
753 | \fIst_rdev\fP values 1, 2 | |
754 | T} | |
fea681da MK |
755 | 0001 S_INSEM s 000001 XENIX semaphore subtype of IFNAM |
756 | 0002 S_INSHD m 000002 XENIX shared data subtype of IFNAM | |
757 | 6000 S_IFBLK b 060000 block special (V7) | |
758 | 7000 S_IFMPB 070000 multiplexed block special (V7) | |
759 | 8000 S_IFREG - 100000 regular (V7) | |
760 | 9000 S_IFCMP 110000 VxFS compressed | |
761 | 9000 S_IFNWK n 110000 network special (HP-UX) | |
762 | a000 S_IFLNK l@ 120000 symbolic link (BSD) | |
77b99918 | 763 | b000 S_IFSHAD 130000 T{ |
7fac88a9 | 764 | Solaris shadow inode for ACL (not seen by user space) |
77b99918 | 765 | T} |
fea681da MK |
766 | c000 S_IFSOCK s= 140000 socket (BSD; also "S_IFSOC" on VxFS) |
767 | d000 S_IFDOOR D> 150000 Solaris door | |
768 | e000 S_IFWHT w% 160000 BSD whiteout (not used for inode) | |
77b99918 BIG |
769 | 0200 S_ISVTX 001000 T{ |
770 | sticky bit: save swapped text even after use (V7) | |
771 | .br | |
772 | reserved (SVID-v2) | |
773 | .br | |
774 | On nondirectories: don't cache this file (SunOS) | |
775 | .br | |
776 | On directories: restricted deletion flag (SVID-v4.2) | |
777 | T} | |
778 | 0400 S_ISGID 002000 T{ | |
779 | set-group-ID on execution (V7) | |
780 | .br | |
781 | for directories: use BSD semantics for propagation of GID | |
782 | T} | |
783 | 0400 S_ENFMT 002000 T{ | |
784 | System V file locking enforcement (shared with S_ISGID) | |
785 | T} | |
da2d9dad | 786 | 0800 S_ISUID 004000 set-user-ID on execution (V7) |
77b99918 BIG |
787 | 0800 S_CDF 004000 T{ |
788 | directory is a context dependent file (HP-UX) | |
789 | T} | |
fea681da | 790 | .TE |
77b99918 | 791 | .ad |
fea681da MK |
792 | |
793 | A sticky command appeared in Version 32V AT&T UNIX. | |
2b2581ee | 794 | .SH NOTES |
1ef5b280 MK |
795 | On Linux, |
796 | .BR lstat () | |
797 | will generally not trigger automounter action, whereas | |
798 | .BR stat () | |
5d5985b8 MK |
799 | will (but see the description of |
800 | .BR fstatat () | |
801 | .B AT_NO_AUTOMOUNT | |
802 | fag, above). | |
1ef5b280 | 803 | |
d695a48c | 804 | For pseudofiles that are autogenerated by the kernel, |
9dbc4adb MK |
805 | .BR stat () |
806 | does not return an accurate value in the | |
807 | .IR st_size | |
808 | field. | |
809 | For example, the value 0 is returned for many files under the | |
1ef5b280 MK |
810 | .I /proc |
811 | directory, | |
9dbc4adb MK |
812 | while various files under |
813 | .IR /sys | |
814 | report a size of 4096 bytes, even though the file content is smaller. | |
815 | For such files, one should simply try to read as many bytes as possible | |
816 | (and append \(aq\e0\(aq to the returned buffer | |
817 | if it is to be interpreted as a string). | |
818 | .\" | |
1ef5b280 | 819 | .SS Timestamp fields |
e9e9e87e MK |
820 | Older kernels and older standards did not support nanosecond timestamp |
821 | fields. | |
b8efc3ed | 822 | Instead, there were three timestamp |
e9e9e87e MK |
823 | .RI fields\(em st_atime , |
824 | .IR st_mtime , | |
825 | and | |
826 | .IR st_ctime \(emtyped | |
b8efc3ed | 827 | as |
e9e9e87e MK |
828 | .IR time_t |
829 | that recorded timestamps with one-second precision. | |
1ef5b280 | 830 | |
2b2581ee MK |
831 | Since kernel 2.5.48, the |
832 | .I stat | |
f5935752 | 833 | structure supports nanosecond resolution for the three file timestamp fields. |
e9e9e87e MK |
834 | The nanosecond components of each timestamp are available |
835 | via names of the form | |
2a0bd971 MK |
836 | .IR st_atim.tv_nsec , |
837 | if suitable feature test macros are defined. | |
838 | Nanosecond timestamps were standardized in POSIX.1-2008, | |
839 | and, starting with version 2.12, | |
840 | glibc exposes the nanosecond component names if | |
f5935752 MK |
841 | .BR _POSIX_C_SOURCE |
842 | is defined with the value 200809L or greater, or | |
843 | .BR _XOPEN_SOURCE | |
844 | is defined with the value 700 or greater. | |
2a0bd971 MK |
845 | Up to and including glibc 2.19, |
846 | the definitions of the nanoseconds components are also defined if | |
847 | .B _BSD_SOURCE | |
848 | or | |
849 | .B _SVID_SOURCE | |
850 | is defined. | |
f5935752 MK |
851 | If none of the aforementioned macros are defined, |
852 | then the nanosecond values are exposed with names of the form | |
853 | .IR st_atimensec . | |
1ef5b280 | 854 | |
96f92a7c MK |
855 | Nanosecond timestamps are supported on XFS, JFS, Btrfs, and |
856 | ext4 (since Linux 2.6.23). | |
857 | .\" commit ef7f38359ea8b3e9c7f2cae9a4d4935f55ca9e80 | |
c2033cfe | 858 | Nanosecond timestamps are not supported in ext2, ext3, and Reiserfs. |
1ef5b280 MK |
859 | On filesystems that do not support subsecond timestamps, |
860 | the nanosecond fields are returned with the value 0. | |
0722a578 | 861 | .SS C library/kernel differences |
b8f9d9dd MK |
862 | Over time, increases in the size of the |
863 | .I stat | |
0c8dd254 | 864 | structure have led to three successive versions of |
b8f9d9dd MK |
865 | .BR stat (): |
866 | .IR sys_stat () | |
867 | (slot | |
868 | .IR __NR_oldstat ), | |
869 | .IR sys_newstat () | |
870 | (slot | |
871 | .IR __NR_stat ), | |
872 | and | |
0daa9e92 | 873 | .I sys_stat64() |
a39f2f4d | 874 | (slot |
94971420 MK |
875 | .IR __NR_stat64 ) |
876 | on 32-bit platforms such as i386. | |
877 | The first two versions were already present in Linux 1.0 | |
878 | (albeit with different names); | |
cd358be3 | 879 | .\" See include/asm-i386/stat.h in the Linux 2.4 source code for the |
94971420 MK |
880 | .\" various versions of the structure definitions |
881 | the last was added in Linux 2.4. | |
882 | Similar remarks apply for | |
883 | .BR fstat () | |
884 | and | |
885 | .BR lstat (). | |
886 | ||
887 | The kernel-internal versions of the | |
888 | .I stat | |
889 | structure dealt with by the different versions are, respectively: | |
94971420 MK |
890 | .TP |
891 | .IR __old_kernel_stat | |
892 | The original structure, with rather narrow fields, and no padding. | |
893 | .TP | |
894 | .IR stat | |
895 | Larger | |
896 | .I st_ino | |
897 | field and padding added to various parts of the structure to | |
898 | allow for future expansion. | |
899 | .TP | |
900 | .IR stat64 | |
901 | Even larger | |
902 | .I st_ino | |
903 | field, | |
904 | larger | |
905 | .I st_uid | |
906 | and | |
907 | .I st_gid | |
908 | fields to accommodate the Linux-2.4 expansion of UIDs and GIDs to 32 bits, | |
909 | and various other enlarged fields and further padding in the structure. | |
910 | (Various padding bytes were eventually consumed in Linux 2.6, | |
911 | with the advent of 32-bit device IDs and nanosecond components | |
912 | for the timestamp fields.) | |
94971420 | 913 | .PP |
d28a0b77 | 914 | The glibc |
b8f9d9dd | 915 | .BR stat () |
d28a0b77 | 916 | wrapper function hides these details from applications, |
6f1a1e61 MK |
917 | invoking the most recent version of the system call provided by the kernel, |
918 | and repacking the returned information if required for old binaries. | |
8179def1 MK |
919 | .\" |
920 | .\" A note from Andries Brouwer, July 2007 | |
e0bf9127 MK |
921 | .\" |
922 | .\" > Is the story not rather more complicated for some calls like | |
8179def1 | 923 | .\" > stat(2)? |
e0bf9127 | 924 | .\" |
8179def1 | 925 | .\" Yes and no, mostly no. See /usr/include/sys/stat.h . |
e0bf9127 | 926 | .\" |
8179def1 MK |
927 | .\" The idea is here not so much that syscalls change, but that |
928 | .\" the definitions of struct stat and of the types dev_t and mode_t change. | |
929 | .\" This means that libc (even if it does not call the kernel | |
930 | .\" but only calls some internal function) must know what the | |
931 | .\" format of dev_t or of struct stat is. | |
932 | .\" The communication between the application and libc goes via | |
933 | .\" the include file <sys/stat.h> that defines a _STAT_VER and | |
934 | .\" _MKNOD_VER describing the layout of the data that user space | |
935 | .\" uses. Each (almost each) occurrence of stat() is replaced by | |
936 | .\" an occurrence of xstat() where the first parameter of xstat() | |
937 | .\" is this version number _STAT_VER. | |
e0bf9127 | 938 | .\" |
8179def1 MK |
939 | .\" Now, also the definitions used by the kernel change. |
940 | .\" But glibc copes with this in the standard way, and the | |
941 | .\" struct stat as returned by the kernel is repacked into | |
942 | .\" the struct stat as expected by the application. | |
943 | .\" Thus, _STAT_VER and this setup cater for the application-libc | |
944 | .\" interface, rather than the libc-kernel interface. | |
e0bf9127 | 945 | .\" |
8179def1 | 946 | .\" (Note that the details depend on gcc being used as c compiler.) |
40084043 | 947 | |
94971420 MK |
948 | On modern 64-bit systems, life is simpler: there is a single |
949 | .BR stat () | |
950 | system call and the kernel deals with a | |
951 | .I stat | |
952 | structure that contains fields of a sufficient size. | |
953 | ||
40084043 MK |
954 | The underlying system call employed by the glibc |
955 | .BR fstatat () | |
956 | wrapper function is actually called | |
cad6df32 MK |
957 | .BR fstatat64 () |
958 | or, on some architectures, | |
959 | .\" strace(1) shows the name "newfstatat" on x86-64 | |
960 | .BR newfstatat (). | |
bc7ff20e | 961 | .SH EXAMPLE |
988db661 | 962 | The following program calls |
2777b1ca | 963 | .BR stat () |
bc7ff20e MK |
964 | and displays selected fields in the returned |
965 | .I stat | |
966 | structure. | |
967 | .nf | |
968 | ||
969 | #include <sys/types.h> | |
970 | #include <sys/stat.h> | |
971 | #include <time.h> | |
972 | #include <stdio.h> | |
988db661 | 973 | #include <stdlib.h> |
51dbffc5 | 974 | #include <sys/sysmacros.h> |
bc7ff20e MK |
975 | |
976 | int | |
977 | main(int argc, char *argv[]) | |
978 | { | |
979 | struct stat sb; | |
980 | ||
981 | if (argc != 2) { | |
982 | fprintf(stderr, "Usage: %s <pathname>\\n", argv[0]); | |
983 | exit(EXIT_FAILURE); | |
984 | } | |
985 | ||
29059a65 | 986 | if (stat(argv[1], &sb) == \-1) { |
bc7ff20e | 987 | perror("stat"); |