]>
Commit | Line | Data |
---|---|---|
9905e59b DH |
1 | '\" t |
2 | .\" Copyright (c) 2017 David Howells <dhowells@redhat.com> | |
3 | .\" | |
4 | .\" Derived from the stat.2 manual page: | |
5 | .\" Copyright (c) 1992 Drew Eckhardt (drew@cs.colorado.edu), March 28, 1992 | |
6 | .\" Parts Copyright (c) 1995 Nicolai Langfeldt (janl@ifi.uio.no), 1/1/95 | |
7 | .\" and Copyright (c) 2006, 2007, 2014 Michael Kerrisk <mtk.manpages@gmail.com> | |
8 | .\" | |
9 | .\" %%%LICENSE_START(VERBATIM) | |
10 | .\" Permission is granted to make and distribute verbatim copies of this | |
11 | .\" manual provided the copyright notice and this permission notice are | |
12 | .\" preserved on all copies. | |
13 | .\" | |
14 | .\" Permission is granted to copy and distribute modified versions of this | |
15 | .\" manual under the conditions for verbatim copying, provided that the | |
16 | .\" entire resulting derived work is distributed under the terms of a | |
17 | .\" permission notice identical to this one. | |
18 | .\" | |
19 | .\" Since the Linux kernel and libraries are constantly changing, this | |
20 | .\" manual page may be incorrect or out-of-date. The author(s) assume no | |
21 | .\" responsibility for errors or omissions, or for damages resulting from | |
22 | .\" the use of the information contained herein. The author(s) may not | |
23 | .\" have taken the same level of care in the production of this manual, | |
24 | .\" which is licensed free of charge, as they might when working | |
25 | .\" professionally. | |
26 | .\" | |
27 | .\" Formatted or processed versions of this manual, if unaccompanied by | |
28 | .\" the source, must acknowledge the copyright and authors of this work. | |
29 | .\" %%%LICENSE_END | |
30 | .\" | |
31 | .TH STATX 2 2017-03-07 "Linux" "Linux Programmer's Manual" | |
32 | .SH NAME | |
33 | statx \- Get file status (extended) | |
34 | .SH SYNOPSIS | |
35 | .nf | |
36 | .B #include <sys/types.h> | |
37 | .br | |
38 | .B #include <sys/stat.h> | |
39 | .br | |
40 | .B #include <unistd.h> | |
41 | .br | |
42 | .BR "#include <fcntl.h> " "/* Definition of AT_* constants */" | |
43 | .sp | |
44 | .BI "int statx(int " dirfd ", const char *" pathname ", int " flags "," | |
45 | .BI " unsigned int " mask ", struct statx *" buf ); | |
46 | .fi | |
47 | .sp | |
48 | .in -4n | |
49 | Feature Test Macro Requirements for glibc (see | |
50 | .BR feature_test_macros (7)): | |
51 | .in | |
52 | .ad l | |
53 | .PD 0 | |
54 | .sp | |
55 | .RS 4 | |
56 | <unknown as yet> | |
57 | .RE | |
58 | .PD | |
59 | .ad | |
60 | .SH DESCRIPTION | |
61 | .PP | |
62 | This function returns information about a file, storing it in the buffer | |
63 | pointed to by | |
64 | .IR buf . | |
65 | The buffer is filled in according to the following type: | |
66 | .PP | |
67 | .in +4n | |
68 | .nf | |
69 | struct statx { | |
6a4667aa MK |
70 | __u32 stx_mask; /* Mask of bits indicating |
71 | filled fields */ | |
72 | __u32 stx_blksize; /* Block size for filesystem I/O */ | |
73 | __u64 stx_attributes; /* Extra file attribute indicators */ | |
74 | __u32 stx_nlink; /* Number of hard links */ | |
75 | __u32 stx_uid; /* User ID of owner */ | |
76 | __u32 stx_gid; /* Group ID of owner */ | |
77 | __u16 stx_mode; /* File type and mode */ | |
78 | __u64 stx_ino; /* Inode number */ | |
79 | __u64 stx_size; /* Total size in bytes */ | |
80 | __u64 stx_blocks; /* Number of 512B blocks allocated */ | |
81 | ||
82 | /* The following fields are file timestamps */ | |
83 | struct statx_timestamp stx_atime; /* Last access */ | |
84 | struct statx_timestamp stx_btime; /* Creation */ | |
85 | struct statx_timestamp stx_ctime; /* Last status change */ | |
86 | struct statx_timestamp stx_mtime; /* Last modification */ | |
87 | ||
88 | /* If this file represents device, then the next two feilds | |
89 | contain the ID of the device */ | |
90 | __u32 stx_rdev_major; /* Major ID */ | |
91 | __u32 stx_rdev_minor; /* Minor ID */ | |
92 | ||
93 | /* The next two fields contain the ID of the device | |
94 | contain the filesystem where the file resides */ | |
95 | __u32 stx_dev_major; /* Major ID */ | |
96 | __u32 stx_dev_minor; /* Minor ID */ | |
9905e59b DH |
97 | }; |
98 | .fi | |
99 | .in | |
100 | .PP | |
6a4667aa | 101 | The file timestamps are structures of the following type: |
9905e59b DH |
102 | .PP |
103 | .in +4n | |
104 | .nf | |
105 | struct statx_timestamp { | |
6a4667aa MK |
106 | __s64 tv_sec; /* Seconds since the Epoch (UNIX time) */ |
107 | __s32 tv_nsec; /* Nanoseconds before or since tv_sec */ | |
9905e59b DH |
108 | }; |
109 | .fi | |
110 | .in | |
111 | .PP | |
112 | (Note that reserved space and padding is omitted) | |
113 | .SS | |
114 | Invoking \fBstatx\fR(): | |
115 | .PP | |
116 | To access a file's status, no permissions are required on the file itself, but | |
117 | in the case of | |
118 | .BR statx () | |
119 | with a path, execute (search) permission is required on all of the directories | |
120 | in | |
121 | .I pathname | |
122 | that lead to the file. | |
123 | .PP | |
124 | .BR statx () | |
125 | uses | |
6a4667aa MK |
126 | .IR pathname , |
127 | .IR dirfd , | |
128 | and | |
129 | .IR flags | |
9905e59b DH |
130 | to locate the target file in one of a variety of ways: |
131 | .TP | |
132 | [*] By absolute path. | |
133 | .I pathname | |
134 | points to an absolute path and | |
135 | .I dirfd | |
136 | is ignored. The file is looked up by name, starting from the root of the | |
137 | filesystem as seen by the calling process. | |
138 | .TP | |
139 | [*] By cwd-relative path. | |
140 | .I pathname | |
141 | points to a relative path and | |
6a4667aa MK |
142 | .IR dirfd |
143 | is | |
144 | .BR AT_FDCWD . | |
9905e59b DH |
145 | The file is looked up by name, starting from the current working directory. |
146 | .TP | |
147 | [*] By dir-relative path. | |
148 | .I pathname | |
149 | points to relative path and | |
150 | .I dirfd | |
151 | indicates a file descriptor pointing to a directory. The file is looked up by | |
152 | name, starting from the directory specified by | |
153 | .IR dirfd . | |
154 | .TP | |
155 | [*] By file descriptor. | |
156 | .IR pathname " is " NULL " and " dirfd | |
157 | indicates a file descriptor. The file attached to the file descriptor is | |
158 | queried directly. The file descriptor may point to any type of file, not just | |
159 | a directory. | |
160 | .PP | |
161 | .I flags | |
162 | can be used to influence a path-based lookup. A value for | |
163 | .I flags | |
164 | is constructed by OR'ing together zero or more of the following constants: | |
165 | .TP | |
166 | .BR AT_EMPTY_PATH | |
167 | .\" commit 65cfc6722361570bfe255698d9cd4dccaf47570d | |
168 | If | |
169 | .I pathname | |
170 | is an empty string, operate on the file referred to by | |
171 | .IR dirfd | |
172 | (which may have been obtained using the | |
173 | .BR open (2) | |
174 | .B O_PATH | |
175 | flag). | |
176 | If | |
177 | .I dirfd | |
178 | is | |
179 | .BR AT_FDCWD , | |
180 | the call operates on the current working directory. | |
181 | In this case, | |
182 | .I dirfd | |
183 | can refer to any type of file, not just a directory. | |
184 | This flag is Linux-specific; define | |
185 | .B _GNU_SOURCE | |
186 | .\" Before glibc 2.16, defining _ATFILE_SOURCE sufficed | |
187 | to obtain its definition. | |
188 | .TP | |
189 | .BR AT_NO_AUTOMOUNT | |
190 | Don't automount the terminal ("basename") component of | |
191 | .I pathname | |
192 | if it is a directory that is an automount point. | |
193 | This allows the caller to gather attributes of an automount point | |
194 | (rather than the location it would mount). | |
195 | This flag can be used in tools that scan directories | |
196 | to prevent mass-automounting of a directory of automount points. | |
197 | The | |
198 | .B AT_NO_AUTOMOUNT | |
199 | flag has no effect if the mount point has already been mounted over. | |
200 | This flag is Linux-specific; define | |
201 | .B _GNU_SOURCE | |
202 | .\" Before glibc 2.16, defining _ATFILE_SOURCE sufficed | |
203 | to obtain its definition. | |
204 | .TP | |
205 | .B AT_SYMLINK_NOFOLLOW | |
206 | If | |
207 | .I pathname | |
208 | is a symbolic link, do not dereference it: | |
209 | instead return information about the link itself, like | |
6a4667aa | 210 | .BR lstat (2). |
9905e59b DH |
211 | .PP |
212 | .I flags | |
213 | can also be used to control what sort of synchronisation the kernel will do | |
214 | when querying a file on a remote filesystem. This is done by OR'ing in one of | |
215 | the following values: | |
216 | .TP | |
217 | AT_STATX_SYNC_AS_STAT | |
218 | Do whatever | |
6a4667aa | 219 | .BR stat (2) |
9905e59b DH |
220 | does. This is the default and is very much filesystem specific. |
221 | .TP | |
222 | AT_STATX_FORCE_SYNC | |
223 | Force the attributes to be synchronised with the server. This may require that | |
224 | a network filesystem perform a data writeback to get the timestamps correct. | |
225 | .TP | |
226 | AT_STATX_DONT_SYNC | |
227 | Don't synchronise anything, but rather just take whatever the system has cached | |
228 | if possible. This may mean that the information returned is approximate, but, | |
229 | on a network filesystem, it may not involve a round trip to the server - even | |
230 | if no lease is held. | |
231 | .PP | |
232 | The | |
233 | .I mask | |
234 | argument to | |
235 | .BR statx () | |
236 | is used to tell the kernel which fields the caller is interested in. | |
237 | .I mask | |
238 | is an OR'ed combination of the following constants: | |
239 | .PP | |
240 | .in +4n | |
241 | .TS | |
242 | lB l. | |
243 | STATX_TYPE Want stx_mode & S_IFMT | |
244 | STATX_MODE Want stx_mode & ~S_IFMT | |
245 | STATX_NLINK Want stx_nlink | |
246 | STATX_UID Want stx_uid | |
247 | STATX_GID Want stx_gid | |
248 | STATX_ATIME Want stx_atime{,_ns} | |
249 | STATX_MTIME Want stx_mtime{,_ns} | |
250 | STATX_CTIME Want stx_ctime{,_ns} | |
251 | STATX_INO Want stx_ino | |
252 | STATX_SIZE Want stx_size | |
253 | STATX_BLOCKS Want stx_blocks | |
254 | STATX_BASIC_STATS [All of the above] | |
255 | STATX_BTIME Want stx_btime{,_ns} | |
256 | STATX_ALL [All currently available fields] | |
257 | .TE | |
258 | .in | |
259 | .PP | |
260 | .B "Do not" | |
261 | simply set | |
262 | .I mask | |
263 | to UINT_MAX as one or more bits may, in the future, be used to specify an | |
264 | extension to the buffer. | |
265 | .SS | |
266 | The returned information | |
267 | .PP | |
268 | The status information for the target file is returned in the | |
269 | .I statx | |
270 | structure pointed to by | |
271 | .IR buf . | |
272 | Included in this is | |
273 | .I stx_mask | |
274 | which indicates what other information has been returned. | |
275 | .I stx_mask | |
276 | has the same format as the mask argument and bits are set in it to indicate | |
277 | which fields have been filled in. | |
278 | .PP | |
279 | It should be noted that the kernel may return fields that weren't requested and | |
280 | may fail to return fields that were requested, depending on what the backing | |
281 | filesystem supports. In either case, | |
282 | .I stx_mask | |
283 | will not be equal | |
284 | .IR mask . | |
285 | .PP | |
286 | If a filesystem does not support a field or if it has an unrepresentable value | |
287 | (for instance, a file with an exotic type), then the mask bit corresponding to | |
288 | that field will be cleared in | |
289 | .I stx_mask | |
290 | even if the user asked for it and a dummy value will be filled in for | |
291 | compatibility purposes if one is available (e.g. a dummy uid and gid may be | |
292 | specified to mount under some circumstances). | |
293 | .PP | |
294 | A filesystem may also fill in fields that the caller didn't ask for if it has | |
295 | values for them available at no extra cost. If this happens, the corresponding | |
296 | bits will be set in | |
297 | .IR stx_mask . | |
298 | .PP | |
299 | ||
300 | .\" Background: inode attributes are modified with i_mutex held, but | |
301 | .\" read by stat() without taking the mutex. | |
302 | .I Note: | |
303 | For performance and simplicity reasons, different fields in the | |
304 | .I statx | |
305 | structure may contain state information from different moments | |
306 | during the execution of the system call. | |
307 | For example, if | |
308 | .IR stx_mode | |
309 | or | |
310 | .IR stx_uid | |
311 | is changed by another process by calling | |
312 | .BR chmod (2) | |
313 | or | |
314 | .BR chown (2), | |
315 | .BR stat () | |
316 | might return the old | |
317 | .I stx_mode | |
318 | together with the new | |
319 | .IR stx_uid , | |
320 | or the old | |
321 | .I stx_uid | |
322 | together with the new | |
323 | .IR stx_mode . | |
324 | .PP | |
325 | Apart from stx_mask (which is described above), the fields in the | |
326 | .I statx | |
327 | structure are: | |
328 | .TP | |
329 | .I stx_mode | |
330 | The file type and mode. This is described in more detail below. | |
331 | .TP | |
332 | .I stx_size | |
333 | The size of the file (if it is a regular file or a symbolic link) in bytes. | |
334 | The size of a symbolic link is the length of the pathname it contains, without | |
335 | a terminating null byte. | |
336 | .TP | |
337 | .I stx_blocks | |
338 | The number of blocks allocated to the file on the medium, in 512-byte units. | |
339 | (This may be smaller than | |
340 | .IR stx_size /512 | |
341 | when the file has holes.) | |
342 | .TP | |
343 | .I stx_blksize | |
344 | The "preferred" blocksize for efficient filesystem I/O. (Writing to a file in | |
345 | smaller chunks may cause an inefficient read-modify-rewrite.) | |
346 | .TP | |
347 | .I stx_nlink | |
348 | The number of hard links on a file. | |
349 | .TP | |
350 | .I stx_uid | |
351 | The user ID of the file's owner. | |
352 | .TP | |
353 | .I stx_gid | |
354 | The ID of the group that may access the file. | |
355 | .TP | |
356 | .IR stx_dev_major " and " stx_dev_minor | |
357 | The device on which this file (inode) resides. | |
358 | .TP | |
359 | .IR stx_rdev_major " and " stx_rdev_minor | |
360 | The device that this file (inode) represents if the file is of block or | |
361 | character device type. | |
362 | .TP | |
363 | .I stx_attributes | |
364 | Further status information about the file (see below for more information). | |
365 | .TP | |
366 | .I stx_atime | |
367 | The file's last access timestamp. | |
368 | This field is changed by file accesses, for example, by | |
369 | .BR execve (2), | |
370 | .BR mknod (2), | |
371 | .BR pipe (2), | |
372 | .BR utime (2), | |
373 | and | |
374 | .BR read (2) | |
375 | (of more than zero bytes). | |
376 | Other routines, such as | |
377 | .BR mmap (2), | |
378 | may or may not update it. | |
379 | .TP | |
380 | .I stx_btime | |
381 | The file's creation timestamp. This is set on file creation and not changed | |
382 | subsequently. | |
383 | .TP | |
384 | .I stx_ctime | |
385 | The file's last status change timestamp. This field is changed by writing or | |
386 | by setting inode information (i.e., owner, group, link count, mode, etc.). | |
387 | .TP | |
388 | .I stx_mtime | |
389 | The file's last modification timestamp. This is changed by file modifications, | |
390 | for example, by | |
391 | .BR mknod (2), | |
392 | .BR truncate (2), | |
393 | .BR utime (2), | |
394 | and | |
395 | .BR write (2) | |
396 | (of more than zero bytes). Moreover, the modification time of a directory is | |
397 | changed by the creation or deletion of files in that directory. This field is | |
398 | .I not | |
399 | changed for changes in owner, group, hard link count, or mode. | |
400 | ||
401 | ||
402 | ||
403 | .PP | |
404 | Not all of the Linux filesystems implement all of the timestamp fields. Some | |
405 | filesystems allow mounting in such a way that file and/or directory accesses do | |
406 | not cause an update of the | |
407 | .I stx_atime | |
408 | field. | |
409 | (See | |
410 | .IR noatime , | |
411 | .IR nodiratime , | |
412 | and | |
413 | .I relatime | |
414 | in | |
415 | .BR mount (8), | |
416 | and related information in | |
417 | .BR mount (2).) | |
418 | In addition, | |
419 | .I stx_atime | |
420 | is not updated if a file is opened with the | |
421 | .BR O_NOATIME ; | |
422 | see | |
423 | .BR open (2). | |
424 | ||
425 | .SS File attributes | |
426 | .PP | |
427 | The | |
428 | .I stx_attributes | |
429 | field contains a set of OR'ed flags that indicate additional attributes of the | |
430 | file: | |
431 | .TP | |
432 | STATX_ATTR_COMPRESSED | |
433 | The file is compressed by the fs and may take extra resources to access. | |
434 | .TP | |
435 | STATX_ATTR_IMMUTABLE | |
436 | The file cannot be modified: it cannot be deleted or renamed, no hard links can | |
437 | be created to this file and no data can be written to it. See chattr(1). | |
438 | .TP | |
439 | STATX_ATTR_APPEND | |
440 | The file can only be opened in append mode for writing. Random access writing | |
441 | is not permitted. See chattr(1). | |
442 | .TP | |
443 | STATX_ATTR_NODUMP | |
444 | File is not a candidate for backup when a backup program such as dump(8) is | |
445 | run. See chattr(1). | |
446 | .TP | |
447 | STATX_ATTR_ENCRYPTED | |
448 | A key is required for the file to be encrypted by the filesystem. | |
449 | .SS File type and mode | |
450 | .PP | |
451 | The | |
452 | .I stx_mode | |
453 | field contains the combined file type and mode. POSIX refers to the bits in | |
454 | this field corresponding to the mask | |
455 | .B S_IFMT | |
456 | (see below) as the | |
457 | .IR "file type" , | |
458 | the 12 bits corresponding to the mask 07777 as the | |
459 | .IR "file mode bits" | |
460 | and the least significant 9 bits (0777) as the | |
461 | .IR "file permission bits" . | |
462 | .IP | |
463 | The following mask values are defined for the file type of the | |
464 | .I stx_mode | |
465 | field: | |
466 | .in +4n | |
467 | .TS | |
468 | lB l l. | |
469 | S_IFMT 0170000 bit mask for the file type bit field | |
470 | ||
471 | S_IFSOCK 0140000 socket | |
472 | S_IFLNK 0120000 symbolic link | |
473 | S_IFREG 0100000 regular file | |
474 | S_IFBLK 0060000 block device | |
475 | S_IFDIR 0040000 directory | |
476 | S_IFCHR 0020000 character device | |
477 | S_IFIFO 0010000 FIFO | |
478 | .TE | |
479 | .in | |
480 | .IP | |
481 | Note that | |
482 | .I stx_mode | |
483 | has two mask flags covering it: one for the type and one for the mode bits. | |
484 | .PP | |
485 | To test for a regular file (for example), one could write: | |
486 | .nf | |
487 | .in +4n | |
488 | statx(AT_FDCWD, pathname, 0, STATX_TYPE, &sb); | |
489 | if ((sb.stx_mask & STATX_TYPE) && (sb.stx_mode & S_IFMT) == S_IFREG) { | |
490 | /* Handle regular file */ | |
491 | } | |
492 | .in | |
493 | .fi | |
494 | .PP | |
495 | Because tests of the above form are common, additional macros are defined by | |
496 | POSIX to allow the test of the file type in | |
497 | .I stx_mode | |
498 | to be written more concisely: | |
499 | .RS 4 | |
500 | .TS | |
501 | lB l. | |
502 | \fBS_ISREG\fR(m) Is it a regular file? | |
503 | \fBS_ISDIR\fR(m) Is it a directory? | |
504 | \fBS_ISCHR\fR(m) Is it a character device? | |
505 | \fBS_ISBLK\fR(m) Is it a block device? | |
506 | \fBS_ISFIFO\fR(m) Is it a FIFO (named pipe)? | |
507 | \fBS_ISLNK\fR(m) Is it a symbolic link? (Not in POSIX.1-1996.) | |
508 | \fBS_ISSOCK\fR(m) Is it a socket? (Not in POSIX.1-1996.) | |
509 | .TE | |
510 | .RE | |
511 | .PP | |
512 | The preceding code snippet could thus be rewritten as: | |
513 | ||
514 | .nf | |
515 | .in +4n | |
516 | statx(AT_FDCWD, pathname, 0, STATX_TYPE, &sb); | |
517 | if ((sb.stx_mask & STATX_TYPE) && S_ISREG(sb.stx_mode)) { | |
518 | /* Handle regular file */ | |
519 | } | |
520 | .in | |
521 | .fi | |
522 | .PP | |
523 | The definitions of most of the above file type test macros | |
524 | are provided if any of the following feature test macros is defined: | |
525 | .BR _BSD_SOURCE | |
526 | (in glibc 2.19 and earlier), | |
527 | .BR _SVID_SOURCE | |
528 | (in glibc 2.19 and earlier), | |
529 | or | |
530 | .BR _DEFAULT_SOURCE | |
531 | (in glibc 2.20 and later). | |
532 | In addition, definitions of all of the above macros except | |
533 | .BR S_IFSOCK | |
534 | and | |
535 | .BR S_ISSOCK () | |
536 | are provided if | |
537 | .BR _XOPEN_SOURCE | |
538 | is defined. | |
539 | The definition of | |
540 | .BR S_IFSOCK | |
541 | can also be exposed by defining | |
542 | .BR _XOPEN_SOURCE | |
543 | with a value of 500 or greater. | |
544 | ||
545 | The definition of | |
546 | .BR S_ISSOCK () | |
547 | is exposed if any of the following feature test macros is defined: | |
548 | .BR _BSD_SOURCE | |
549 | (in glibc 2.19 and earlier), | |
550 | .BR _DEFAULT_SOURCE | |
551 | (in glibc 2.20 and later), | |
552 | .BR _XOPEN_SOURCE | |
553 | with a value of 500 or greater, or | |
554 | .BR _POSIX_C_SOURCE | |
555 | with a value of 200112L or greater. | |
556 | .PP | |
557 | The following mask values are defined for | |
558 | the file mode component of the | |
559 | .I stx_mode | |
560 | field: | |
561 | .in +4n | |
562 | .TS | |
563 | lB l l. | |
564 | S_ISUID 04000 set-user-ID bit | |
565 | S_ISGID 02000 set-group-ID bit (see below) | |
566 | S_ISVTX 01000 sticky bit (see below) | |
567 | ||
568 | S_IRWXU 00700 owner has read, write, and execute permission | |
569 | S_IRUSR 00400 owner has read permission | |
570 | S_IWUSR 00200 owner has write permission | |
571 | S_IXUSR 00100 owner has execute permission | |
572 | ||
573 | S_IRWXG 00070 group has read, write, and execute permission | |
574 | S_IRGRP 00040 group has read permission | |
575 | S_IWGRP 00020 group has write permission | |
576 | S_IXGRP 00010 group has execute permission | |
577 | ||
578 | S_IRWXO 00007 T{ | |
579 | others (not in group) have read, write, and execute permission | |
580 | T} | |
581 | S_IROTH 00004 others have read permission | |
582 | S_IWOTH 00002 others have write permission | |
583 | S_IXOTH 00001 others have execute permission | |
584 | .TE | |
585 | .in | |
586 | .P | |
587 | The set-group-ID bit | |
588 | .RB ( S_ISGID ) | |
589 | has several special uses. | |
590 | For a directory, it indicates that BSD semantics is to be used | |
591 | for that directory: files created there inherit their group ID from | |
592 | the directory, not from the effective group ID of the creating process, | |
593 | and directories created there will also get the | |
594 | .B S_ISGID | |
595 | bit set. | |
596 | For a file that does not have the group execution bit | |
597 | .RB ( S_IXGRP ) | |
598 | set, | |
599 | the set-group-ID bit indicates mandatory file/record locking. | |
600 | .P | |
601 | The sticky bit | |
602 | .RB ( S_ISVTX ) | |
603 | on a directory means that a file | |
604 | in that directory can be renamed or deleted only by the owner | |
605 | of the file, by the owner of the directory, and by a privileged | |
606 | process. | |
607 | ||
608 | ||
609 | .SH RETURN VALUE | |
610 | On success, zero is returned. | |
611 | On error, \-1 is returned, and | |
612 | .I errno | |
613 | is set appropriately. | |
614 | .SH ERRORS | |
615 | .TP | |
616 | .B EINVAL | |
617 | Invalid flag specified in | |
618 | .IR flags . | |
619 | .TP | |
620 | .B EACCES | |
621 | Search permission is denied for one of the directories | |
622 | in the path prefix of | |
623 | .IR pathname . | |
624 | (See also | |
625 | .BR path_resolution (7).) | |
626 | .TP | |
627 | .B EBADF | |
628 | .I dirfd | |
629 | is not a valid open file descriptor. | |
630 | .TP | |
631 | .B EFAULT | |
632 | Bad address. | |
633 | .TP | |
634 | .B ELOOP | |
635 | Too many symbolic links encountered while traversing the path. | |
636 | .TP | |
637 | .B ENAMETOOLONG | |
638 | .I pathname | |
639 | is too long. | |
640 | .TP | |
641 | .B ENOENT | |
642 | A component of | |
643 | .I pathname | |
644 | does not exist, or | |
645 | .I pathname | |
646 | is an empty string and AT_EMPTY_PATH was not specified. | |
647 | .TP | |
648 | .B ENOMEM | |
649 | Out of memory (i.e., kernel memory). | |
650 | .TP | |
651 | .B ENOTDIR | |
652 | A component of the path prefix of | |
653 | .I pathname | |
654 | is not a directory or | |
655 | .I pathname | |
656 | is relative and | |
657 | .I dirfd | |
658 | is a file descriptor referring to a file other than a directory. | |
659 | .SH VERSIONS | |
660 | .BR statx () | |
661 | was added to Linux in kernel 4.11; | |
662 | library support is not yet added to glibc. | |
663 | .SH SEE ALSO | |
664 | .BR ls (1), | |
665 | .BR stat (1), | |
666 | .BR access (2), | |
667 | .BR chmod (2), | |
668 | .BR chown (2), | |
669 | .BR stat (2), | |
670 | .BR readlink (2), | |
671 | .BR utime (2), | |
672 | .BR capabilities (7), | |
673 | .BR symlink (7) |