setea Subroutine

Purpose

Sets an extended attribute value.

Syntax

#include <sys/ea.h>

int setea(const char *path, const char *name,
        void *value, size_t size, int flags);
int fsetea(int filedes, const char *name,
        void *value, size_t size, int flags);
int lsetea(const char *path, const char *name,
        void *value, size_t size, int flags);

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 8-character prefix "(0xF8)SYSTEM(0xF8)". Prefix "(0xF8)SYSTEM(0xF8)" is reserved for system use only.

Note: 0xF8 represents a non-printable character.

The setea subroutine sets the value of the extended attribute identified by name and associated with the given path in the file system. The size of the value must be specified. The fsetea subroutine is identical to setea, except that it takes a file descriptor instead of a path. The lsetea subroutine is identical to setea, 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 the value of an attribute. The value of an extended attribute is an opaque byte stream of specified length.
size The length of the value.
filedes A file descriptor for the file.
flags None are defined at this time.

Return Values

If the setea subroutine succeeds, 0 is returned. Upon failure, -1 is returned and errno is set appropriately.

Error Codes

Item Description
EACCES Caller lacks write permission to the base file, or lacks the appropriate ACL privileges for named attribute write.
EDQUOT Because of quota enforcement, the remaining space is insufficient to store the extended attribute.
EFAULT A bad address was passed for path, name, or value.
EFORMAT File system is capable of supporting EAs, but EAs are disabled.
EINVAL No flags should be specified.
EINVAL A path-like name should not be used (such as zml/file, . and ..).
ENAMETOOLONG The path or name value is too long.
ENOSPC The remaining space is insufficient to store the extended attribute.
ENOTSUP Extended attributes are not supported by the file system.

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