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

名称

listxattr，llistxattr，flistxattr-列出扩展属性名称

语法

#include <sys/types.h>
#include <sys/xattr.h>

ssize_t listxattr(const char *path, char *list, size_t size);
ssize_t llistxattr(const char *path, char *list, size_t size);
ssize_t flistxattr(int fd, char *list, size_t size);

说明

扩展属性是与inode关联的name：value对(文件，目录，符号链接等)。它们是与系统中所有inode关联的常规属性的扩展(即stat(2)数据)。扩展属性概念的完整概述可以在xattr(7)中找到。

listxattr()检索与文件系统中给定路径关联的扩展属性名称的列表。检索到的列表放在列表中，该列表是调用方分配的缓冲区，其大小(以字节为单位)在参数大小中指定。该列表是一组(以零结尾)的名称，一个接一个。列表中可能会省略调用过程无法访问的扩展属性的名称。返回属性名称列表的长度。

llistxattr()与listxattr()相同，只是在符号链接的情况下，该链接检索的是与链接本身关联的扩展属性的名称列表，而不是它所引用的文件。

flistxattr()与listxattr()相同，仅查询fd引用的打开文件(由open(2)返回)代替路径。

单个扩展属性名称是一个以空字符结尾的字符串。该名称包括名称空间前缀；可能有几个与单个inode关联的不相交的名称空间。

如果将size指定为零，则这些调用将返回扩展属性名称列表的当前大小(并使列表保持不变)。这可以用来确定在后续调用中应提供的缓冲区的大小。 (但是，请记住，扩展属性集可能会在两个调用之间更改，因此仍然有必要检查第二个调用的返回状态。)

Example

名称列表以无序结尾的以null终止的字符串数组的形式返回(属性名称由空字节(aq \ 0aq)分隔)，如下所示：

user.name1
system.posix_acl_access
$ touch /tmp/foo
$ setfattr -n user.fred -v chocolate /tmp/foo
$ setfattr -n user.frieda -v bar /tmp/foo
$ setfattr -n user.empty /tmp/foo
$ ./listxattr /tmp/foo
user.fred: chocolate
user.frieda: bar
user.empty: <no value>
system.posix_acl_default
#include <malloc.h>
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <sys/types.h>
#include <sys/xattr.h>

int
main(int argc, char *argv[])
{
    ssize_t buflen, keylen, vallen;
    char *buf, *key, *val;

    if (argc != 2) {
        fprintf(stderr, "Usage: %s path\n", argv[0]);
        exit(EXIT_FAILURE);
    }

    /*
     * Determine the length of the buffer needed.
     */
    buflen = listxattr(argv[1], NULL, 0);
    if (buflen == -1) {
        perror("listxattr");
        exit(EXIT_FAILURE);
    }
    if (buflen == 0) {
        printf("%s has no attributes.\n", argv[1]);
        exit(EXIT_SUCCESS);
    }

    /*
     * Allocate the buffer.
     */
    buf = malloc(buflen);
    if (buf == NULL) {
        perror("malloc");
        exit(EXIT_FAILURE);
    }

    /*
     * Copy the list of attribute keys to the buffer.
     */
    buflen = listxattr(argv[1], buf, buflen);
    if (buflen == -1) {
        perror("listxattr");
        exit(EXIT_FAILURE);
    }

    /*
     * Loop over the list of zero terminated strings with the
     * attribute keys. Use the remaining buffer length to determine
     * the end of the list.
     */
    key = buf;
    while (buflen > 0) {

        /*
         * Output attribute key.
         */
        printf("%s: ", key);

        /*
         * Determine length of the value.
         */
        vallen = getxattr(argv[1], key, NULL, 0);
        if (vallen == -1)
            perror("getxattr");

        if (vallen > 0) {

            /*
             * Allocate value buffer.
             * One extra byte is needed to append 0x00.
             */
            val = malloc(vallen + 1);
            if (val == NULL) {
                perror("malloc");
                exit(EXIT_FAILURE);
            }

            /*
             * Copy value to buffer.
             */
            vallen = getxattr(argv[1], key, val, vallen);
            if (vallen == -1)
                perror("getxattr");
            else {
                /*
                 * Output attribute value.
                 */
                val[vallen] = 0;
                printf("%s", val);
            }

            free(val);
        } else if (vallen == 0)
            printf("<no value>");

        printf("\n");

        /*
         * Forward to next attribute key.
         */
        keylen = strlen(key) + 1;
        buflen -= keylen;
        key += keylen;
    }

    free(buf);
    exit(EXIT_SUCCESS);
}
system.name1##代码##user.name2##代码##

使用扩展属性实现POSIX ACL的文件系统可能会返回如下列表：

返回值

成功后，将返回一个非负数，以指示扩展属性名称列表的大小。失败时，将返回-1并正确设置errno。

错误说明

E2BIG

扩展属性名称列表的大小大于允许的最大大小。该列表无法检索。例如，在每个文件支持无限数量的扩展属性的文件系统(例如XFS)上可能会发生这种情况。参见错误。

ENOTSUP

文件系统不支持或禁用扩展属性。

ERANGE

列表缓冲区的大小太小，无法保存结果。

此外，stat(2)中记录的错误也可能发生。

版本

从内核2.4开始，这些系统调用已经在Linux上可用了。从2.3版开始提供glibc支持。

遵循规范

这些系统调用是特定于Linux的。

BUGS

如xattr(7)所述，VFS对listxattr(7)返回的扩展属性名称列表的大小施加64 kB的限制。如果附加到文件的属性名称的总大小超过此限制，则不再可能检索属性名称列表。

示例

以下程序演示了listxattr()和getxattr(2)的用法。对于其路径名作为命令行参数提供的文件，它将列出所有扩展文件属性及其值。

为了使代码保持简单，该程序假定在执行程序期间属性键和值是恒定的。生产程序应在程序执行期间期望并处理更改。例如，在两次调用listxattr()之间，属性键所需的字节数可能会增加。应用程序可以使用循环来处理这种可能性，该循环在每次失败并出现错误ERANGE时，使用更大的缓冲区重试调用(也许最多达到预定的最大尝试次数)。对getxattr(2)的调用可以类似地处理。

通过首先创建一个文件，设置一些扩展的文件属性，然后在示例程序中列出这些属性来记录以下输出。

Example output

Program source (listxattr.c)

另外参见

getfattr(1)，setfattr(1)，getxattr(2)，open(2)，removexattr(2)，setxattr(2)，stat(2)，symlink(7)，xattr(7)

出版信息

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