attr_multi, attr_multif - manipulate multiple user
attributes on a filesystem object at once
C SYNOPSIS
#include <attr/attributes.h>
int attr_multi (const char *path, attr_multiop_t *oplist,
int count, int flags);
int attr_multif (int fd, attr_multiop_t *oplist,
int count, int flags);
DESCRIPTION
The attr_multi and attr_multif functions provide a way to
operate on multiple attributes of a filesystem object at
once.
Path points to a path name for a filesystem object, and fd
refers to the file descriptor associated with a file. The
oplist is an array of aattttrr_mmuullttiioopp_tt structures. Each
element in that array describes a single attribute opera
tion and provides all the information required to carry
out that operation and to check for success or failure of
that operation. Count tells how many elements are in the
oplist array.
The contents of an aattttrr_mmuullttiioopp_tt structure include the
following members:
iinntt aamm_ooppccooddee;; //** wwhhiicchh ooppeerraattiioonn ttoo ppeerrffoorrmm ((sseeee bbeellooww)) **//
iinntt aamm_eerrrroorr;; //** [[oouutt aarrgg]] rreessuulltt ooff tthhiiss ssuubb--oopp ((aann eerrrrnnoo)) **//
cchhaarr **aamm_aattttrrnnaammee;; //** aattttrriibbuuttee nnaammee ttoo wwoorrkk wwiitthh **//
cchhaarr **aamm_aattttrrvvaalluuee;; //** [[iinn//oouutt aarrgg]] aattttrriibbuuttee vvaalluuee ((rraaww bbyytteess)) **//
iinntt aamm_lleennggtthh;; //** [[iinn//oouutt aarrgg]] lleennggtthh ooff vvaalluuee **//
iinntt aamm_ffllaaggss;; //** ffllaaggss ((bbiitt--wwiissee OORR ooff ##ddeeffiinneess bbeellooww)) **//
The am_opcode field defines how the remaining fields are
to be interpreted and can take on one of the following
values:
AATTTTRR_OOPP_GGEETT //** rreettuurrnn tthhee iinnddiiccaatteedd aattttrr''ss vvaalluuee **//
AATTTTRR_OOPP_SSEETT //** sseett//ccrreeaattee tthhee iinnddiiccaatteedd aattttrr//vvaalluuee ppaaiirr **//
AATTTTRR_OOPP_RREEMMOOVVEE //** rreemmoovvee tthhee iinnddiiccaatteedd aattttrr **//
The am_error field will contain the appropriate error
result code if that sub-operation fails. The result codes
for a given sub-operation are a subset of the result codes
that are possible from the corresponding single-attribute
function call. For example, the result code possible from
an AATTTTRR_OOPP_GGEETT sub-operation are a subset of those that
can be returned from an attr_get function call.
The am_attrname field is a pointer to a NULL terminated
should operate on.
The am_attrvalue, am_length and am_flags fields are used
to store the value of the named attribute, and some con
trol flags for that sub-operation, respectively. Their
use varies depending on the value of the am_opcode field.
ATTR_OP_GET
The am_attrvalue field is a pointer to a empty
buffer that will be overwritten with the value of
the named attribute. The am_length field is ini
tially the total size of the memory buffer that the
am_attrvalue field points to. After the operation,
the am_length field contains the actual size of the
attribute´s value. The am_flags field may be set
to the AATTTTRR_RROOOOTT flag. If the process has appro
priate priviledges, the ROOT namespace will be
searched for the named attribute, otherwise the
USER namespace will be searched.
ATTR_OP_SET
The am_attrvalue and am_length fields contain the
new value for the given attribute name and its
length. The AATTTTRR_RROOOOTT flag may be set in the
am_flags field. If the process has appropriate
priviledges, the ROOT namespace will be searched
for the named attribute, otherwise the USER names
pace will be searched. The AATTTTRR_CCRREEAATTEE and the
AATTTTRR_RREEPPLLAACCEE flags may also be set in the am_flags
field (but not simultaneously). If the AATTTTRR_CCRREEAATTEE
flag is set, the sub-operation will set the
am_error field to EEXIST if the named attribute
already exists. If the AATTTTRR_RREEPPLLAACCEE flag is set,
the sub-operation will set the am_error field to
ENOATTR if the named attribute does not already
exist. If neither of those two flags are set and
the attribute does not exist, then the attribute
will be created with the given value. If neither
of those two flags are set and the attribute
already exists, then the value will be replaced
with the given value.
ATTR_OP_REMOVE
The am_attrvalue and am_length fields are not used
and are ignored. The am_flags field may be set to
the AATTTTRR_RROOOOTT flag. If the process has appropriate
priviledges, the ROOT namespace will be searched
for the named attribute, otherwise the USER names
pace will be searched.
The flags argument to the attr_multi call is used to con
trol following of symbolic links in the path argument.
The default is to follow symbolic links, flags should be
attr_multi will fail if one or more of the following are
true:
[ENOENT] The named file does not exist.
[EPERM] The effective user ID does not match the
owner of the file and the effective user
ID is not super-user.
[ENOTDIR] A component of the path prefix is not a
directory.
[EACCES] Search permission is denied on a compo
nent of the path prefix.
[EINVAL] A bit other than ATTR_DONTFOLLOW was set
in the flag argument.
[EFAULT] Path, or oplist points outside the allo
cated address space of the process.
[ELOOP] A path name lookup involved too many sym
bolic links.
[ENAMETOOLONG] The length of path exceeds {MAXPATHLEN},
or a pathname component is longer than
{MAXNAMELEN}.
attr_multif will fail if:
[EINVAL] A bit was set in the flag argument, or fd
refers to a socket, not a file.
[EFAULT] Oplist points outside the allocated address
space of the process.
[EBADF] Fd does not refer to a valid descriptor.
DIAGNOSTICS
Upon successful completion of the attr_multi call, a value
of 0 is returned. Otherwise, a value of -1 is returned
and errno is set to indicate the error. Note that the
individual operations listed in the oplist array each have
their own error return fields. The errno variable only
records the result of the attr_multi call itself, not the
result of any of the sub-operations.
SEE ALSO
attr(1), attr_get(3), attr_remove(3), and attr_set(3).
Man(1) output converted with
man2html