diff options
Diffstat (limited to 'man')
-rw-r--r-- | man/man1/attr.1 | 26 | ||||
-rw-r--r-- | man/man3/attr_get.3 | 6 | ||||
-rw-r--r-- | man/man3/attr_list.3 | 263 | ||||
-rw-r--r-- | man/man3/attr_multi.3 | 9 | ||||
-rw-r--r-- | man/man3/attr_remove.3 | 3 | ||||
-rw-r--r-- | man/man3/attr_set.3 | 3 |
6 files changed, 299 insertions, 11 deletions
diff --git a/man/man1/attr.1 b/man/man1/attr.1 index 9c1d905..ab555f1 100644 --- a/man/man1/attr.1 +++ b/man/man1/attr.1 @@ -3,12 +3,14 @@ attr \- extended attributes on XFS filesystem objects .SH SYNOPSIS .nf -\f3attr\f1 [ \f3\-LRq\f1 ] \f3\-s attrname\f1 [ \f3\-V attrvalue\f1 ] \c +\f3attr\f1 [ \f3\-LRSq\f1 ] \f3\-s attrname\f1 [ \f3\-V attrvalue\f1 ] \c \f3pathname\f1 .sp .8v -\f3attr\f1 [ \f3\-LRq\f1 ] \f3\-g attrname pathname\f1 +\f3attr\f1 [ \f3\-LRSq\f1 ] \f3\-g attrname pathname\f1 .sp .8v -\f3attr\f1 [ \f3\-LRq\f1 ] \f3\-r attrname pathname\f1 +\f3attr\f1 [ \f3\-LRSq\f1 ] \f3\-r attrname pathname\f1 +.sp .8v +\f3attr\f1 [ \f3\-LRSq\f1 ] \f3\-l pathname\f1 .sp .8v .fi .SH OVERVIEW @@ -84,6 +86,18 @@ With the flag, \f4stdout\fP will be exactly and only the value of the attribute, suitable for storage directly into a file or processing via a piped command. .TP +.B LIST +The +.B \-l +option tells +.I attr +to list the names of all the attributes that are associated with the object, +and the number of bytes in the value of each of those attributes. +With the +.B \-q +flag, \f4stdout\fP will be a simple list of only the attribute names, +one per line, suitable for input into a script. +.TP .B REMOVE The .B \-r attrname @@ -131,6 +145,12 @@ attribute namespace rather that the .I USER attribute namespace. .PP +The +.B \-S +option is similar, except it specifies use of the +.I security +attribute namespace. +.PP When the .B \-q option is given diff --git a/man/man3/attr_get.3 b/man/man3/attr_get.3 index 2f97f8d..c0ab084 100644 --- a/man/man3/attr_get.3 +++ b/man/man3/attr_get.3 @@ -2,6 +2,7 @@ .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 <attr/attributes.h> @@ -20,7 +21,7 @@ and functions provide a way to retrieve the value of an attribute. .P .I Path\^ -points to a path name for a filesystem object, and +points to a path name for a filesystem object, and .I fd\^ refers to the file descriptor associated with a file. If the attribute @@ -32,7 +33,7 @@ The .I valuelength argument is an input/output argument that on the call to .B attr_get -should contain the maximum size of attribute value the +should contain the maximum size of attribute value the process is willing to accept. On return, the .I valuelength @@ -171,6 +172,7 @@ On success, zero is returned. On error, \-1 is returned, and is set appropriately. .SH "SEE ALSO" .BR attr (1), +.BR attr_list (3), .BR attr_multi (3), .BR attr_remove (3), and diff --git a/man/man3/attr_list.3 b/man/man3/attr_list.3 index e69de29..79013be 100644 --- a/man/man3/attr_list.3 +++ b/man/man3/attr_list.3 @@ -0,0 +1,263 @@ +.TH ATTR_LIST 3 "Extended Attributes" "Dec 2005" "XFS Compatibility API" +.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 +.B attr_list +and +.B 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 +.B 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 +.B attr_get +call should be used to get the value. +The +.B 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 +.B 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 +.B attr_list +function call or to zero it out. +It should be zero\'ed out before the first +.B attr_list +call. +Note that multi-threaded applications may keep more than one +.I cursor +in order to serve multiple contexts, ie: the +.B attr_list +call is "thread-safe". +.PP +.B 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 +.B 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 "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. +.SH "SEE ALSO" +.BR attr (1), +.BR attr_multi (3), +.BR attr_remove (3), +and +.BR attr_set (3). diff --git a/man/man3/attr_multi.3 b/man/man3/attr_multi.3 index aee9072..ed30869 100644 --- a/man/man3/attr_multi.3 +++ b/man/man3/attr_multi.3 @@ -22,10 +22,10 @@ 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 +points to a path name for a filesystem object, and .I fd refers to the file descriptor associated with a file. -The +The .I oplist is an array of \f4attr_multiop_t\fP structures. Each element in that array describes a single attribute operation @@ -133,7 +133,7 @@ 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 +may also be set in the .I am_flags field (but not simultaneously). If the \f4ATTR_CREATE\fP flag is set, @@ -257,7 +257,7 @@ is set appropriately. Note that the individual operations listed in the .I oplist array each have their own error return fields. -The +The .I errno variable only records the result of the .I attr_multi @@ -265,6 +265,7 @@ call itself, not the result of any of the sub-operations. .SH "SEE ALSO" .BR attr (1), .BR attr_get (3), +.BR attr_list (3), .BR attr_remove (3), and .BR attr_set (3). diff --git a/man/man3/attr_remove.3 b/man/man3/attr_remove.3 index 9068e11..90fbb72 100644 --- a/man/man3/attr_remove.3 +++ b/man/man3/attr_remove.3 @@ -20,7 +20,7 @@ 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 +points to a path name for a filesystem object, and .I fd\^ refers to the file descriptor associated with a file. If the attribute @@ -143,6 +143,7 @@ is set appropriately. .SH "SEE ALSO" .BR attr (1), .BR attr_get (3), +.BR attr_list (3), .BR attr_multi (3), and .BR attr_set (3). diff --git a/man/man3/attr_set.3 b/man/man3/attr_set.3 index 63c6b7e..9637700 100644 --- a/man/man3/attr_set.3 +++ b/man/man3/attr_set.3 @@ -23,7 +23,7 @@ and 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 +points to a path name for a filesystem object, and .I fd\^ refers to the file descriptor associated with a file. If the attribute @@ -203,6 +203,7 @@ is set appropriately. .SH "SEE ALSO" .BR attr (1), .BR attr_get (3), +.BR attr_list (3), .BR attr_multi (3), and .BR attr_remove (3). |