diff --git a/man2/statx.2 b/man2/statx.2 index 5949df69c..bff820430 100644 --- a/man2/statx.2 +++ b/man2/statx.2 @@ -113,11 +113,11 @@ struct statx_timestamp { .SS Invoking \fBstatx\fR(): .PP -To access a file's status, no permissions are required on the file itself, but -in the case of +To access a file's status, no permissions are required on the file itself, +but in the case of .BR statx () -with a path, execute (search) permission is required on all of the directories -in +with a path, +execute (search) permission is required on all of the directories in .I pathname that lead to the file. .PP @@ -133,7 +133,8 @@ to locate the target file in one of a variety of ways: .I pathname points to an absolute path and .I dirfd -is ignored. The file is looked up by name, starting from the root of the +is ignored. +The file is looked up by name, starting from the root of the filesystem as seen by the calling process. .TP [*] By cwd-relative path. @@ -148,18 +149,20 @@ The file is looked up by name, starting from the current working directory. .I pathname points to relative path and .I dirfd -indicates a file descriptor pointing to a directory. The file is looked up by -name, starting from the directory specified by +indicates a file descriptor pointing to a directory. +The file is looked up by name, starting from the directory specified by .IR dirfd . .TP [*] By file descriptor. .IR pathname " is " NULL " and " dirfd -indicates a file descriptor. The file attached to the file descriptor is -queried directly. The file descriptor may point to any type of file, not just +indicates a file descriptor. +The file attached to the file descriptor is queried directly. +The file descriptor may point to any type of file, not just a directory. .PP .I flags -can be used to influence a path-based lookup. A value for +can be used to influence a path-based lookup. +A value for .I flags is constructed by OR'ing together zero or more of the following constants: .TP @@ -210,22 +213,25 @@ instead return information about the link itself, like .BR lstat (2). .PP .I flags -can also be used to control what sort of synchronisation the kernel will do -when querying a file on a remote filesystem. This is done by OR'ing in one of -the following values: +can also be used to control what sort of synchronization the kernel will do +when querying a file on a remote filesystem. +This is done by OR'ing in one of the following values: .TP AT_STATX_SYNC_AS_STAT Do whatever .BR stat (2) -does. This is the default and is very much filesystem specific. +does. +This is the default and is very much filesystem specific. .TP AT_STATX_FORCE_SYNC -Force the attributes to be synchronised with the server. This may require that +Force the attributes to be synchronised with the server. +This may require that a network filesystem perform a data writeback to get the timestamps correct. .TP AT_STATX_DONT_SYNC Don't synchronise anything, but rather just take whatever the system has cached -if possible. This may mean that the information returned is approximate, but, +if possible. +This may mean that the information returned is approximate, but, on a network filesystem, it may not involve a round trip to the server - even if no lease is held. .PP @@ -278,7 +284,8 @@ which fields have been filled in. .PP It should be noted that the kernel may return fields that weren't requested and may fail to return fields that were requested, depending on what the backing -filesystem supports. In either case, +filesystem supports. +In either case, .I stx_mask will not be equal .IR mask . @@ -292,11 +299,10 @@ compatibility purposes if one is available (e.g. a dummy uid and gid may be specified to mount under some circumstances). .PP A filesystem may also fill in fields that the caller didn't ask for if it has -values for them available at no extra cost. If this happens, the corresponding -bits will be set in +values for them available at no extra cost. +If this happens, the corresponding bits will be set in .IR stx_mask . .PP - .\" Background: inode attributes are modified with i_mutex held, but .\" read by stat() without taking the mutex. .I Note: @@ -327,7 +333,8 @@ Apart from stx_mask (which is described above), the fields in the structure are: .TP .I stx_mode -The file type and mode. This is described in more detail below. +The file type and mode. +This is described in more detail below. .TP .I stx_size The size of the file (if it is a regular file or a symbolic link) in bytes. @@ -341,7 +348,8 @@ The number of blocks allocated to the file on the medium, in 512-byte units. when the file has holes.) .TP .I stx_blksize -The "preferred" blocksize for efficient filesystem I/O. (Writing to a file in +The "preferred" blocksize for efficient filesystem I/O. +(Writing to a file in smaller chunks may cause an inefficient read-modify-rewrite.) .TP .I stx_nlink @@ -378,32 +386,33 @@ Other routines, such as may or may not update it. .TP .I stx_btime -The file's creation timestamp. This is set on file creation and not changed -subsequently. +The file's creation timestamp. +This is set on file creation and not changed subsequently. .TP .I stx_ctime -The file's last status change timestamp. This field is changed by writing or +The file's last status change timestamp. +This field is changed by writing or by setting inode information (i.e., owner, group, link count, mode, etc.). .TP .I stx_mtime -The file's last modification timestamp. This is changed by file modifications, +The file's last modification timestamp. +This is changed by file modifications, for example, by .BR mknod (2), .BR truncate (2), .BR utime (2), and .BR write (2) -(of more than zero bytes). Moreover, the modification time of a directory is -changed by the creation or deletion of files in that directory. This field is +(of more than zero bytes). +Moreover, the modification time of a directory is +changed by the creation or deletion of files in that directory. +This field is .I not changed for changes in owner, group, hard link count, or mode. - - - .PP -Not all of the Linux filesystems implement all of the timestamp fields. Some -filesystems allow mounting in such a way that file and/or directory accesses do -not cause an update of the +Not all of the Linux filesystems implement all of the timestamp fields. +Some filesystems allow mounting in such a way that file and/or +directory accesses do not cause an update of the .I stx_atime field. (See @@ -421,7 +430,7 @@ is not updated if a file is opened with the .BR O_NOATIME ; see .BR open (2). - +.\" .SS File attributes .PP The @@ -434,15 +443,19 @@ The file is compressed by the fs and may take extra resources to access. .TP STATX_ATTR_IMMUTABLE The file cannot be modified: it cannot be deleted or renamed, no hard links can -be created to this file and no data can be written to it. See chattr(1). +be created to this file and no data can be written to it. +See chattr(1). .TP STATX_ATTR_APPEND -The file can only be opened in append mode for writing. Random access writing -is not permitted. See chattr(1). +The file can only be opened in append mode for writing. +Random access writing +is not permitted. +See chattr(1). .TP STATX_ATTR_NODUMP File is not a candidate for backup when a backup program such as dump(8) is -run. See chattr(1). +run. +See chattr(1). .TP STATX_ATTR_ENCRYPTED A key is required for the file to be encrypted by the filesystem. @@ -450,7 +463,8 @@ A key is required for the file to be encrypted by the filesystem. .PP The .I stx_mode -field contains the combined file type and mode. POSIX refers to the bits in +field contains the combined file type and mode. +POSIX refers to the bits in this field corresponding to the mask .B S_IFMT (see below) as the @@ -604,8 +618,6 @@ on a directory means that a file in that directory can be renamed or deleted only by the owner of the file, by the owner of the directory, and by a privileged process. - - .SH RETURN VALUE On success, zero is returned. On error, \-1 is returned, and