extattr (2)
Leading comments
Copyright (c) 2001 Dima Dorfman <dima@unixfreak.org> Copyright (c) 2003 Robert Watson <rwatson@FreeBSD.org> All rights reserved. Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: 1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. 2. Redistributions in binary form must reproduce the above copyright notice, this list of ...
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 attributesLIBRARY
Lb libcSYNOPSIS
In sys/types.h In sys/extattr.h Ft ssize_t Fn extattr_get_fd int fd int attrnamespace const char *attrname void *data size_t nbytes Ft ssize_t Fn extattr_set_fd int fd int attrnamespace const char *attrname const void *data size_t nbytes Ft int Fn extattr_delete_fd int fd int attrnamespace const char *attrname Ft ssize_t Fn extattr_list_fd int fd int attrnamespace void *data size_t nbytes Ft ssize_t Fn extattr_get_file const char *path int attrnamespace const char *attrname void *data size_t nbytes Ft ssize_t Fn extattr_set_file const char *path int attrnamespace const char *attrname const void *data size_t nbytes Ft int Fn extattr_delete_file const char *path int attrnamespace const char *attrname Ft ssize_t Fn extattr_list_file const char *path int attrnamespace void *data size_t nbytes Ft ssize_t Fn extattr_get_link const char *path int attrnamespace const char *attrname void *data size_t nbytes Ft ssize_t Fn extattr_set_link const char *path int attrnamespace const char *attrname const void *data size_t nbytes Ft int Fn extattr_delete_link const char *path int attrnamespace const char *attrname Ft ssize_t Fn extattr_list_link const char *path int attrnamespace void *data size_t nbytesDESCRIPTION
Named extended attributes are meta-data associated with vnodes representing files and directories. They exist as Qq Li name=value pairs within a set of namespaces.The Fn extattr_get_file system call retrieves the value of the specified extended attribute into a buffer pointed to by Fa data of size Fa nbytes . The Fn extattr_set_file system call sets the value of the specified extended attribute to the data described by Fa data . The Fn extattr_delete_file system call deletes the extended attribute specified. The Fn 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 Fn extattr_get_file , and Fn extattr_list_file calls consume the Fa data and Fa nbytes arguments in the style of read(2); Fn extattr_set_file consumes these arguments in the style of write(2).
If Fa data is NULL in a call to Fn extattr_get_file and Fn extattr_list_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 Fn extattr_delete_link , Fn extattr_get_link , and Fn extattr_set_link system calls behave in the same way as their _file counterparts, except that they do not follow symlinks.
The Fn extattr_get_fd , Fn extattr_set_fd , Fn extattr_delete_fd , and Fn extattr_list_fd , calls are identical to their Qq Li _file counterparts except for the first argument. The Qq Li _fd functions take a file descriptor, while the Qq Li _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:
- Fa attrnamespace
- the namespace in which the extended attribute resides; see extattr(9)
- Fa 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 Fa data is attribute-specific.
For more information on named extended attributes, please see extattr(9).
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 Fn extattr_get_file , Fn extattr_set_file , and Fn extattr_list_file calls return the number of bytes that were read or written from the Fa data , respectively, or if Fa data was NULL then Fn extattr_get_file and Fn extattr_list_file return 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.Rv -std extattr_delete_file
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.- Bq Er EFAULT
- The Fa attrnamespace and Fa attrname arguments, or the memory range defined by Fa data and Fa nbytes point outside the process's allocated address space.
- Bq Er ENAMETOOLONG
- The attribute name was longer than EXTATTR_MAXNAMELEN
The Fn extattr_get_fd , Fn extattr_set_fd , Fn extattr_delete_fd , and Fn extattr_list_fd system calls may also fail if:
- Bq Er EBADF
- The file descriptor referenced by Fa fd was invalid.
Additionally, the Fn extattr_get_file , Fn extattr_set_file , and Fn extattr_delete_file calls may also fail due to the following errors:
- Bq Er ENOATTR
- The requested attribute was not defined for this file.
- Bq Er ENOTDIR
- A component of the path prefix is not a directory.
- Bq Er ENAMETOOLONG
- A component of a pathname exceeded 255 characters, or an entire path name exceeded 1023 characters.
- Bq Er ENOENT
- A component of the path name that must exist does not exist.
- Bq Er EACCES
- Search permission is denied for a component of the path prefix.