getea Subroutine


Reads the value of an extended attribute.


#include <sys/ea.h>

ssize_t getea(const char *path, const char *name,
        void *value, size_t size);
ssize_t fgetea(int filedes, const char *name, void *value, size_t size);
ssize_t lgetea(const char *path, const char *name,
        void *value, 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 the eight characters prefix "(0xF8)SYSTEM(0xF8)". Prefix "(0xF8)SYSTEM(0xF8)" is reserved for system use only.

Note: The 0xF8 prefix represents a non-printable character.

The getea subroutine retrieves the value of the extended attribute identified by name and associated with the given path in the file system. The length of the attribute value is returned. The fgetea subroutine is identical to getea, except that it takes a file descriptor instead of a path. The lgetea subroutine is identical to getea, except, in the case of a symbolic link, the link itself is interrogated rather than the file that it refers to.


Item Description
path The path name of the file.
name The name of the extended attribute. An extended attribute name is a NULL-terminated string.
value A pointer to a buffer in which the attribute will be stored. The value of an extended attribute is an opaque byte stream of specified length.
size The size of the buffer. If size is 0, getea returns the current size of the named extended attribute, which can be used to estimate whether the size of a buffer is sufficiently large enough to hold the value associated with the extended attribute.
filedes A file descriptor for the file.

Return Values

If the getea subroutine succeeds, a nonnegative number is returned that indicates the size of the extended attribute value. Upon failure, -1 is returned and errno is set appropriately.

Error Codes

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, name, or value.
EFORMAT File system is capable of supporting EAs, but EAs are disabled.
EINVAL A path-like name should not be used (such as zml/file, . and ..).
ENAMETOOLONG The path or name value is too long.
ENOATTR The named attribute does not exist, or the process has no access to this attribute.
ERANGE The size of the value buffer is too small to hold the result.
ENOTSUP Extended attributes are not supported by the file system.

The errors documented for the stat(2) system call are also applicable here.