Lists the extended attributes associated with a file.
#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);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.
| Item | Description |
|---|---|
| path | The path name of the file. |
| list | A pointer to a buffer in which the list of attributes will be stored. |
| size | The size of the buffer. |
| filedes | A file descriptor for the file. |
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.
| Item | Description |
|---|---|
| EACCES | Caller lacks read permission on the base file, or lacks the appropriate ACL privileges for named attribute read. |
| EFAULT | A bad address was passed for path or list. |
| EFORMAT | File system is capable of supporting EAs, but EAs are disabled. |
| ENOTSUP | Extended attributes are not supported by the file system. |
| ERANGE | The size of the list buffer is too small to hold the result. |