1STATX(2)                   Linux Programmer's Manual                  STATX(2)
2
3
4

NAME

6       statx - get file status (extended)
7

SYNOPSIS

9       #include <sys/types.h>
10       #include <sys/stat.h>
11       #include <unistd.h>
12       #include <fcntl.h>           /* Definition of AT_* constants */
13
14       int statx(int dirfd, const char *pathname, int flags,
15                 unsigned int mask, struct statx *statxbuf);
16

DESCRIPTION

18       This  function returns information about a file, storing it in the buf‐
19       fer pointed to by statxbuf.  The returned buffer is a structure of  the
20       following type:
21
22           struct statx {
23               __u32 stx_mask;        /* Mask of bits indicating
24                                         filled fields */
25               __u32 stx_blksize;     /* Block size for filesystem I/O */
26               __u64 stx_attributes;  /* Extra file attribute indicators */
27               __u32 stx_nlink;       /* Number of hard links */
28               __u32 stx_uid;         /* User ID of owner */
29               __u32 stx_gid;         /* Group ID of owner */
30               __u16 stx_mode;        /* File type and mode */
31               __u64 stx_ino;         /* Inode number */
32               __u64 stx_size;        /* Total size in bytes */
33               __u64 stx_blocks;      /* Number of 512B blocks allocated */
34               __u64 stx_attributes_mask;
35                                      /* Mask to show what's supported
36                                         in stx_attributes */
37
38               /* The following fields are file timestamps */
39               struct statx_timestamp stx_atime;  /* Last access */
40               struct statx_timestamp stx_btime;  /* Creation */
41               struct statx_timestamp stx_ctime;  /* Last status change */
42               struct statx_timestamp stx_mtime;  /* Last modification */
43
44               /* If this file represents a device, then the next two
45                  fields contain the ID of the device */
46               __u32 stx_rdev_major;  /* Major ID */
47               __u32 stx_rdev_minor;  /* Minor ID */
48
49               /* The next two fields contain the ID of the device
50                  containing the filesystem where the file resides */
51               __u32 stx_dev_major;   /* Major ID */
52               __u32 stx_dev_minor;   /* Minor ID */
53           };
54
55       The file timestamps are structures of the following type:
56
57           struct statx_timestamp {
58               __s64 tv_sec;    /* Seconds since the Epoch (UNIX time) */
59               __u32 tv_nsec;   /* Nanoseconds since tv_sec */
60           };
61
62       (Note that reserved space and padding is omitted.)
63
64   Invoking statx():
65       To  access  a  file's  status,  no permissions are required on the file
66       itself, but in the case of statx() with a  pathname,  execute  (search)
67       permission  is required on all of the directories in pathname that lead
68       to the file.
69
70       statx() uses pathname, dirfd, and flags to identify the target file  in
71       one of the following ways:
72
73       An absolute pathname
74              If pathname begins with a slash, then it is an absolute pathname
75              that identifies  the  target  file.   In  this  case,  dirfd  is
76              ignored.
77
78       A relative pathname
79              If  pathname is a string that begins with a character other than
80              a slash and dirfd is AT_FDCWD, then pathname is a relative path‐
81              name that is interpreted relative to the process's current work‐
82              ing directory.
83
84       A directory-relative pathname
85              If pathname is a string that begins with a character other  than
86              a  slash  and dirfd is a file descriptor that refers to a direc‐
87              tory, then pathname is a relative pathname that  is  interpreted
88              relative to the directory referred to by dirfd.
89
90       By file descriptor
91              If  pathname  is  an  empty string and the AT_EMPTY_PATH flag is
92              specified in flags (see below), then the target file is the  one
93              referred to by the file descriptor dirfd.
94
95       flags  can  be  used to influence a pathname-based lookup.  A value for
96       flags is constructed by ORing together zero or more  of  the  following
97       constants:
98
99       AT_EMPTY_PATH
100              If  pathname is an empty string, operate on the file referred to
101              by dirfd (which may have been obtained using the open(2)  O_PATH
102              flag).   In  this case, dirfd can refer to any type of file, not
103              just a directory.
104
105              If dirfd is AT_FDCWD, the call operates on the  current  working
106              directory.
107
108              This  flag  is  Linux-specific; define _GNU_SOURCE to obtain its
109              definition.
110
111       AT_NO_AUTOMOUNT
112              Don't automount the terminal ("basename") component of  pathname
113              if  it  is  a directory that is an automount point.  This allows
114              the caller to gather attributes of an  automount  point  (rather
115              than  the  location  it  would mount).  This flag can be used in
116              tools that scan directories to prevent  mass-automounting  of  a
117              directory  of automount points.  The AT_NO_AUTOMOUNT flag has no
118              effect if the mount point has already been mounted  over.   This
119              flag is Linux-specific; define _GNU_SOURCE to obtain its defini‐
120              tion.
121
122       AT_SYMLINK_NOFOLLOW
123              If pathname is a symbolic link, do not dereference  it:  instead
124              return information about the link itself, like lstat(2).
125
126       flags can also be used to control what sort of synchronization the ker‐
127       nel will do when querying a file on a remote filesystem.  This is  done
128       by ORing in one of the following values:
129
130       AT_STATX_SYNC_AS_STAT
131              Do  whatever stat(2) does.  This is the default and is very much
132              filesystem-specific.
133
134       AT_STATX_FORCE_SYNC
135              Force the attributes to be synchronized with the  server.   This
136              may  require  that a network filesystem perform a data writeback
137              to get the timestamps correct.
138
139       AT_STATX_DONT_SYNC
140              Don't synchronize anything, but rather just  take  whatever  the
141              system  has cached if possible.  This may mean that the informa‐
142              tion returned is approximate, but, on a network  filesystem,  it
143              may not involve a round trip to the server - even if no lease is
144              held.
145
146       The mask argument to statx() is used to tell the  kernel  which  fields
147       the  caller  is interested in.  mask is an ORed combination of the fol‐
148       lowing constants:
149
150           STATX_TYPE          Want stx_mode & S_IFMT
151           STATX_MODE          Want stx_mode & ~S_IFMT
152           STATX_NLINK         Want stx_nlink
153           STATX_UID           Want stx_uid
154           STATX_GID           Want stx_gid
155           STATX_ATIME         Want stx_atime
156           STATX_MTIME         Want stx_mtime
157           STATX_CTIME         Want stx_ctime
158           STATX_INO           Want stx_ino
159           STATX_SIZE          Want stx_size
160           STATX_BLOCKS        Want stx_blocks
161           STATX_BASIC_STATS   [All of the above]
162           STATX_BTIME         Want stx_btime
163           STATX_ALL           [All currently available fields]
164
165       Note that, in general, the kernel does not reject values in mask  other
166       than the above.  (For an exception, see EINVAL in errors.)  Instead, it
167       simply informs the caller which values are supported by this kernel and
168       filesystem  via the statx.stx_mask field.  Therefore, do not simply set
169       mask to UINT_MAX (all bits set), as  one  or  more  bits  may,  in  the
170       future, be used to specify an extension to the buffer.
171
172   The returned information
173       The  status  information  for  the target file is returned in the statx
174       structure pointed to by statxbuf.  Included in this is  stx_mask  which
175       indicates  what  other information has been returned.  stx_mask has the
176       same format as the mask argument and bits are set  in  it  to  indicate
177       which fields have been filled in.
178
179       It  should  be  noted  that  the  kernel may return fields that weren't
180       requested and may fail to return fields that were requested,  depending
181       on what the backing filesystem supports.  (Fields that are given values
182       despite being unrequested  can  just  be  ignored.)   In  either  case,
183       stx_mask will not be equal mask.
184
185       If  a  filesystem  does  not  support  a field or if it has an unrepre‐
186       sentable value (for instance, a file with an  exotic  type),  then  the
187       mask  bit  corresponding to that field will be cleared in stx_mask even
188       if the user asked for it and a dummy value will be filled in  for  com‐
189       patibility  purposes if one is available (e.g., a dummy UID and GID may
190       be specified to mount under some circumstances).
191
192       A filesystem may also fill in fields that the caller didn't ask for  if
193       it has values for them available and the information is available at no
194       extra cost.  If this happens, the corresponding bits  will  be  set  in
195       stx_mask.
196
197       Note:  for  performance and simplicity reasons, different fields in the
198       statx structure may contain state information  from  different  moments
199       during  the  execution of the system call.  For example, if stx_mode or
200       stx_uid is changed by another process by calling chmod(2) or  chown(2),
201       stat()  might return the old stx_mode together with the new stx_uid, or
202       the old stx_uid together with the new stx_mode.
203
204       Apart from stx_mask (which is described above), the fields in the statx
205       structure are:
206
207       stx_blksize
208              The "preferred" block size for efficient filesystem I/O.  (Writ‐
209              ing to a file in smaller chunks may cause an  inefficient  read-
210              modify-rewrite.)
211
212       stx_attributes
213              Further  status  information  about the file (see below for more
214              information).
215
216       stx_nlink
217              The number of hard links on a file.
218
219       stx_uid
220              This field contains the user ID of the owner of the file.
221
222       stx_gid
223              This field contains the ID of the group owner of the file.
224
225       stx_mode
226              The file type and mode.  See inode(7) for details.
227
228       stx_ino
229              The inode number of the file.
230
231       stx_size
232              The size of the file (if it is a  regular  file  or  a  symbolic
233              link)  in  bytes.   The size of a symbolic link is the length of
234              the pathname it contains, without a terminating null byte.
235
236       stx_blocks
237              The number of blocks allocated to the file  on  the  medium,  in
238              512-byte units.  (This may be smaller than stx_size/512 when the
239              file has holes.)
240
241       stx_attributes_mask
242              A mask indicating which bits in stx_attributes are supported  by
243              the VFS and the filesystem.
244
245       stx_atime
246              The file's last access timestamp.
247
248       stx_btime
249              The file's creation timestamp.
250
251       stx_ctime
252              The file's last status change timestamp.
253
254       stx_mtime
255              The file's last modification timestamp.
256
257       stx_dev_major and stx_dev_minor
258              The device on which this file (inode) resides.
259
260       stx_rdev_major and stx_rdev_minor
261              The  device  that this file (inode) represents if the file is of
262              block or character device type.
263
264       For further information on the above fields, see inode(7).
265
266   File attributes
267       The stx_attributes field contains a set of  ORed  flags  that  indicate
268       additional attributes of the file.  Note that any attribute that is not
269       indicated as supported by stx_attributes_mask has no usable value here.
270       The    bits    in    stx_attributes_mask   correspond   bit-by-bit   to
271       stx_attributes.
272
273       The flags are as follows:
274
275       STATX_ATTR_COMPRESSED
276              The file is compressed by the  filesystem  and  may  take  extra
277              resources to access.
278
279       STATX_ATTR_IMMUTABLE
280              The file cannot be modified: it cannot be deleted or renamed, no
281              hard links can be created to this file and no data can be  writ‐
282              ten to it.  See chattr(1).
283
284       STATX_ATTR_APPEND
285              The  file can only be opened in append mode for writing.  Random
286              access writing is not permitted.  See chattr(1).
287
288       STATX_ATTR_NODUMP
289              File is not a candidate for backup when a backup program such as
290              dump(8) is run.  See chattr(1).
291
292       STATX_ATTR_ENCRYPTED
293              A  key  is required for the file to be encrypted by the filesys‐
294              tem.
295
296       STATX_ATTR_VERITY (since Linux 5.5)
297              The file has fs-verity enabled.  It cannot be  written  to,  and
298              all  reads from it will be verified against a cryptographic hash
299              that covers the entire file (e.g., via a Merkle tree).
300

RETURN VALUE

302       On success, zero is returned.  On error, -1 is returned, and  errno  is
303       set appropriately.
304

ERRORS

306       EACCES Search  permission  is  denied for one of the directories in the
307              path prefix of pathname.  (See also path_resolution(7).)
308
309       EBADF  dirfd is not a valid open file descriptor.
310
311       EFAULT pathname or statxbuf is NULL or points to a location outside the
312              process's accessible address space.
313
314       EINVAL Invalid flag specified in flags.
315
316       EINVAL Reserved  flag specified in mask.  (Currently, there is one such
317              flag, designated by the constant STATX__RESERVED, with the value
318              0x80000000U.)
319
320       ELOOP  Too  many  symbolic links encountered while traversing the path‐
321              name.
322
323       ENAMETOOLONG
324              pathname is too long.
325
326       ENOENT A component of pathname does not exist, or pathname is an  empty
327              string and AT_EMPTY_PATH was not specified in flags.
328
329       ENOMEM Out of memory (i.e., kernel memory).
330
331       ENOTDIR
332              A component of the path prefix of pathname is not a directory or
333              pathname is relative and dirfd is a file descriptor referring to
334              a file other than a directory.
335

VERSIONS

337       statx() was added to Linux in kernel 4.11; library support was added in
338       glibc 2.28.
339

CONFORMING TO

341       statx() is Linux-specific.
342

SEE ALSO

344       ls(1), stat(1), access(2), chmod(2),  chown(2),  readlink(2),  stat(2),
345       utime(2), capabilities(7), inode(7), symlink(7)
346

COLOPHON

348       This  page  is  part of release 5.07 of the Linux man-pages project.  A
349       description of the project, information about reporting bugs,  and  the
350       latest     version     of     this    page,    can    be    found    at
351       https://www.kernel.org/doc/man-pages/.
352
353
354
355Linux                             2020-04-11                          STATX(2)
Impressum