initial version for reworked extended attributes build environment.

6 files changed, 1157 insertions, 0 deletions

diff --git a/man/man3/Makefile b/man/man3/Makefile
new file mode 100644
index 0000000..abf2063
--- /dev/null
+++ b/man/man3/Makefile
@@ -0,0 +1,49 @@
+#
+# Copyright (c) 2000 Silicon Graphics, Inc.  All Rights Reserved.
+# 
+# This program is free software; you can redistribute it and/or modify it
+# under the terms of version 2 of the GNU General Public License as
+# published by the Free Software Foundation.
+# 
+# This program is distributed in the hope that it would be useful, but
+# WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
+# 
+# Further, this software is distributed without any warranty that it is
+# free of the rightful claim of any third person regarding infringement
+# or the like.  Any license provided herein, whether implied or
+# otherwise, applies only to this software file.  Patent licenses, if
+# any, provided herein do not apply to combinations of this program with
+# other software, or any other product whatsoever.
+# 
+# You should have received a copy of the GNU General Public License along
+# with this program; if not, write the Free Software Foundation, Inc., 59
+# Temple Place - Suite 330, Boston MA 02111-1307, USA.
+# 
+# Contact information: Silicon Graphics, Inc., 1600 Amphitheatre Pkwy,
+# Mountain View, CA  94043, or:
+# 
+# http://www.sgi.com 
+# 
+# For further information regarding this notice, see: 
+# 
+# http://oss.sgi.com/projects/GenInfo/SGIGPLNoticeExplan/
+#
+
+TOPDIR = ../..
+include $(TOPDIR)/include/builddefs
+
+MAN_SECTION	= 3
+
+MAN_PAGES	= $(shell echo *.$(MAN_SECTION))
+MAN_DEST	= $(PKG_MAN_DIR)/man$(MAN_SECTION)
+LSRCFILES	= $(MAN_PAGES)
+
+default : $(MAN_PAGES)
+
+include $(BUILDRULES)
+
+install : default
+	$(INSTALL) -m 755 -d $(MAN_DEST)
+	$(INSTALL_MAN)
+install-dev:
diff --git a/man/man3/attr_get.3 b/man/man3/attr_get.3
new file mode 100644
index 0000000..8c9385c
--- /dev/null
+++ b/man/man3/attr_get.3
@@ -0,0 +1,190 @@
+.TH ATTR_GET 3
+.SH NAME
+attr_get, attr_getf \- get the value of a user attribute of a filesystem object
+.SH C SYNOPSIS
+.PP
+.sp
+.nf
+.B #include <sys/attributes.h>
+.sp
+.B "int attr_get (const char \(**path, const char \(**attrname, "
+.B "              char \(**attrvalue, int \(**valuelength, int flags);"
+.PP
+.B "int attr_getf (int fd, const char \(**attrname, "
+.B "               char \(**attrvalue, int \(**valuelength, int flags);"
+.Op
+.SH DESCRIPTION
+The
+.I attr_get
+and
+.I attr_getf
+functions provide a way to retrieve the value of an attribute.
+.P
+.I Path\^
+points to a path name for a filesystem object, and 
+.I fd\^
+refers to the file descriptor associated with a file.
+If the attribute
+.I attrname
+exists, the value associated with it will be copied into the
+.I attrvalue
+buffer.
+The
+.I valuelength
+argument is an input/output argument that on the call to
+.I attr_get
+should contain the maximum size of attribute value the 
+process is willing to accept.
+On return, the
+.I valuelength
+will have been modified to show the actual size of the
+attribute value returned.
+The
+.I flags
+argument can contain the following symbols bitwise OR\'ed together:
+.TP
+.SM
+\%ATTR_ROOT
+Look for
+.I attrname
+in the
+.B root
+address space, not in the
+.B user
+address space.
+(limited to use by super-user only)
+.TP
+.SM
+\%ATTR_DONTFOLLOW
+Do not follow symbolic links when resolving a
+.I path
+on an
+.I attr_get
+function call.
+The default is to follow symbolic links.
+.PP
+.I attr_get
+will fail if one or more of the following are true:
+.TP 17
+.SM
+\%[ENOATTR]
+The attribute name given is not associated with the indicated
+filesystem object.
+.TP
+.SM
+\%[E2BIG]
+The value of the given attribute is too large to fit into the buffer.
+The integer that the
+.I valuelength
+argument points to has been modified to show the actual number
+of bytes that would be required to store the value of that attribute.
+.TP
+.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 was set in the
+.I flag
+argument that is not defined for this system call.
+.TP
+.SM
+\%[EFAULT]
+.I Path,
+.I attrname,
+.I attrvalue,
+or
+.I valuelength
+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_getf\^
+will fail if:
+.TP 15
+.SM
+\%[ENOATTR]
+The attribute name given is not associated with the indicated
+filesystem object.
+.TP
+.SM
+\%[E2BIG]
+The value of the given attribute is too large to fit into the buffer.
+The integer that the
+.I valuelength
+argument points to has been modified to show the actual numnber
+of bytes that would be required to store the value of that attribute.
+.TP
+.SM
+\%[EINVAL]
+A bit was set in the
+.I flag
+argument that is not defined for this system call,
+or
+.I fd\^
+refers to a socket, not a file.
+.TP
+.SM
+\%[EFAULT]
+.I Attrname,
+.I attrvalue,
+or
+.I valuelength
+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_list(3), attr_listf(3)
+.br
+attr_multi(3), attr_multif(3)
+.br
+attr_remove(3), attr_removef(3),
+.br
+attr_set(3), attr_setf(3),
+.SH "DIAGNOSTICS"
+Upon successful completion, a value of 0 is returned.
+Otherwise, a value of \-1 is returned and
+.I errno\^
+is set to indicate the error.
diff --git a/man/man3/attr_list.3 b/man/man3/attr_list.3
new file mode 100644
index 0000000..71408a4
--- /dev/null
+++ b/man/man3/attr_list.3
@@ -0,0 +1,269 @@
+.TH ATTR_LIST 3
+.SH NAME
+attr_list, attr_listf \- list the names of the user attributes of a filesystem object
+.SH C SYNOPSIS
+.PP
+.sp
+.nf
+.B #include <sys/attributes.h>
+.sp
+.B "int attr_list (const char \(**path, char \(**buffer, "
+.B "               const int buffersize, int flags,"
+.B "               attrlist_cursor_t \(**cursor);"
+.PP
+.B "int attr_listf (int fd, char \(**buffer, "
+.B "                const int buffersize, int flags,"
+.B "                attrlist_cursor_t \(**cursor);"
+.Op
+.SH DESCRIPTION
+The
+.I attr_list
+and
+.I attr_listf
+functions provide a way to list the existing attributes of a
+filesystem object.
+.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 buffer
+will be filled with a structure describing at least a portion of the
+attributes associated with the given filesystem object.
+.I Buffer
+will be overwritten with an \f4attrlist_t\fP structure
+containing a list of the attributes associated with
+that filesystem object, up to a maximum of
+.I buffersize
+bytes.
+The 
+.I buffer
+must be sufficiently large to hold the appropriate data structures
+plus at least one maximally sized attribute name,
+but cannot be more than ATTR_MAX_VALUELEN (currently 64KB) bytes in length.
+.PP
+.Op c p a
+The contents of an \f4attrlist_t\fP structure include the following members:
+.P
+.RS 3
+.nf
+.ft 4
+.ta 9n 22n
+__int32_t al_count; /\(** number of entries in attrlist \(**/
+__int32_t al_more; /\(** T/F: more attrs (do syscall again) \(**/
+__int32_t al_offset[1]; /\(** byte offsets of attrs [var-sized] \(**/
+.ft 1
+.fi
+.RE
+.PP
+The
+.I al_count
+field shows the number of attributes represented in this buffer,
+which is also the number of elements in the
+.I al_offset
+array.
+The
+.I al_more
+field will be non-zero if another
+.I attr_list
+call would result in more attributes.
+The
+.I al_offset
+array contains the byte offset within the
+.I buffer
+of the structure describing each of the attributes,
+an \f4attrlist_ent_t\fP structure.
+The \f4ATTR_ENTRY(buffer, index)\fP macro will help with decoding the list.
+It takes a pointer to the
+.I buffer
+and an
+.I index
+into the 
+.I al_offset
+array and returns a pointer to the corresponding
+\f4attrlist_ent_t\fP structure.
+.PP
+The contents of an \f4attrlist_ent_t\fP structure
+include the following members:
+.P
+.RS 3
+.nf
+.ft 4
+.ta 9n 22n
+u_int32_t a_valuelen; /\(** number bytes in value of attr \(**/
+char a_name[]; /\(** attr name (NULL terminated) \(**/
+.ft 1
+.fi
+.Op
+.RE
+.PP
+The
+.I a_valuelen
+field shows the size in bytes of the value
+associated with the attribute whose name is stored in the
+.I a_name
+field.
+The name is a NULL terminated string.
+.PP
+Note that the value of the attribute cannot be obtained through
+this interface, the
+.I attr_get
+call should be used to get the value.
+The
+.I attr_list
+interface tells the calling process how large of a buffer
+it must have in order to get the attribute\'s value.
+.PP
+The
+.I flags
+argument can contain the following symbols bitwise OR\'ed together:
+.TP
+.SM
+\%ATTR_ROOT
+List the attributes that are in the
+.B root
+address space, not in the
+.B user
+address space.
+(limited to use by super-user only)
+.TP
+.SM
+\%ATTR_DONTFOLLOW
+Do not follow symbolic links when resolving a
+.I path
+on an
+.I attr_list
+function call.
+The default is to follow symbolic links.
+.PP
+The
+.I cursor
+argument is a pointer to an opaque data structure that the kernel uses
+to track the calling process\'s position in the attribute list.
+The only valid operations on a
+.I cursor
+are to pass it into an
+.I attr_list
+function call or to zero it out.
+It should be zero\'ed out before the first
+.I attr_list
+call.
+Note that multi-threaded applications may keep more than one
+.I cursor
+in order to serve multiple contexts, ie: the
+.I attr_list
+call is "thread-safe".
+.PP
+.I attr_list
+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 was set in the
+.I flag
+argument that is not defined for this system call,
+or the buffer was too small or too large.
+.TP
+.SM
+\%[EFAULT]
+Either
+.I Path
+or
+.I buffer
+points outside the allocated address space of the process, or
+.I buffer
+or
+.I bufsize
+are not 32bit aligned.
+.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 }.
+.TP
+.SM
+\%[ENOATTR] 
+.I attribute\^
+does not exist for this file.
+.PP
+.I attr_listf\^
+will fail if:
+.TP 15
+.SM
+\%[EINVAL]
+A bit was set in the
+.I flag
+argument that is not defined for this system call, or
+.I fd\^
+refers to a socket, not a file,
+or the buffer was too small or too large.
+.TP
+.SM
+\%[EFAULT]
+Either
+.I Path
+or
+.I buffer
+points outside the allocated address space of the process, or
+.I buffer
+or
+.I bufsize
+are not 32bit aligned.
+.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_multi(3), attr_multif(3)
+.br
+attr_remove(3), attr_removef(3),
+.br
+attr_set(3), attr_set(3)
+.SH "DIAGNOSTICS"
+Upon successful completion, a value of 0 is returned.
+Otherwise, a value of \-1 is returned and
+.I errno\^
+is set to indicate the error.
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.
diff --git a/man/man3/attr_remove.3 b/man/man3/attr_remove.3
new file mode 100644
index 0000000..66340dd
--- /dev/null
+++ b/man/man3/attr_remove.3
@@ -0,0 +1,155 @@
+.TH ATTR_REMOVE 3
+.SH NAME
+attr_remove, attr_removef \- remove a user attribute of a filesystem object
+.SH C SYNOPSIS
+.PP
+.sp
+.nf
+.B #include <sys/attributes.h>
+.sp
+.B "int attr_remove (const char \(**path, const char \(**attrname, int flags);"
+.PP
+.B "int attr_removef (int fd, const char \(**attrname, int flags);"
+.Op
+.SH DESCRIPTION
+The
+.I attr_remove
+and
+.I attr_removef
+functions provide a way to remove previously created attributes
+from filesystem objects.
+.P
+.I Path\^
+points to a path name for a filesystem object, and 
+.I fd\^
+refers to the file descriptor associated with a file.
+If the attribute
+.I attrname
+exists, the attribute name and value will be removed from the
+fileystem object.
+The
+.I flags
+argument can contain the following symbols bitwise OR\'ed together:
+.TP
+.SM
+\%ATTR_ROOT
+Look for
+.I attrname
+in the
+.B root
+address space, not in the
+.B user
+address space.
+(limited to use by super-user only)
+.TP
+.SM
+\%ATTR_DONTFOLLOW
+Do not follow symbolic links when resolving a
+.I path
+on an
+.I attr_remove
+function call.
+The default is to follow symbolic links.
+.PP
+.I attr_remove
+will fail if one or more of the following are true:
+.TP 17
+.SM
+\%[ENOATTR]
+The attribute name given is not associated with the indicated
+filesystem object.
+.TP
+.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 was set in the
+.I flag
+argument that is not defined for this system call.
+.TP
+.SM
+\%[EFAULT]
+.I Path
+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_removef\^
+will fail if:
+.TP 15
+.SM
+\%[ENOATTR]
+The attribute name given is not associated with the indicated
+filesystem object.
+.TP
+.SM
+\%[EINVAL]
+A bit was set in the
+.I flag
+argument that is not defined for this system call,
+or
+.I fd\^
+refers to a socket, not a file.
+.TP
+.SM
+\%[EFAULT]
+.I Attrname
+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_listf(3)
+.br
+attr_multi(3), attr_multif(3)
+.br
+attr_set(3), attr_setf(3),
+.SH "DIAGNOSTICS"
+Upon successful completion, a value of 0 is returned.
+Otherwise, a value of \-1 is returned and
+.I errno\^
+is set to indicate the error.
diff --git a/man/man3/attr_set.3 b/man/man3/attr_set.3
new file mode 100644
index 0000000..c23c523
--- /dev/null
+++ b/man/man3/attr_set.3
@@ -0,0 +1,215 @@
+.TH ATTR_SET 3
+.SH NAME
+attr_set, attr_setf \- set the value of a user attribute of a filesystem object
+.SH C SYNOPSIS
+.PP
+.sp
+.nf
+.B #include <sys/attributes.h>
+.sp
+.B "int attr_set (const char \(**path, const char \(**attrname, "
+.B "              const char \(**attrvalue, const int valuelength,"
+.B "              int flags);"
+.PP
+.B "int attr_setf (int fd, const char \(**attrname, "
+.B "               const char \(**attrvalue, const int valuelength,"
+.B "               int flags);"
+.Op
+.SH DESCRIPTION
+The
+.I attr_set
+and
+.I attr_setf
+functions provide a way to create attributes and set/change their values.
+.P
+.I Path\^
+points to a path name for a filesystem object, and 
+.I fd\^
+refers to the file descriptor associated with a file.
+If the attribute
+.I attrname
+does not exist, an attribute with the given name and value will be created
+and associated with that indicated filesystem object.
+If an attribute with that name already exists on that filesystem object,
+the existing value is replaced with the new value given in this call.
+The new attribute value is copied from the
+.I attrvalue
+buffer for a total of
+.I valuelength
+bytes.
+The
+.I flags
+argument can contain the following symbols bitwise OR\'ed together:
+.TP
+.SM
+\%ATTR_ROOT
+Look for
+.I attrname
+in the
+.B root
+address space, not in the
+.B user
+address space.
+(limited to use by super-user only)
+.TP
+.SM
+\%ATTR_DONTFOLLOW
+Do not follow symbolic links when resolving a
+.I path
+on an
+.I attr_set
+function call.
+The default is to follow symbolic links.
+.TP
+.SM
+\%ATTR_CREATE
+Return an error (EEXIST) if an attribute of the given name
+already exists on the indicated filesystem object,
+otherwise create an attribute with the given name and value.
+This flag is used to implement a pure create operation,
+without this flag
+.I attr_set
+will create the attribute if it does not already exist.
+An error (EINVAL) will be returned if both ATTR_CREATE and ATTR_REPLACE
+are set in the same call.
+.TP
+.SM
+\%ATTR_REPLACE
+Return an error (ENOATTR) if an attribute of the given name
+does not already exist on the indicated filesystem object,
+otherwise replace the existing attribute\'s value with the given value.
+This flag is used to implement a pure replacement operation,
+without this flag
+.I attr_set
+will create the attribute if it does not already exist.
+An error (EINVAL) will be returned if both ATTR_CREATE and ATTR_REPLACE
+are set in the same call.
+.PP
+.I attr_set
+will fail if one or more of the following are true:
+.TP 17
+.SM
+\%[ENOATTR]
+The attribute name given is not associated with the indicated
+filesystem object and the ATTR_REPLACE flag bit was set.
+.TP
+.SM
+\%[E2BIG]
+The value of the given attribute is too large, it exceeds the
+maximum allowable size of an attribute value.
+.TP
+.SM
+\%[EEXIST]
+The attribute name given is already associated with the indicated
+filesystem object and the ATTR_CREATE flag bit was set.
+.TP
+.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 was set in the
+.I flag
+argument that is not defined for this system call,
+or both the ATTR_CREATE and ATTR_REPLACE flags bits were set.
+.TP
+.SM
+\%[EFAULT]
+.I Path,
+.I attrname,
+or
+.I attrvalue
+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_setf\^
+will fail if:
+.TP 15
+.SM
+\%[ENOATTR]
+The attribute name given is not associated with the indicated
+filesystem object and the ATTR_REPLACE flag bit was set.
+.TP
+.SM
+\%[E2BIG]
+The value of the given attribute is too large, it exceeds the
+maximum allowable size of an attribute value.
+.TP
+.SM
+\%[EEXIST]
+The attribute name given is already associated with the indicated
+filesystem object and the ATTR_CREATE flag bit was set.
+.TP
+.SM
+\%[EINVAL]
+A bit was set in the
+.I flag
+argument that is not defined for this system call,
+or both the ATTR_CREATE and ATTR_REPLACE flags bits were set, or
+.I fd\^
+refers to a socket, not a file.
+.TP
+.SM
+\%[EFAULT]
+.I Attrname,
+or
+.I attrvalue
+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_listf(3)
+.br
+attr_multi(3), attr_multif(3)
+.br
+attr_remove(3), attr_removef(3),
+.SH "DIAGNOSTICS"
+Upon successful completion, a value of 0 is returned.
+Otherwise, a value of \-1 is returned and
+.I errno\^
+is set to indicate the error.