]>
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 | .\" |
e8426ca2 | 40 | .TH STAT 2 2020-04-11 "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 | 45 | .B #include <sys/types.h> |
fea681da | 46 | .B #include <sys/stat.h> |
fea681da | 47 | .B #include <unistd.h> |
68e4db0a | 48 | .PP |
9a38b2ce | 49 | .BI "int stat(const char *" pathname ", struct stat *" statbuf ); |
9a38b2ce | 50 | .BI "int fstat(int " fd ", struct stat *" statbuf ); |
9a38b2ce | 51 | .BI "int lstat(const char *" pathname ", struct stat *" statbuf ); |
f90f031e | 52 | |
40084043 MK |
53 | .BR "#include <fcntl.h> " "/* Definition of AT_* constants */" |
54 | .B #include <sys/stat.h> | |
68e4db0a | 55 | .PP |
40084043 | 56 | .BI "int fstatat(int " dirfd ", const char *" pathname ", struct stat *" \ |
9a38b2ce | 57 | statbuf , |
40084043 MK |
58 | .BI " int " flags ); |
59 | .fi | |
68e4db0a | 60 | .PP |
8179def1 MK |
61 | .in -4n |
62 | Feature Test Macro Requirements for glibc (see | |
63 | .BR feature_test_macros (7)): | |
64 | .in | |
68e4db0a | 65 | .PP |
43e0fe7d | 66 | .ad l |
8179def1 | 67 | .BR lstat (): |
43e0fe7d | 68 | .RS 4 |
cf7fa0a1 | 69 | /* glibc 2.19 and earlier */ _BSD_SOURCE |
afb9bd5d | 70 | .br |
cf7fa0a1 | 71 | || /* Since glibc 2.20 */ _DEFAULT_SOURCE |
afb9bd5d | 72 | .br |
cf7fa0a1 MK |
73 | || _XOPEN_SOURCE\ >=\ 500 |
74 | .\" _XOPEN_SOURCE\ &&\ _XOPEN_SOURCE_EXTENDED | |
3ba63d80 | 75 | .br |
cf7fa0a1 | 76 | || /* Since glibc 2.10: */ _POSIX_C_SOURCE\ >=\ 200112L |
43e0fe7d | 77 | .RE |
68e4db0a | 78 | .PP |
40084043 | 79 | .BR fstatat (): |
40084043 MK |
80 | .ad l |
81 | .RS 4 | |
68e4db0a | 82 | .PD 0 |
40084043 MK |
83 | .TP 4 |
84 | Since glibc 2.10: | |
b0da7b8b | 85 | _POSIX_C_SOURCE\ >=\ 200809L |
40084043 MK |
86 | .TP |
87 | Before glibc 2.10: | |
88 | _ATFILE_SOURCE | |
89 | .RE | |
43e0fe7d MK |
90 | .PD |
91 | .ad | |
fea681da MK |
92 | .SH DESCRIPTION |
93 | .PP | |
e096bd70 | 94 | These functions return information about a file, in the buffer pointed to by |
9a38b2ce | 95 | .IR statbuf . |
5503c85e | 96 | No permissions are required on the file itself, but\(emin the case of |
071d1c4f MK |
97 | .BR stat (), |
98 | .BR fstatat (), | |
c13182ef | 99 | and |
827edbd2 MK |
100 | .BR lstat ()\(emexecute |
101 | (search) permission is required on all of the directories in | |
66cbeaf4 | 102 | .I pathname |
da2d9dad | 103 | that lead to the file. |
fea681da | 104 | .PP |
da2d9dad | 105 | .BR stat () |
071d1c4f MK |
106 | and |
107 | .BR fstatat () | |
e096bd70 MK |
108 | retrieve information about the file pointed to by |
109 | .IR pathname ; | |
071d1c4f MK |
110 | the differences for |
111 | .BR fstatat () | |
112 | are described below. | |
efeece04 | 113 | .PP |
da2d9dad | 114 | .BR lstat () |
fea681da | 115 | is identical to |
da2d9dad MK |
116 | .BR stat (), |
117 | except that if | |
66cbeaf4 | 118 | .I pathname |
e096bd70 | 119 | is a symbolic link, then it returns information about the link itself, |
fea681da | 120 | not the file that it refers to. |
efeece04 | 121 | .PP |
da2d9dad | 122 | .BR fstat () |
fea681da | 123 | is identical to |
da2d9dad | 124 | .BR stat (), |
5201bb40 | 125 | except that the file about which information is to be retrieved |
e096bd70 | 126 | is specified by the file descriptor |
d3b03141 | 127 | .IR fd . |
9152b8c9 MK |
128 | .\" |
129 | .SS The stat structure | |
da2d9dad | 130 | All of these system calls return a |
fea681da MK |
131 | .I stat |
132 | structure, which contains the following fields: | |
133 | .PP | |
bd191423 | 134 | .in +4n |
b8302363 | 135 | .EX |
fea681da | 136 | struct stat { |
e9e9e87e | 137 | dev_t st_dev; /* ID of device containing file */ |
96dea201 MK |
138 | ino_t st_ino; /* Inode number */ |
139 | mode_t st_mode; /* File type and mode */ | |
140 | nlink_t st_nlink; /* Number of hard links */ | |
141 | uid_t st_uid; /* User ID of owner */ | |
142 | gid_t st_gid; /* Group ID of owner */ | |
143 | dev_t st_rdev; /* Device ID (if special file) */ | |
144 | off_t st_size; /* Total size, in bytes */ | |
145 | blksize_t st_blksize; /* Block size for filesystem I/O */ | |
146 | blkcnt_t st_blocks; /* Number of 512B blocks allocated */ | |
e9e9e87e MK |
147 | |
148 | /* Since Linux 2.6, the kernel supports nanosecond | |
149 | precision for the following timestamp fields. | |
150 | For the details before Linux 2.6, see NOTES. */ | |
151 | ||
96dea201 MK |
152 | struct timespec st_atim; /* Time of last access */ |
153 | struct timespec st_mtim; /* Time of last modification */ | |
154 | struct timespec st_ctim; /* Time of last status change */ | |
e9e9e87e MK |
155 | |
156 | #define st_atime st_atim.tv_sec /* Backward compatibility */ | |
157 | #define st_mtime st_mtim.tv_sec | |
158 | #define st_ctime st_ctim.tv_sec | |
fea681da | 159 | }; |
b8302363 | 160 | .EE |
bd191423 | 161 | .in |
efeece04 | 162 | .PP |
b3deaf0f | 163 | .IR Note : |
496bdb56 MK |
164 | the order of fields in the |
165 | .I stat | |
166 | structure varies somewhat | |
167 | across architectures. | |
168 | In addition, | |
169 | the definition above does not show the padding bytes | |
170 | that may be present between some fields on various architectures. | |
409b0278 | 171 | Consult the glibc and kernel source code |
496bdb56 | 172 | if you need to know the details. |
efeece04 | 173 | .PP |
64639e9a MK |
174 | .\" Background: inode attributes are modified with i_mutex held, but |
175 | .\" read by stat() without taking the mutex. | |
b3deaf0f | 176 | .IR Note : |
7ad5fb5d | 177 | for performance and simplicity reasons, different fields in the |
f240296d JH |
178 | .I stat |
179 | structure may contain state information from different moments | |
64639e9a MK |
180 | during the execution of the system call. |
181 | For example, if | |
addfd6c3 MK |
182 | .IR st_mode |
183 | or | |
f240296d | 184 | .IR st_uid |
addfd6c3 MK |
185 | is changed by another process by calling |
186 | .BR chmod (2) | |
187 | or | |
64639e9a | 188 | .BR chown (2), |
f240296d JH |
189 | .BR stat () |
190 | might return the old | |
191 | .I st_mode | |
192 | together with the new | |
193 | .IR st_uid , | |
194 | or the old | |
195 | .I st_uid | |
196 | together with the new | |
197 | .IR st_mode . | |
efeece04 | 198 | .PP |
53cb52e5 MK |
199 | The fields in the |
200 | .I stat | |
201 | structure are as follows: | |
202 | .TP | |
29de83af | 203 | .I st_dev |
53cb52e5 | 204 | This field describes the device on which this file resides. |
e9ef777f MK |
205 | (The |
206 | .BR major (3) | |
207 | and | |
208 | .BR minor (3) | |
209 | macros may be useful to decompose the device ID in this field.) | |
53cb52e5 | 210 | .TP |
c61617be MK |
211 | .I st_ino |
212 | This field contains the file's inode number. | |
213 | .TP | |
cafa9752 | 214 | .I st_mode |
e8ff4f53 MK |
215 | This field contains the file type and mode. |
216 | See | |
217 | .BR inode (7) | |
218 | for further information. | |
cafa9752 | 219 | .TP |
d41bfb20 MK |
220 | .I st_nlink |
221 | This field contains the number of hard links to the file. | |
222 | .TP | |
78909f3e MK |
223 | .I st_uid |
224 | This field contains the user ID of the owner of the file. | |
225 | .TP | |
226 | .I st_gid | |
227 | This field contains the ID of the group owner of the file. | |
228 | .TP | |
da2d9dad | 229 | .I st_rdev |
53cb52e5 MK |
230 | This field describes the device that this file (inode) represents. |
231 | .TP | |
fea681da | 232 | .I st_size |
53cb52e5 | 233 | This field gives the size of the file (if it is a regular |
c13182ef | 234 | file or a symbolic link) in bytes. |
280ff209 MK |
235 | The size of a symbolic link is the length of the pathname |
236 | it contains, without a terminating null byte. | |
53cb52e5 | 237 | .TP |
28f042cc | 238 | .I st_blksize |
96dea201 | 239 | This field gives the "preferred" block size for efficient filesystem I/O. |
28f042cc | 240 | .TP |
fea681da | 241 | .I st_blocks |
53cb52e5 | 242 | This field indicates the number of blocks allocated to the file, |
e8ff4f53 | 243 | in 512-byte units. |
fea681da | 244 | (This may be smaller than |
eee0a2ec MK |
245 | .IR st_size /512 |
246 | when the file has holes.) | |
53cb52e5 | 247 | .TP |
fea681da | 248 | .I st_atime |
b2a8e053 | 249 | This is the time of the last access of file data. |
53cb52e5 | 250 | .TP |
fea681da | 251 | .I st_mtime |
b2a8e053 | 252 | This is the time of last modification of file data. |
53cb52e5 | 253 | .TP |
fea681da | 254 | .I st_ctime |
b2a8e053 MK |
255 | This is the file's last status change timestamp |
256 | (time of last change to the inode). | |
fea681da | 257 | .PP |
e8ff4f53 MK |
258 | For further information on the above fields, see |
259 | .BR inode (7). | |
40084043 | 260 | .\" |
1fef0fa3 | 261 | .SS fstatat() |
40084043 MK |
262 | The |
263 | .BR fstatat () | |
57bc46c2 N |
264 | system call is a more general interface for accessing file information |
265 | which can still provide exactly the behavior of each of | |
cadd38ba | 266 | .BR stat (), |
57bc46c2 N |
267 | .BR lstat (), |
268 | and | |
269 | .BR fstat (). | |
efeece04 | 270 | .PP |
40084043 MK |
271 | If the pathname given in |
272 | .I pathname | |
273 | is relative, then it is interpreted relative to the directory | |
274 | referred to by the file descriptor | |
275 | .I dirfd | |
276 | (rather than relative to the current working directory of | |
277 | the calling process, as is done by | |
cadd38ba | 278 | .BR stat () |
57bc46c2 N |
279 | and |
280 | .BR lstat () | |
40084043 | 281 | for a relative pathname). |
efeece04 | 282 | .PP |
40084043 MK |
283 | If |
284 | .I pathname | |
285 | is relative and | |
286 | .I dirfd | |
287 | is the special value | |
288 | .BR AT_FDCWD , | |
289 | then | |
290 | .I pathname | |
291 | is interpreted relative to the current working | |
292 | directory of the calling process (like | |
57bc46c2 N |
293 | .BR stat () |
294 | and | |
295 | .BR lstat ()). | |
efeece04 | 296 | .PP |
40084043 MK |
297 | If |
298 | .I pathname | |
299 | is absolute, then | |
300 | .I dirfd | |
301 | is ignored. | |
efeece04 | 302 | .PP |
40084043 MK |
303 | .I flags |
304 | can either be 0, or include one or more of the following flags ORed: | |
305 | .TP | |
306 | .BR AT_EMPTY_PATH " (since Linux 2.6.39)" | |
307 | .\" commit 65cfc6722361570bfe255698d9cd4dccaf47570d | |
308 | If | |
309 | .I pathname | |
310 | is an empty string, operate on the file referred to by | |
311 | .IR dirfd | |
312 | (which may have been obtained using the | |
313 | .BR open (2) | |
314 | .B O_PATH | |
315 | flag). | |
b78969ac MÅš |
316 | In this case, |
317 | .I dirfd | |
57bc46c2 N |
318 | can refer to any type of file, not just a directory, and |
319 | the behavior of | |
320 | .BR fstatat () | |
321 | is similar to that of | |
322 | .BR fstat (). | |
a6fcbdf8 MK |
323 | If |
324 | .I dirfd | |
325 | is | |
326 | .BR AT_FDCWD , | |
327 | the call operates on the current working directory. | |
40084043 MK |
328 | This flag is Linux-specific; define |
329 | .B _GNU_SOURCE | |
330 | .\" Before glibc 2.16, defining _ATFILE_SOURCE sufficed | |
331 | to obtain its definition. | |
332 | .TP | |
333 | .BR AT_NO_AUTOMOUNT " (since Linux 2.6.38)" | |
334 | Don't automount the terminal ("basename") component of | |
335 | .I pathname | |
336 | if it is a directory that is an automount point. | |
337 | This allows the caller to gather attributes of an automount point | |
338 | (rather than the location it would mount). | |
76e4954f MK |
339 | Since Linux 4.14, |
340 | .\" commit 42f46148217865a545e129612075f3d828a2c4e4 | |
3d5c9255 | 341 | also don't instantiate a nonexistent name in an |
57bc46c2 | 342 | on-demand directory such as used for automounter indirect maps. |
40084043 MK |
343 | This flag can be used in tools that scan directories |
344 | to prevent mass-automounting of a directory of automount points. | |
345 | The | |
346 | .B AT_NO_AUTOMOUNT | |
347 | flag has no effect if the mount point has already been mounted over. | |
348 | This flag is Linux-specific; define | |
349 | .B _GNU_SOURCE | |
350 | .\" Before glibc 2.16, defining _ATFILE_SOURCE sufficed | |
351 | to obtain its definition. | |
57bc46c2 N |
352 | Both |
353 | .BR stat () | |
354 | and | |
355 | .BR lstat () | |
356 | act as though | |
357 | .B AT_NO_AUTOMOUNT | |
358 | was set. | |
40084043 MK |
359 | .TP |
360 | .B AT_SYMLINK_NOFOLLOW | |
361 | If | |
362 | .I pathname | |
363 | is a symbolic link, do not dereference it: | |
364 | instead return information about the link itself, like | |
cadd38ba | 365 | .BR lstat (). |
40084043 MK |
366 | (By default, |
367 | .BR fstatat () | |
368 | dereferences symbolic links, like | |
cadd38ba | 369 | .BR stat ().) |
40084043 MK |
370 | .PP |
371 | See | |
372 | .BR openat (2) | |
373 | for an explanation of the need for | |
374 | .BR fstatat (). | |
47297adb | 375 | .SH RETURN VALUE |
c13182ef MK |
376 | On success, zero is returned. |
377 | On error, \-1 is returned, and | |
fea681da MK |
378 | .I errno |
379 | is set appropriately. | |
380 | .SH ERRORS | |
381 | .TP | |
382 | .B EACCES | |
383 | Search permission is denied for one of the directories | |
384 | in the path prefix of | |
66cbeaf4 | 385 | .IR pathname . |
fea681da | 386 | (See also |
ad7cc990 | 387 | .BR path_resolution (7).) |
fea681da MK |
388 | .TP |
389 | .B EBADF | |
d3b03141 | 390 | .I fd |
0fa890e0 | 391 | is not a valid open file descriptor. |
fea681da MK |
392 | .TP |
393 | .B EFAULT | |
394 | Bad address. | |
395 | .TP | |
396 | .B ELOOP | |
397 | Too many symbolic links encountered while traversing the path. | |
398 | .TP | |
399 | .B ENAMETOOLONG | |
66cbeaf4 | 400 | .I pathname |
c066b169 | 401 | is too long. |
fea681da MK |
402 | .TP |
403 | .B ENOENT | |
5cf0b3b4 | 404 | A component of |
66cbeaf4 | 405 | .I pathname |
ad9533eb | 406 | does not exist or is a dangling symbolic link. |
33909153 MK |
407 | .TP |
408 | .B ENOENT | |
66cbeaf4 | 409 | .I pathname |
96dea201 MK |
410 | is an empty string and |
411 | .B AT_EMPTY_PATH | |
412 | was not specified in | |
413 | .IR flags . | |
fea681da MK |
414 | .TP |
415 | .B ENOMEM | |
75b94dc3 | 416 | Out of memory (i.e., kernel memory). |
fea681da MK |
417 | .TP |
418 | .B ENOTDIR | |
94ea1e9d | 419 | A component of the path prefix of |
66cbeaf4 | 420 | .I pathname |
5cf0b3b4 | 421 | is not a directory. |
9dcc4605 MK |
422 | .TP |
423 | .B EOVERFLOW | |
66cbeaf4 | 424 | .I pathname |
fec75159 SP |
425 | or |
426 | .I fd | |
427 | refers to a file whose size, inode number, | |
428 | or number of blocks cannot be represented in, respectively, the types | |
429 | .IR off_t , | |
430 | .IR ino_t , | |
431 | or | |
432 | .IR blkcnt_t . | |
433 | This error can occur when, for example, | |
434 | an application compiled on a 32-bit platform without | |
5e4dc269 | 435 | .I -D_FILE_OFFSET_BITS=64 |
9dcc4605 MK |
436 | calls |
437 | .BR stat () | |
438 | on a file whose size exceeds | |
4d69ed2e | 439 | .I (1<<31)-1 |
fec75159 | 440 | bytes. |
40084043 | 441 | .PP |
40084043 MK |
442 | The following additional errors can occur for |
443 | .BR fstatat (): | |
444 | .TP | |
445 | .B EBADF | |
446 | .I dirfd | |
447 | is not a valid file descriptor. | |
448 | .TP | |
449 | .B EINVAL | |
450 | Invalid flag specified in | |
451 | .IR flags . | |
452 | .TP | |
453 | .B ENOTDIR | |
454 | .I pathname | |
455 | is relative and | |
456 | .I dirfd | |
457 | is a file descriptor referring to a file other than a directory. | |
458 | .SH VERSIONS | |
459 | .BR fstatat () | |
460 | was added to Linux in kernel 2.6.16; | |
461 | library support was added to glibc in version 2.4. | |
47297adb | 462 | .SH CONFORMING TO |
40084043 MK |
463 | .BR stat (), |
464 | .BR fstat (), | |
465 | .BR lstat (): | |
282daba9 | 466 | SVr4, 4.3BSD, POSIX.1-2001, POSIX.1.2008. |
97c1eac8 MK |
467 | .\" SVr4 documents additional |
468 | .\" .BR fstat () | |
469 | .\" error conditions EINTR, ENOLINK, and EOVERFLOW. SVr4 | |
470 | .\" documents additional | |
471 | .\" .BR stat () | |
472 | .\" and | |
473 | .\" .BR lstat () | |
474 | .\" error conditions EINTR, EMULTIHOP, ENOLINK, and EOVERFLOW. | |
efeece04 | 475 | .PP |
40084043 MK |
476 | .BR fstatat (): |
477 | POSIX.1-2008. | |
efeece04 | 478 | .PP |
d3e8b141 MK |
479 | According to POSIX.1-2001, |
480 | .BR lstat () | |
481 | on a symbolic link need return valid information only in the | |
482 | .I st_size | |
44b1f5a0 | 483 | field and the file type of the |
d3e8b141 MK |
484 | .IR st_mode |
485 | field of the | |
486 | .IR stat | |
487 | structure. | |
a03c016c | 488 | POSIX.1-2008 tightens the specification, requiring |
d3e8b141 | 489 | .BR lstat () |
7901c9c3 | 490 | to return valid information in all fields except the mode bits in |
d3e8b141 | 491 | .IR st_mode . |
efeece04 | 492 | .PP |
fea681da MK |
493 | Use of the |
494 | .I st_blocks | |
495 | and | |
496 | .I st_blksize | |
c13182ef MK |
497 | fields may be less portable. |
498 | (They were introduced in BSD. | |
499 | The interpretation differs between systems, | |
500 | and possibly on a single system when NFS mounts are involved.) | |
2b2581ee | 501 | .SH NOTES |
1ef5b280 | 502 | .SS Timestamp fields |
e9e9e87e MK |
503 | Older kernels and older standards did not support nanosecond timestamp |
504 | fields. | |
b8efc3ed | 505 | Instead, there were three timestamp |
e9e9e87e MK |
506 | .RI fields\(em st_atime , |
507 | .IR st_mtime , | |
508 | and | |
509 | .IR st_ctime \(emtyped | |
b8efc3ed | 510 | as |
e9e9e87e MK |
511 | .IR time_t |
512 | that recorded timestamps with one-second precision. | |
efeece04 | 513 | .PP |
2b2581ee MK |
514 | Since kernel 2.5.48, the |
515 | .I stat | |
f5935752 | 516 | structure supports nanosecond resolution for the three file timestamp fields. |
e9e9e87e MK |
517 | The nanosecond components of each timestamp are available |
518 | via names of the form | |
2a0bd971 MK |
519 | .IR st_atim.tv_nsec , |
520 | if suitable feature test macros are defined. | |
521 | Nanosecond timestamps were standardized in POSIX.1-2008, | |
522 | and, starting with version 2.12, | |
523 | glibc exposes the nanosecond component names if | |
f5935752 MK |
524 | .BR _POSIX_C_SOURCE |
525 | is defined with the value 200809L or greater, or | |
526 | .BR _XOPEN_SOURCE | |
527 | is defined with the value 700 or greater. | |
2a0bd971 MK |
528 | Up to and including glibc 2.19, |
529 | the definitions of the nanoseconds components are also defined if | |
530 | .B _BSD_SOURCE | |
531 | or | |
532 | .B _SVID_SOURCE | |
533 | is defined. | |
f5935752 MK |
534 | If none of the aforementioned macros are defined, |
535 | then the nanosecond values are exposed with names of the form | |
536 | .IR st_atimensec . | |
e8ff4f53 | 537 | .\" |
0722a578 | 538 | .SS C library/kernel differences |
b8f9d9dd MK |
539 | Over time, increases in the size of the |
540 | .I stat | |
0c8dd254 | 541 | structure have led to three successive versions of |
b8f9d9dd MK |
542 | .BR stat (): |
543 | .IR sys_stat () | |
544 | (slot | |
545 | .IR __NR_oldstat ), | |
546 | .IR sys_newstat () | |
547 | (slot | |
548 | .IR __NR_stat ), | |
549 | and | |
0daa9e92 | 550 | .I sys_stat64() |
a39f2f4d | 551 | (slot |
94971420 MK |
552 | .IR __NR_stat64 ) |
553 | on 32-bit platforms such as i386. | |
554 | The first two versions were already present in Linux 1.0 | |
555 | (albeit with different names); | |
cd358be3 | 556 | .\" See include/asm-i386/stat.h in the Linux 2.4 source code for the |
94971420 MK |
557 | .\" various versions of the structure definitions |
558 | the last was added in Linux 2.4. | |
559 | Similar remarks apply for | |
560 | .BR fstat () | |
561 | and | |
562 | .BR lstat (). | |
efeece04 | 563 | .PP |
94971420 MK |
564 | The kernel-internal versions of the |
565 | .I stat | |
566 | structure dealt with by the different versions are, respectively: | |
94971420 MK |
567 | .TP |
568 | .IR __old_kernel_stat | |
569 | The original structure, with rather narrow fields, and no padding. | |
570 | .TP | |
571 | .IR stat | |
572 | Larger | |
573 | .I st_ino | |
574 | field and padding added to various parts of the structure to | |
575 | allow for future expansion. | |
576 | .TP | |
577 | .IR stat64 | |
578 | Even larger | |
579 | .I st_ino | |
580 | field, | |
581 | larger | |
582 | .I st_uid | |
583 | and | |
584 | .I st_gid | |
585 | fields to accommodate the Linux-2.4 expansion of UIDs and GIDs to 32 bits, | |
586 | and various other enlarged fields and further padding in the structure. | |
587 | (Various padding bytes were eventually consumed in Linux 2.6, | |
588 | with the advent of 32-bit device IDs and nanosecond components | |
589 | for the timestamp fields.) | |
94971420 | 590 | .PP |
d28a0b77 | 591 | The glibc |
b8f9d9dd | 592 | .BR stat () |
d28a0b77 | 593 | wrapper function hides these details from applications, |
6f1a1e61 MK |
594 | invoking the most recent version of the system call provided by the kernel, |
595 | and repacking the returned information if required for old binaries. | |
8179def1 MK |
596 | .\" |
597 | .\" A note from Andries Brouwer, July 2007 | |
e0bf9127 MK |
598 | .\" |
599 | .\" > Is the story not rather more complicated for some calls like | |
8179def1 | 600 | .\" > stat(2)? |
e0bf9127 | 601 | .\" |
8179def1 | 602 | .\" Yes and no, mostly no. See /usr/include/sys/stat.h . |
e0bf9127 | 603 | .\" |
8179def1 MK |
604 | .\" The idea is here not so much that syscalls change, but that |
605 | .\" the definitions of struct stat and of the types dev_t and mode_t change. | |
606 | .\" This means that libc (even if it does not call the kernel | |
607 | .\" but only calls some internal function) must know what the | |
608 | .\" format of dev_t or of struct stat is. | |
609 | .\" The communication between the application and libc goes via | |
610 | .\" the include file <sys/stat.h> that defines a _STAT_VER and | |
611 | .\" _MKNOD_VER describing the layout of the data that user space | |
612 | .\" uses. Each (almost each) occurrence of stat() is replaced by | |
613 | .\" an occurrence of xstat() where the first parameter of xstat() | |
614 | .\" is this version number _STAT_VER. | |
e0bf9127 | 615 | .\" |
8179def1 MK |
616 | .\" Now, also the definitions used by the kernel change. |
617 | .\" But glibc copes with this in the standard way, and the | |
618 | .\" struct stat as returned by the kernel is repacked into | |
619 | .\" the struct stat as expected by the application. | |
620 | .\" Thus, _STAT_VER and this setup cater for the application-libc | |
621 | .\" interface, rather than the libc-kernel interface. | |
e0bf9127 | 622 | .\" |
8179def1 | 623 | .\" (Note that the details depend on gcc being used as c compiler.) |
efeece04 | 624 | .PP |
94971420 MK |
625 | On modern 64-bit systems, life is simpler: there is a single |
626 | .BR stat () | |
627 | system call and the kernel deals with a | |
628 | .I stat | |
629 | structure that contains fields of a sufficient size. | |
efeece04 | 630 | .PP |
40084043 MK |
631 | The underlying system call employed by the glibc |
632 | .BR fstatat () | |
633 | wrapper function is actually called | |
cad6df32 MK |
634 | .BR fstatat64 () |
635 | or, on some architectures, | |
636 | .\" strace(1) shows the name "newfstatat" on x86-64 | |
637 | .BR newfstatat (). | |
bc7ff20e | 638 | .SH EXAMPLE |
988db661 | 639 | The following program calls |
133ca6ca | 640 | .BR lstat () |
bc7ff20e MK |
641 | and displays selected fields in the returned |
642 | .I stat | |
643 | structure. | |
207050fa MK |
644 | .PP |
645 | .EX | |
bc7ff20e MK |
646 | #include <sys/types.h> |
647 | #include <sys/stat.h> | |
648 | #include <time.h> | |
649 | #include <stdio.h> | |
988db661 | 650 | #include <stdlib.h> |
51dbffc5 | 651 | #include <sys/sysmacros.h> |
bc7ff20e MK |
652 | |
653 | int | |
654 | main(int argc, char *argv[]) | |
655 | { | |
656 | struct stat sb; | |
657 | ||
658 | if (argc != 2) { | |
d1a71985 | 659 | fprintf(stderr, "Usage: %s <pathname>\en", argv[0]); |
bc7ff20e MK |
660 | exit(EXIT_FAILURE); |
661 | } | |
662 | ||
133ca6ca MK |
663 | if (lstat(argv[1], &sb) == \-1) { |
664 | perror("lstat"); | |