Linux程序员手册 第2部分
更新日期： 2020-08-13

名称

statx-获取文件状态(扩展)

语法

#include <sys/types.h>
#include <sys/stat.h>
#include <unistd.h>
#include <fcntl.h>           /* Definition of AT_* constants */

int statx(int dirfd, const char *pathname, int flags,
          unsigned int mask, struct statx *statxbuf);

说明

此函数返回有关文件的信息，并将其存储在statxbuf指向的缓冲区中。返回的缓冲区是以下类型的结构：

struct statx {
    __u32 stx_mask;        /* Mask of bits indicating
                              filled fields */
    __u32 stx_blksize;     /* Block size for filesystem I/O */
    __u64 stx_attributes;  /* Extra file attribute indicators */
    __u32 stx_nlink;       /* Number of hard links */
    __u32 stx_uid;         /* User ID of owner */
    __u32 stx_gid;         /* Group ID of owner */
    __u16 stx_mode;        /* File type and mode */
    __u64 stx_ino;         /* Inode number */
    __u64 stx_size;        /* Total size in bytes */
    __u64 stx_blocks;      /* Number of 512B blocks allocated */
    __u64 stx_attributes_mask;
                           /* Mask to show what's supported
                              in stx_attributes */

    /* The following fields are file timestamps */
    struct statx_timestamp stx_atime;  /* Last access */
    struct statx_timestamp stx_btime;  /* Creation */
    struct statx_timestamp stx_ctime;  /* Last status change */
    struct statx_timestamp stx_mtime;  /* Last modification */

    /* If this file represents a device, then the next two
       fields contain the ID of the device */
    __u32 stx_rdev_major;  /* Major ID */
    __u32 stx_rdev_minor;  /* Minor ID */

    /* The next two fields contain the ID of the device
       containing the filesystem where the file resides */
    __u32 stx_dev_major;   /* Major ID */
    __u32 stx_dev_minor;   /* Minor ID */
};

文件时间戳是以下类型的结构：

struct statx_timestamp {
    __s64 tv_sec;    /* Seconds since the Epoch (UNIX time) */
    __u32 tv_nsec;   /* Nanoseconds since tv_sec */
};

(请注意，保留空间和填充被省略。)

Invoking statx():

要访问文件的状态，不需要文件本身的权限，但是对于带有路径名的statx()，需要对导致文件的路径名中的所有目录执行(搜索)权限。

statx()使用路径名，dirfd和标志以下列方式之一标识目标文件：

An absolute pathname

如果路径名以斜杠开头，则它是标识目标文件的绝对路径名。在这种情况下，dirfd被忽略。

A relative pathname

如果pathname是以斜杠以外的其他字符开头的字符串，而dirfd是AT_FDCWD，则pathname是相对于该进程当前工作目录的相对路径名。

A directory-relative pathname

如果pathname是一个以除斜杠以外的字符开头的字符串，并且dirfd是引用目录的文件描述符，则pathname是相对路径名，相对于dirfd引用的目录进行解释。

By file descriptor

如果路径名是一个空字符串，并且在标志中指定了AT_EMPTY_PATH标志(请参见下文)，则目标文件就是文件描述符dirfd所引用的文件。

标志可用于影响基于路径名的查找。标志的值是通过对以下常量中的零个或多个进行"或"运算来构造的：

AT_EMPTY_PATH

如果路径名是空字符串，请对dirfd引用的文件进行操作(该文件可能已使用open(2)O_PATH标志获得)。在这种情况下，dirfd可以引用任何类型的文件，而不仅仅是目录。

如果dirfd为AT_FDCWD，则调用在当前工作目录上进行。

该标志是特定于Linux的。定义_GNU_SOURCE以获得其定义。

AT_NO_AUTOMOUNT

如果它是自动挂载点的目录，请不要自动挂载路径名的终端(" basename")组件。这允许调用者收集自动挂载点的属性(而不是其将挂载的位置)。可以在扫描目录的工具中使用此标志，以防止自动挂载点目录的大规模自动挂载。如果安装点已经被安装，则AT_NO_AUTOMOUNT标志无效。该标志是特定于Linux的。定义_GNU_SOURCE以获得其定义。

AT_SYMLINK_NOFOLLOW

如果路径名是符号链接，请不要取消引用它：而是返回有关链接本身的信息，例如lstat(2)。

标志还可以用于控制内核在查询远程文件系统上的文件时进行哪种同步。这是通过对以下值之一进行"或"运算来完成的：

AT_STATX_SYNC_AS_STAT

做stat(2)做的任何事情。这是默认设置，并且非常特定于文件系统。

AT_STATX_FORCE_SYNC

强制属性与服务器同步。这可能要求网络文件系统执行数据写回操作以使时间戳正确。

AT_STATX_DONT_SYNC

不要同步任何内容，而是尽可能地获取系统已缓存的所有内容。这可能意味着返回的信息是近似的，但是，在网络文件系统上，即使没有租约，也可能不会涉及到服务器的往返行程。

statx()的mask参数用于告诉内核调用者感兴趣的字段。mask是以下常量的ORed组合：

请注意，通常，内核不拒绝除上述以外的掩码值。 (有关异常，请参阅EINVAL中的错误。)相反，它仅通过statx.stx_mask字段通知调用方此内核和文件系统支持哪些值。因此，请勿简单地将掩码设置为UINT_MAX(所有位均已设置)，因为将来可能会使用一个或多个位来指定对缓冲区的扩展。

The returned information

目标文件的状态信息在statxbuf指向的statx结构中返回。其中包括stx_mask，它指示还返回了哪些其他信息。 stx_mask具有与mask参数相同的格式，并在其中设置了位以指示已填写的字段。

应该注意的是，内核可能会返回未请求的字段，并且可能无法返回所请求的字段，具体取决于后备文件系统支持的内容。 (尽管被请求，但仍被赋予值的字段可以被忽略。)在两种情况下，stx_mask都不等于mask。

如果文件系统不支持字段，或者具有无法表示的值(例如，具有奇异类型的文件)，则即使用户要求提供该字段和一个哑元，也会在stx_mask中清除与该字段对应的掩码位如果有一个可用的值，则出于兼容性目的将填充该值(例如，在某些情况下，可以指定虚拟UID和GID进行安装)。

文件系统还可以填写调用者不要求的字段，如果它具有可用的值，并且信息可用，则无需额外费用。如果发生这种情况，将在stx_mask中设置相应的位。

注意：出于性能和简便性的考虑，statx结构中的不同字段可能包含系统调用执行期间不同时刻的状态信息。例如，如果另一个进程通过调用chmod(2)或chown(2)来更改stx_mode或stx_uid，则stat()可能会返回旧的stx_mode和新的stx_uid，或者旧的stx_uid和新的stx_mode。

除了上面描述的stx_mask之外，statx结构中的字段是：

stx_blksize

有效文件系统I / O的"首选"块大小。 (以较小的块写入文件可能会导致读取-修改-重写效率低下。)

stx_attributes

有关文件的更多状态信息(有关更多信息，请参见下文)。

stx_nlink

文件上的硬链接数。

stx_uid

该字段包含文件所有者的用户标识。

stx_gid

该字段包含文件的组所有者的ID。

stx_mode

文件类型和模式。有关详细信息，请参见inode(7)。

stx_ino

文件的索引节点号。

stx_size

文件的大小(如果是常规文件或符号链接)以字节为单位。符号链接的大小是它包含的路径名的长度，没有终止的空字节。

stx_blocks

分配给介质上文件的块数，以512字节为单位。 (当文件有孔时，它可能小于stx_size / 512。)

stx_attributes_mask

一个掩码，指示VFS和文件系统支持stx_attributes中的哪些位。

stx_atime

文件的最后访问时间戳。

stx_btime

文件的创建时间戳。

stx_ctime

文件的最后状态更改时间戳。

stx_mtime

文件的最后修改时间戳。

stx_dev_majorand stx_dev_minor

该文件(inode)所在的设备。

stx_rdev_majorand stx_rdev_minor

该文件(inode)代表的设备，该文件是块设备还是字符设备类型。

有关以上字段的更多信息，请参见inode(7)。

File attributes

stx_attributes字段包含一组ORed标志，这些标志指示文件的其他属性。请注意，任何未表示为stx_attributes_mask支持的属性在这里都没有可用的值。 stx_attributes_mask中的位与stx_attributes逐位对应。

标志如下：

STATX_ATTR_COMPRESSED

该文件由文件系统压缩，可能会占用额外的资源才能访问。

STATX_ATTR_IMMUTABLE

该文件无法修改：无法删除或重命名，无法创建与此文件的硬链接，也不能向其写入数据。请参见chattr(1)。

STATX_ATTR_APPEND

只能以追加模式打开文件进行写入。不允许随机访问写入。请参见chattr(1)。

STATX_ATTR_NODUMP

运行诸如dump(8)之类的备份程序时，文件不是备份的候选对象。请参见chattr(1)。

STATX_ATTR_ENCRYPTED

要由文件系统加密文件，需要密钥。

STATX_ATTR_VERITY(since Linux 5.5)

该文件已启用fs-verity。无法对其进行写入，并且所有对它的读取都将根据覆盖整个文件的加密哈希进行验证(例如，通过Merkle树)。

返回值

成功时，返回零。如果出错，则返回-1，并正确设置errno。

错误说明

EACCES

路径名的路径前缀中的目录之一的搜索权限被拒绝。 (另请参见path_resolution(7)。)

EBADF

dirfd不是有效的打开文件描述符。

EFAULT

pathname或statxbuf为NULL或指向进程的可访问地址空间之外的位置。

EINVAL

标志中指定的标志无效。

EINVAL

掩码中指定的保留标志。 (当前有一个这样的标志，由常量STATX__RESERVED表示，其值为0x80000000U。)

ELOOP

遍历路径名时遇到太多符号链接。

ENAMETOOLONG

路径名太长。

ENOENT

路径名的组件不存在，或者路径名是空字符串，并且未在标志中指定AT_EMPTY_PATH。

ENOMEM

内存不足(即内核内存)。

ENOTDIR

路径名的路径前缀的组成部分不是目录，或者路径名是相对的，并且dirfd是引用目录以外的文件的文件描述符。

版本

statx()在内核4.11中添加到Linux；库支持在glibc 2.28中添加。

遵循规范

statx()是特定于Linux的。

另外参见

ls(1)，stat(1)，access(2)，chmod(2)，chown(2)，readlink(2)，stat(2)，utime(2)，capabilities(7)，inode(7)，符号链接(7)

出版信息

这个页面是Linux手册页项目5.08版的一部分。有关项目的说明、有关报告错误的信息以及此页面的最新版本，请访问https://www.kernel.org/doc/man-pages/。