--- name: "extattr_get_file" section: "2" platform: "linux" package: "freebsd-manpages" version: "6.0-5" release: "Debian 4.0 (Etch)" platforms: ["linux", "freebsd"] url: "https://new.carta.tech/extattr_get_file" --- # extattr\_get\_file(2) system calls to manipulate VFS extended attributes ## NAME **extattr\_get\_fd**, **extattr\_set\_fd**, **extattr\_delete\_fd**, **extattr\_list\_fd**, **extattr\_get\_file**, **extattr\_set\_file**, **extattr\_delete\_file**, **extattr\_list\_file**, **extattr\_get\_link**, **extattr\_set\_link**, **extattr\_delete\_link**, **extattr\_list\_link** – system calls to manipulate VFS extended attributes ## LIBRARY Standard C Library (libc, -lc) ## SYNOPSIS **#include \** **#include \** **#include \** *ssize\_t*\ **extattr\_get\_fd**(*int fd*, *int attrnamespace*, *const char \*attrname*, *void \*data*, *size\_t nbytes*); *int*\ **extattr\_set\_fd**(*int fd*, *int attrnamespace*, *const char \*attrname*, *const void \*data*, *size\_t nbytes*); *int*\ **extattr\_delete\_fd**(*int fd*, *int attrnamespace*, *const char \*attrname*); *ssize\_t*\ **extattr\_list\_fd**(*int fd*, *int attrnamespace*, *void \*data*, *size\_t nbytes*); *ssize\_t*\ **extattr\_get\_file**(*const char \*path*, *int attrnamespace*, *const char \*attrname*, *void \*data*, *size\_t nbytes*); *int*\ **extattr\_set\_file**(*const char \*path*, *int attrnamespace*, *const char \*attrname*, *const void \*data*, *size\_t nbytes*); *int*\ **extattr\_delete\_file**(*const char \*path*, *int attrnamespace*, *const char \*attrname*); *ssize\_t*\ **extattr\_list\_file**(*const char \*path*, *int attrnamespace*, *void \*data*, *size\_t nbytes*); *ssize\_t*\ **extattr\_get\_link**(*const char \*path*, *int attrnamespace*, *const char \*attrname*, *void \*data*, *size\_t nbytes*); *int*\ **extattr\_set\_link**(*const char \*path*, *int attrnamespace*, *const char \*attrname*, *const void \*data*, *size\_t nbytes*); *int*\ **extattr\_delete\_link**(*const char \*path*, *int attrnamespace*, *const char \*attrname*); *ssize\_t*\ **extattr\_list\_link**(*const char \*path*, *int attrnamespace*, *void \*data*, *size\_t nbytes*); ## DESCRIPTION Named extended attributes are meta-data associated with vnodes representing files and directories. They exist as "name=value" pairs within a set of namespaces. The **extattr\_get\_file**() system call retrieves the value of the specified extended attribute into a buffer pointed to by *data* of size *nbytes*. The **extattr\_set\_file**() system call sets the value of the specified extended attribute to the data described by *data*. The **extattr\_delete\_file**() system call deletes the extended attribute specified. The **extattr\_list\_file**() returns a list of attributes present in the requested namespace. Each list entry consists of a single byte containing the length of the attribute name, followed by the attribute name. The attribute name is not terminated by ASCII 0 (nul). The **extattr\_get\_file**(), and **extattr\_list\_file**() calls consume the *data* and *nbytes* arguments in the style of [read(2)](/read/2.md); **extattr\_set\_file**() consumes these arguments in the style of [write(2)](/write/2.md). If *data* is NULL in a call to **extattr\_get\_file**() then the size of defined extended attribute data will be returned, rather than the quantity read, permitting applications to test the size of the data without performing a read. The **extattr\_delete\_link**(), **extattr\_get\_link**(), and **extattr\_set\_link**() system calls behave in the same way as their \_file counterparts, except that they do not follow symlinks. The **extattr\_get\_fd**(), **extattr\_set\_fd**(), and **extattr\_delete\_fd**() calls are identical to their "\_file" counterparts except for the first argument. The "\_fd" functions take a file descriptor, while the "\_file" functions take a path. Both arguments describe a file associated with the extended attribute that should be manipulated. The following arguments are common to all the system calls described here: - *attrnamespace* the namespace in which the extended attribute resides; see [extattr(9)](/extattr/9.md) - *attrname* the name of the extended attribute Named extended attribute semantics vary by file system implementing the call. Not all operations may be supported for a particular attribute. Additionally, the format of the data in *data* is attribute-specific. For more information on named extended attributes, please see [extattr(9)](/extattr/9.md). ## CAVEAT This interface is under active development, and as such is subject to change as applications are adapted to use it. Developers are discouraged from relying on its stability. ## RETURN VALUES If successful, the **extattr\_get\_file**() and **extattr\_set\_file**() calls return the number of bytes that were read or written from the *data*, respectively, or if *data* was NULL, then **extattr\_get\_file**() returns the number of bytes available to read. If any of the calls are unsuccessful, the value -1 is returned and the global variable *errno* is set to indicate the error. The **extattr\_delete\_file()** function returns the value 0 if successful; otherwise the value -1 is returned and the global variable errno is set to indicate the error. ## ERRORS The following errors may be returned by the system calls themselves. Additionally, the file system implementing the call may return any other errors it desires. - \[EFAULT\] The *attrnamespace* and *attrname* arguments, or the memory range defined by *data* and *nbytes* point outside the process's allocated address space. - \[ENAMETOOLONG\] The attribute name was longer than EXTATTR\_MAXNAMELEN. The **extattr\_get\_fd**(), **extattr\_set\_fd**(), and **extattr\_delete\_fd**() system calls may also fail if: - \[EBADF\] The file descriptor referenced by *fd* was invalid. Additionally, the **extattr\_get\_file**(), **extattr\_set\_file**(), and **extattr\_delete\_file**() calls may also fail due to the following errors: - \[ENOATTR\] The requested attribute was not defined for this file. - \[ENOTDIR\] A component of the path prefix is not a directory. - \[ENAMETOOLONG\] A component of a pathname exceeded 255 characters, or an entire path name exceeded 1023 characters. - \[ENOENT\] A component of the path name that must exist does not exist. - \[EACCES\] Search permission is denied for a component of the path prefix. ## SEE ALSO [extattr(3)](/extattr/3.md), [getextattr(8)](/getextattr/8.md), [setextattr(8)](/setextattr/8.md), [extattr(9)](/extattr/9.md), [VOP\_GETEXTATTR(9)](/VOP_GETEXTATTR/9.md), [VOP\_SETEXTATTR(9)](/VOP_SETEXTATTR/9.md) ## HISTORY Extended attribute support was developed as part of the TrustedBSD Project, and introduced in FreeBSD 5.0. It was developed to support security extensions requiring additional labels to be associated with each file or directory. ## BUGS In earlier versions of this API, passing an empty string for the attribute name to **extattr\_get\_fd**(), **extattr\_get\_file**(), or **extattr\_get\_link**() would return the list of attributes defined for the target object. This interface has been deprecated in preference to using the explicit list API, and should not be used.