getea Subroutine
Purpose
Reads the value of an extended attribute.
Syntax
#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);
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 the eight characters prefix "(0xF8)SYSTEM(0xF8)". Prefix "(0xF8)SYSTEM(0xF8)" is reserved for system use only.
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.
Parameters
| 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.