1 files changed, 279 insertions, 0 deletions
diff --git a/man/man3/attr_multi.3 b/man/man3/attr_multi.3
new file mode 100644
index 0000000..fd9107e
--- /dev/null
+++ b/man/man3/attr_multi.3
@@ -0,0 +1,279 @@
+.TH ATTR_MULTI 3
+.SH NAME
+attr_multi, attr_multif \- manipulate multiple user attributes on a filesystem object at once
+.SH C SYNOPSIS
+.PP
+.sp
+.nf
+.B #include <sys/attributes.h>
+.sp
+.B "int attr_multi (const char \(**path, attr_multiop_t \(**oplist, "
+.B "                int count, int flags);"
+.PP
+.B "int attr_multif (int fd, attr_multiop_t \(**oplist, "
+.B "                 int count, int flags);"
+.Op
+.SH DESCRIPTION
+The
+.I attr_multi
+and
+.I attr_multif
+functions provide a way to operate on multiple attributes of a
+filesystem object at once.
+.P
+.I Path
+points to a path name for a filesystem object, and 
+.I fd
+refers to the file descriptor associated with a file.
+The 
+.I oplist
+is an array of \f4attr_multiop_t\fP structures.
+Each element in that array describes a single attribute operation
+and provides all the information required to carry out that operation
+and to check for success or failure of that operation.
+.I Count
+tells how many elements are in the
+.I oplist
+array.
+.PP
+.Op c p a
+The contents of an \f4attr_multiop_t\fP structure include
+the following members:
+.P
+.RS 3
+.nf
+.ft 4
+.ta 9n 22n
+int am_opcode; /* which operation to perform (see below) */
+int am_error; /* [out arg] result of this sub-op (an errno) */
+char *am_attrname; /* attribute name to work with */
+char *am_attrvalue; /* [in/out arg] attribute value (raw bytes) */
+int am_length; /* [in/out arg] length of value */
+int am_flags; /* flags (bit-wise OR of #defines below) */
+.ft 1
+.fi
+.RE
+.PP
+The
+.I am_opcode
+field defines how the remaining fields are to be interpreted
+and can take on one of the following values:
+.P
+.RS 3
+.nf
+.ft 4
+.ta 9n 22n
+ATTR_OP_GET /* return the indicated attr's value */
+ATTR_OP_SET /* set/create the indicated attr/value pair */
+ATTR_OP_REMOVE /* remove the indicated attr */
+.ft 1
+.fi
+.RE
+.PP
+The
+.I 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 \f4ATTR_OP_GET\fP
+sub-operation are a subset of those that can be returned from an
+.I attr_get
+function call.
+.PP
+The
+.I am_attrname
+field is a pointer to a NULL terminated string giving the attribute name
+that the sub-operation should operate on.
+.PP
+The
+.I am_attrvalue,
+.I am_length
+and
+.I am_flags
+fields are used to store the value of the named attribute,
+and some control flags for that sub-operation, respectively.
+Their use varies depending on the value of the
+.I am_opcode
+field.
+.TP
+.SM
+.B \%ATTR_OP_GET
+The
+.I am_attrvalue
+field is a pointer to a empty buffer that will be overwritten
+with the value of the named attribute.
+The
+.I am_length
+field is initially the total size of the memory buffer that the
+.I am_attrvalue
+field points to.
+After the operation, the
+.I am_length
+field contains the actual size of the attribute\'s value.
+The
+.I am_flags
+field may be set to the \f4ATTR_ROOT\fP flag.
+If the process has appropriate priviledges,
+the ROOT namespace will be searched for the named attribute,
+otherwise the USER namespace will be searched.
+.TP
+.SM
+.B \%ATTR_OP_SET
+The
+.I am_attrvalue
+and
+.I am_length
+fields contain the new value for the given attribute name and its length.
+The \f4ATTR_ROOT\fP flag may be set in the
+.I am_flags
+field.
+If the process has appropriate priviledges,
+the ROOT namespace will be searched for the named attribute,
+otherwise the USER namespace will be searched.
+The \f4ATTR_CREATE\fP and the \f4ATTR_REPLACE\fP flags
+may also be set in the 
+.I am_flags
+field (but not simultaneously).
+If the \f4ATTR_CREATE\fP flag is set,
+the sub-operation will set the
+.I am_error
+field to EEXIST if the named attribute already exists.
+If the \f4ATTR_REPLACE\fP flag is set,
+the sub-operation will set the
+.I 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.
+.TP
+.SM
+.B \%ATTR_OP_REMOVE
+The
+.I am_attrvalue
+and
+.I am_length
+fields are not used and are ignored.
+The
+.I am_flags
+field may be set to the \f4ATTR_ROOT\fP flag.
+If the process has appropriate priviledges,
+the ROOT namespace will be searched for the named attribute,
+otherwise the USER namespace will be searched.
+.PP
+The
+.I flags
+argument to the
+.I attr_multi
+call is used to control following of symbolic links in the
+.I path
+argument.
+The default is to follow symbolic links,
+.I flags
+should be set to ATTR_DONTFOLLOW to not follow symbolic links.
+.PP
+.I attr_multi
+will fail if one or more of the following are true:
+.TP 17
+.SM
+\%[ENOENT]
+The named file does not exist.
+.TP
+.SM
+\%[EPERM]
+The effective user
+.SM ID
+does not match the owner of the file
+and the effective user
+.SM ID
+is not super-user.
+.TP
+.SM
+\%[ENOTDIR]
+A component of the
+path prefix
+is not a directory.
+.TP
+.SM
+\%[EACCES]
+Search permission is denied on a
+component of the
+path prefix.
+.TP
+.SM
+\%[EINVAL]
+A bit other than ATTR_DONTFOLLOW was set in the
+.I flag
+argument.
+.TP
+.SM
+\%[EFAULT]
+.I Path,
+or
+.I oplist
+points outside the allocated address space of the process.
+.TP
+.SM
+\%[ELOOP]
+A path name lookup involved too many symbolic links.
+.TP
+.SM
+\%[ENAMETOOLONG]
+The length of
+.I path
+exceeds
+.SM
+.RI { MAXPATHLEN },
+or a pathname component is longer than
+.SM
+.RI { MAXNAMELEN }.
+.PP
+.I attr_multif
+will fail if:
+.TP 15
+.SM
+\%[EINVAL]
+A bit was set in the
+.I flag
+argument, or
+.I fd\^
+refers to a socket, not a file.
+.TP
+.SM
+\%[EFAULT]
+.I Oplist
+points outside the allocated address space of the process.
+.TP
+.SM
+\%[EBADF]
+.I Fd\^
+does not refer to a valid descriptor.
+.SH "SEE ALSO"
+attr(1),
+.br
+attrctl(2),
+.br
+attr_get(3), attr_getf(3),
+.br
+attr_list(3), attr_list(3)
+.br
+attr_remove(3), attr_removef(3),
+.br
+attr_set(3), attr_set(3)
+.SH "DIAGNOSTICS"
+Upon successful completion of the
+.I attr_multi
+call, a value of 0 is returned.
+Otherwise, a value of \-1 is returned and
+.I errno
+is set to indicate the error.
+Note that the individual operations listed in the
+.I oplist
+array each have their own error return fields.
+The 
+.I errno
+variable only records the result of the
+.I attr_multi
+call itself, not the result of any of the sub-operations.