listea Subroutine

Purpose

Lists the extended attributes associated with a file.

Syntax

#include <sys/ea.h>

ssize_t listea(const char *path, char *list, size_t size);
ssize_t flistea (int filedes, char *list, size_t size);
ssize_t llistea (const char *path, char *list, size_t size);

Description

Extended attributes are name:value pairs associated with the file system objects (such as files, directories, and symlinks). They are extensions to the normal attributes that are associated with all objects in the file system (that is, the stat(2) data).

Do not define an extended attribute name with eight characters prefix "(0xF8)SYSTEM(0xF8)". Prefix "(0xF8)SYSTEM(0xF8)" is reserved for system use only.

The listea subroutine retrieves the list of extended attribute names associated with the given path in the file system. The list is the set of (NULL-terminated) names, one after the other. Names of extended attributes to which the calling process does not have access might be omitted from the list. The length of the attribute name list is returned. The flistea subroutine is identical to listea, except that it takes a file descriptor instead of a path. The llistea subroutine is identical to listea, except, in the case of a symbolic link, the link itself is interrogated, not the file that it refers to.

An empty buffer of size 0 can be passed into these calls to return the current size of the list of extended attribute names, which can be used to estimate whether the size of a buffer is sufficiently large to hold the list of names.

Parameters

Return Values

If the listea subroutine succeeds, a nonnegative number is returned that indicates the length in bytes of the attribute name list. Upon failure, -1 is returned and errno is set appropriately.

Error Codes