diff options
Diffstat (limited to 'man')
| -rw-r--r-- | man/Makefile | 2 | ||||
| -rw-r--r-- | man/man1/attr.1 | 65 | ||||
| -rw-r--r-- | man/man1/getfattr.1 | 129 | ||||
| -rw-r--r-- | man/man1/setfattr.1 | 71 | ||||
| -rw-r--r-- | man/man2/attrctl.2 | 350 | ||||
| -rw-r--r-- | man/man2/getxattr.2 | 123 | ||||
| -rw-r--r-- | man/man2/listxattr.2 | 137 | ||||
| -rw-r--r-- | man/man2/removexattr.2 | 91 | ||||
| -rw-r--r-- | man/man2/setxattr.2 | 126 | ||||
| -rw-r--r-- | man/man3/attr_get.3 | 8 | ||||
| -rw-r--r-- | man/man3/attr_list.3 | 269 | ||||
| -rw-r--r-- | man/man3/attr_multi.3 | 6 | ||||
| -rw-r--r-- | man/man3/attr_remove.3 | 8 | ||||
| -rw-r--r-- | man/man3/attr_set.3 | 8 | ||||
| -rw-r--r-- | man/man5/Makefile | 48 | ||||
| -rw-r--r-- | man/man5/attr.5 | 110 |
16 files changed, 875 insertions, 676 deletions
diff --git a/man/Makefile b/man/Makefile index 057c462..35492a3 100644 --- a/man/Makefile +++ b/man/Makefile @@ -33,7 +33,7 @@ TOPDIR = .. include $(TOPDIR)/include/builddefs -SUBDIRS = man1 man2 man3 +SUBDIRS = man1 man2 man3 man5 default install install-dev : $(SUBDIRS) $(SUBDIRS_MAKERULE) diff --git a/man/man1/attr.1 b/man/man1/attr.1 index bf6cbbe..9c1d905 100644 --- a/man/man1/attr.1 +++ b/man/man1/attr.1 @@ -1,6 +1,6 @@ -.TH attr 1 +.TH ATTR 1 "Extended Attributes" "Dec 2001" "XFS Compatibility API" .SH NAME -attr \- manipulate Extended Attributes on filesystem objects +attr \- extended attributes on XFS filesystem objects .SH SYNOPSIS .nf \f3attr\f1 [ \f3\-LRq\f1 ] \f3\-s attrname\f1 [ \f3\-V attrvalue\f1 ] \c @@ -10,33 +10,40 @@ attr \- manipulate Extended Attributes on filesystem objects .sp .8v \f3attr\f1 [ \f3\-LRq\f1 ] \f3\-r attrname pathname\f1 .sp .8v -\f3attr\f1 [ \f3\-LRq\f1 ] \f3\-l pathname\f1 -.sp .8v .fi .SH OVERVIEW -Extended Attributes implement the ability for a user to attach -name/value pairs to objects within the filesystem. +Extended attributes implement the ability for a user to attach +name:value pairs to objects within the XFS filesystem. .P They could be used to store meta-information about the file. For example "character-set=kanji" could tell a document browser to use the Kanji character set when displaying that document and "thumbnail=..." could provide a reduced resolution overview of a high resolution graphic image. +.PP +This document describes the +.I attr +command, which is mostly compatible with the IRIX command of the same name. +It is thus aimed specifically at users of the XFS filesystem - for +filesystem independent extended attribute manipulation, consult the +.IR getfattr (1) +and +.IR setfattr (1) +documentation. .P -The +In the XFS filesystem, the .I names can be up to 256 bytes in length, terminated by the first 0 byte. The intent is that they be printable ASCII (or other character set) names for the attribute. -.P The .I values -can be up to 256KB of arbitrary binary data. +can be up to 64KB of arbitrary binary data. .P -Attributes can be attached to all types of inodes: +Attributes can be attached to all types of XFS inodes: regular files, directories, symbolic links, device nodes, etc. .P -There are 2 disjoint attribute name spaces associated with every +XFS uses 2 disjoint attribute name spaces associated with every filesystem object. They are the .B root @@ -58,7 +65,7 @@ the value of attributes on any particular file. .SH DESCRIPTION The .I attr -utility allows the manipulation of Extended Attributes associated with +utility allows the manipulation of extended attributes associated with filesystem objects from within shell scripts. .PP There are four main operations that @@ -77,18 +84,6 @@ 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 @@ -148,17 +143,21 @@ The standard file interchange/archive programs .IR tar (1), and .IR cpio (1) -will not archive or restore Extended Attributes, +will not archive or restore extended attributes, while the .IR xfsdump (8) program will. +.SH "CAVEATS" +The list option present in the IRIX version of this command is not supported. +.I getfattr +provides a mechanism to retrieve all of the attribute names. .SH "SEE ALSO" -attr_get(2), attr_getf(2), -attr_list(2), attr_listf(2), -attr_multi(2), attr_multif(2), -attr_remove(2), attr_removef(2), -attr_set(2), attr_setf(2), +getfattr(1), +setfattr(1), +attr_get(3), +attr_set(3), +attr_multi(3), +attr_remove(3), +attr(5), +and xfsdump(8). -.SH BUGS -The extended attributes system call used by this program is -experimental and is currently only supported by the XFS filesystem. diff --git a/man/man1/getfattr.1 b/man/man1/getfattr.1 new file mode 100644 index 0000000..7b3ea66 --- /dev/null +++ b/man/man1/getfattr.1 @@ -0,0 +1,129 @@ +.TH GETFATTR 1 "Extended Attributes" "Dec 2001" "File Utilities" +.SH NAME +getfattr, aget \- get extended attributes of filesystem objects +.SH SYNOPSIS +.nf +\f3getfattr\f1 [\f3\-lvR5LP\f1] \f3\-n name\f1 [\f3\-e en\f1] \c +\f3pathname\f1... +\f3getfattr\f1 [\f3\-lvR5LP\f1] \f3\-d\f1 [\f3\-e en\f1] \c +[\f3\-s\f1 | \f3\-r regex\f1] \f3pathname\f1... +\f3getfattr\f1 [\f3\-Vh\f1] +.fi +.SH DESCRIPTION +For each file, +.B getfattr +displays the file name, +and the set of extended attribute names (and optionally values) which +are associated with that file. +.PP +.B aget +is exactly the same as +.BR getfattr , +and is installed for compatibility purposes. +.PP +The output format of +.B "getfattr \-ds" +is as follows: +.fam C +.RS +.nf + 1: # file: somedir/ + 2: user.name0="value0" + 3: system.name0="value1" + 4: user.name1="value2" + 5: ... +.fi +.RE +.fam T +.PP +Line 1 identifies the file name for which the +following lines are being reported. +The remaining lines (lines 2 to 4 above) show the +.I name +and +.I value +pairs associated with the specified file. +.SS OPTIONS +.TP 4 +.I \-n name +Dump the value of the named extended attribute extended attribute. +.TP +.I \-a +Absolute names \- suppress the stripping of leading '/' from an absolute +.IR pathname . +.TP +.I \-d +Dump the values of all extended attributes associated with +.IR pathname . +.TP +.I \-e en +Encode values after retrieving them. +Valid values of +.I en +are "text", "hex", and "base64". +.TP +.I \-l +Do not follow symlinks - if +.I pathname +is a symbolic link, it is not followed, but is instead itself the +inode being examined. +.TP +.I \-r +.I regex +is a regular expression pattern to apply to the set of extended +attribute names being returned. +It defaults to "^user\\." if no +.I \-r +is specified, which causes +.B getfattr +to operate on only extended attributes from the user namespace. +.TP +.I \-s +Dump out both the "user" and "system" namespaces. +Refer to +.BR attr (5) +for a more detailed discussion on namespaces. +This option is useful for backing up extended attributes in a filesystem +independent manner. +It is implemented using a regular expression ("^user\\.|^system\\.") +and so cannot be used in conjunction with the +.I \-r +option described earlier. +.TP +.I \-v +Dump out the extended attribute value(s) only. +.TP +.I \-R +Recurse into subdirectories, dumping extended attributes for each file +encountered (breadth first). +.TP +.I \-5 +Same as \-R, except done in post-order (depth first). +.TP +.I \-L +Refines the \-R or \-5 option - "logical walk" (do follow symbolic links). +.TP +.I \-P +Refines the \-R or \-5 option - "physical walk" (do not follow symbolic links). +.TP +.I \-V +Print the version of +.B getfattr +and exit. +.TP +.I \-h +Print help explaining the command line options. +.TP +.I \-\- +End of command line options. +All remaining parameters are interpreted as file names, even if they +start with a dash character. +.SH AUTHOR +Andreas Gruenbacher, +.RI < a.gruenbacher@computer.org > +and the SGI XFS development team, +.RI < linux-xfs@oss.sgi.com >. +.P +Please send your bug reports or comments to these addresses. +.SH "SEE ALSO" +setfattr(1), and attr(5). diff --git a/man/man1/setfattr.1 b/man/man1/setfattr.1 new file mode 100644 index 0000000..6b71d2a --- /dev/null +++ b/man/man1/setfattr.1 @@ -0,0 +1,71 @@ +.TH SETFATTR 1 "Extended Attributes" "Dec 2001" "File Utilities" +.SH NAME +setfattr, aset \- set extended attributes of filesystem objects +.SH SYNOPSIS +.nf +\f3setfattr\f1 [\f3\-l\f1] \f3\-n name\f1 [\f3\-v value\f1] \f3pathname\f1... +\f3setfattr\f1 [\f3\-l\f1] \f3\-x name\f1 \f3pathname\f1... +\f3setfattr\f1 [\f3\-l\f1] \f3\-B file\f1 +\f3setfattr\f1 [\f3\-Vh\f1] +.fi +.SH DESCRIPTION +The +.B setfattr +command is used to associate a new +.I value +with an extended attribute +.IR name +for each specified file. +.PP +.B aset +is exactly the same as +.BR setfattr , +and is installed for compatibility purposes. +.SS OPTIONS +.TP 4 +.I \-n name +Set the value of the named extended attribute extended attribute. +.TP +.I \-l +Do not follow symlinks - if +.I pathname +is a symbolic link, it is not followed, but is instead itself the +inode being modified. +.TP +.I \-x +Remove the named extended attribute entirely. +.TP +.I \-v +Specifies the new value for the named extended attribute. +.TP +.I \-B +Restores extended attributes using values from the specified file. +The file must be in the format generated by the +.B getfattr +command (\-sdlR options). +The file name +.I \- +may be used in conjunction with this option, to specify the +standard input stream to be used rather than a named file. +.TP +.I \-V +Print the version of +.B setfattr +and exit. +.TP +.I \-h +Print help explaining the command line options. +.TP +.I \-\- +End of command line options. +All remaining parameters are interpreted as file names, even if they +start with a dash character. +.SH AUTHOR +Andreas Gruenbacher, +.RI < a.gruenbacher@computer.org > +and the SGI XFS development team, +.RI < linux-xfs@oss.sgi.com >. +.P +Please send your bug reports or comments to these addresses. +.SH "SEE ALSO" +getfattr(1), and attr(5). diff --git a/man/man2/attrctl.2 b/man/man2/attrctl.2 deleted file mode 100644 index b49b0c7..0000000 --- a/man/man2/attrctl.2 +++ /dev/null @@ -1,350 +0,0 @@ -.TH ATTRCTL 2 -.SH NAME -attrctl \- manipulate (extended) attributes of system objects -.SH C SYNOPSIS -.PP -.sp -.nf -.B #include <attr/attributes.h> -.sp -.B "int attrctl (attr_obj_t obj, int type, attr_op_t *ops," -.B " int count);" -.Op -.SH OVERVIEW -The -.I attrctl -system call allows a user to attach name/value pairs to system -objects - typically filesystem objects (inodes). -.P -This is a first draft proposal which may well *not* be the final -interface - it has been implemented to address some immediate -issues with the current XFS implementation and is the first attempt -at an interface which could allow both XFS and EXT2 extended attributes -implementations to coexist. -.P -Extended attributes can be used to store meta-information about a -file, for example "character-set=kanji" could tell a document browser -to use the Kanji character set when displaying that document -and "thumbnail=..." could provide a reduced resolution overview of a -high resolution graphic image. -.P -The -.B names -can be up to MAXNAMELEN bytes in length, terminated by the first \e0 byte. -The intent is that they be printable ASCII (or other character set) -names for the attribute. -.P -The -.B values -can be up to ATTR_MAX_VALUELEN (currently 64KB) of arbitrary binary data. -.P -Attributes can be attached to all types of inodes: -regular files, directories, symbolic links, device nodes, etc. -.P -There are 2 disjoint attribute name spaces associated with every -filesystem object. -They are the -.B root -and -.B user -address spaces. -The -.B root -address space is accessible only to the super-user, -and then only by specifying a flag to the operation request. -Non-root users will not see or be able to modify attributes in the -.B root -address space. -The -.B user -address space is protected by the normal file permissions mechanism, -so the owner of the file can decide who is able to see and/or modify -the value of attributes on any particular file. The attribute get/list -operations require read permission, and attribute set/remove require -write permission. -.P -Attributes are currently supported only in the XFS and EXT2 filesystem -types. However, this system call has been designed to be generic -and extensible, such that other filesystems should be able to make -use of it. -.SH DESCRIPTION -The -.I attrctl -system call provides a way to access arbitrary extended attributes. -.P -.I Obj\^ -indicates the system object whose extended attributes are to be -manipulated. -The contents of the \f4attr_obj_t\f1 union are as follows: -.P -typedef union { -.RS 3 -.nf -.ft 4 -.ta 9n 22n -char *path; -int fd; -pid_t pid; -.ft 1 -.fi -.RE -} attr_obj_t; -.PP -.I type\^ -identifies the type of -.I obj\^ -- currently only file descriptors and path names are implemented -(ATTR_TYPE_NAME and ATTR_TYPE_FD), but processes have also been -proposed (ATTR_TYPE_PID). -.P -.I Ops\^ -refers to an array of one or more input/output structures containing -control information related to attribute operations and those -operations' results. -.PP -The -.I count -argument indicates the number of structures in the -.I ops -array. -.PP -.Op c p a -The contents of an \f4attr_op_t\fP structure are as follows: -.P -typedef struct { -.RS 3 -.nf -.ft 4 -.ta 9n 22n -int opcode; /* which operation to perform (see below) */ -int error; /* [out arg] result of this sub-op (an errno) */ -char *name; /* attribute name to work with */ -char *value; /* [in/out arg] attribute value (raw bytes) */ -int length; /* [in/out arg] length of value */ -int flags; /* flags (bit-wise OR of #defines below) */ -void *aux; /* optional command-specific data */ -.ft 1 -.fi -.RE -} attr_op_t; -.PP -The -.I opcode -field defines how the remaining fields are to be interpreted -and can take on one of the following -.B ATTR_OP -values. -.PP -.B ATTR_OP_GET -returns the -.I value -associated with attribute -.IR name . -The size of the user buffer is passed in as -.IR length , -and the size of the attribute value is returned in the same field. -Valid flags are ATTR_ROOT and ATTR_DONTFOLLOW. -.P -.B ATTR_OP_SET -sets (possibly creating a new attribute) the value of the -attribute specified by -.I name -to -.IR value . -The -.I length -parameter specifies the size of the new value, and the valid -.I flags -are ATTR_ROOT, ATTR_DONTFOLLOW, ATTR_CREATE, and ATTR_REPLACE. -.P -.B ATTR_OP_REMOVE -provides a way to remove previously created attributes. -If the attribute -.I name -exists, the attribute name and its associated value will be -removed. -Valid -.I flags -are ATTR_ROOT and ATTR_DONTFOLLOW. -.P -.B ATTR_OP_LIST -is used to list the existing attributes associated with an object. -The -.I name -field is ignored \- -.I value -and -.I size -specify the buffer to be filled with at least a portion of the -attributes associated with the given object. -An -.B attrlist_t -structure will be written into the -.I value -buffer, containing a list of the attributes associated with the -object, up to a maximum of -.I size -bytes. -The -.B attrlist_t -structure contains the following elements: -.P -typedef struct { -.RS 3 -.nf -.ft 4 -.ta 9n 22n -__s32 count; /* number of entries in attribute list */ -__s32 more; /* [in/out arg] more attrs (call again) */ -__s32 offset[1]; /* byte offsets of attrs [var-sized] */ -.ft 1 -.fi -.RE -} attrlist_t; -.PP -The -.I count -field shows the number of attributes represented in this buffer, -which is also the number of elements in the -.I offset -array. -The -.I more -field will be non-zero if another -.B ATTR_OP_LIST -call would retrieve more attributes. -The -.I offset -array contains the byte offset within the -.I value -buffer of the structure describing each of the attributes, an -.B attrlist_ent_t -structure. -The -.B "ATTR_ENTRY(buffer, index)" -macro will help with decoding the list. -It takes a pointer to the -.I value -and an index into the -.I offset -array, and returns a pointer to the corresponding -.I attrlist_ent_t -structure. -.P -typedef struct { -.RS 3 -.nf -.ft 4 -.ta 9n 22n -__u32 valuelen; /* number of bytes in attribute value */ -char name[]; /* attribute name (NULL terminated) */ -.ft 1 -.fi -.RE -} attrlist_ent_t; -.PP -The -.I valuelen -field shows the size in bytes of the value associated -with the attribute whose name is stored in the -.I name -field. -.P -Valid -.I flags -for the -.B ATTR_LIST -command are ATTR_ROOT and ATTR_DONTFOLLOW. -The -.I aux -pointer is used to reference an opaque cursor (type -.BR attrlist_cursor_t ), -which the kernel uses to track the calling process's position -in the attribute list. -The only valid operations on this cursor are to pass it into the -operation or to zero it out (it should be zeroed before the -first -.B attrctl -call. -Note that multi-threaded applications may keep more than one -cursor in order to serve multiple contexts (i.e. the -.B ATTR_LIST -operation is "thread-safe"). -.P -All operations will set -.I error -to an error code if the operation fails, otherwise it will -contain zero indicating success. The set of valid -.I flags -field values (combined using bitwise OR) is as follows: -.TP -.SM -\%ATTR_ROOT -Look for attribute -.I name -in the -.B root -address space, not in the -.B user -address space (limited to use by the 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 -Set -.I error -field (EEXIST) if an attribute of the given name already -exists on the indicated object. -This flag is used to implement a pure create operation, -without this flag -.B ATTR_SET -will create the attribute if it does not already exist. -.TP -.SM -\%ATTR_REPLACE -Set -.I error -field (ENOENT) if an attribute of the given name -does not already exist on the indicated 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 -.B ATTR_SET -will create the attribute if it does not already exist. -.PP -The -.I error -field will be set (EINVAL) if both ATTR_CREATE and ATTR_REPLACE -are requested in the same operation. -.SH DIAGNOSTICS -.I attrctl -will return 0 on success, and an error code on any failure. -Since the -.I attrctl -system call is arbitrarily extensible, and the intention is that it -will always be used through an overlying API, refer to the manual -pages for overlying API calls for specific error code values. -.P -.I attrctl -will always attempt to perform all operations, and a set of -operations are not atomic (failure of one operation does not -necessarily cause prior successful operations to be undone). -.SH "SEE ALSO" -attr(1), -.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). diff --git a/man/man2/getxattr.2 b/man/man2/getxattr.2 new file mode 100644 index 0000000..813873e --- /dev/null +++ b/man/man2/getxattr.2 @@ -0,0 +1,123 @@ +.\" +.\" Extended attributes system calls manual pages +.\" +.\" (C) Andreas Gruenbacher, February 2001 +.\" (C) Silicon Graphics Inc, September 2001 +.\" +.TH GETXATTR 2 "Extended Attributes" "Dec 2001" "System calls" +.SH NAME +getxattr, lgetxattr, fgetxattr \- retrieve an extended attribute value +.SH SYNOPSIS +.fam C +.nf +.B #include <attr/xattr.h> +.sp +.BI "ssize_t getxattr (const char\ *" path ", const char\ *" name ", +.BI "\t\t\t\t void\ *" value ", size_t " size ); +.BI "ssize_t lgetxattr (const char\ *" path ", const char\ *" name ", +.BI "\t\t\t\t void\ *" value ", size_t " size ); +.BI "ssize_t fgetxattr (int " filedes ", const char\ *" name ", +.BI "\t\t\t\t void\ *" value ", size_t " size ); +.fi +.fam T +.SH DESCRIPTION +Extended attributes are +.IR name :\c +.I value +pairs associated with inodes (files, directories, symlinks, etc). +They are extensions to the normal attributes which are associated +with all inodes in the system (i.e. the +.BR stat (2) +data). +A complete overview of extended attributes concepts can be found in +.BR attr (5). +.PP +.B getxattr +retrieves the +.I value +of the extended attribute identified by +.I name +and associated with the given +.I path +in the filesystem. +The length of the attribute +.I value +is returned. +.PP +.B lgetxattr +is identical to +.BR getxattr , +except in the case of a symbolic link, where the link itself is +interrogated, not the file that it refers to. +.PP +.B fgetxattr +is identical to +.BR getxattr , +only the open file pointed to by +.I filedes +(as returned by +.BR open (2)) +is interrogated in place of +.IR path . +.PP +An extended attribute +.I name +is a simple NULL-terminated string. +The name includes a namespace prefix \- there may be several, disjoint +namespaces associated with an individual inode. +The value of an extended attribute is a chunk of arbitrary textual or +binary data of specified length. +.PP +An empty buffer of +.I size +zero can be passed into these calls to return the current size of the +named extended attribute, which can be used to estimate the size of a +buffer which is sufficiently large to hold the value associated with +the extended attribute. +.PP +The interface is designed to allow guessing of initial buffer +sizes, and to enlarge buffers when the return value indicates +that the buffer provided was too small. +.SH RETURN VALUE +On success, a positive number is returned indicating the size of the +extended attribute value. +On failure, \-1 is returned and +.I errno +is set appropriately. +.PP +If the named attribute does not exist, or the process has no access to +this attribute, +.I errno +is set to ENOATTR. +.PP +If the +.I size +of the +.I value +buffer is too small to hold the result, +.I errno +is set to ERANGE. +.PP +If extended attributes are not supported by the filesystem, or are disabled, +.I errno +is set to ENOTSUP. +.PP +The errors documented for the +.BR stat (2) +system call are also applicable here. +.SH AUTHORS +Andreas Gruenbacher, +.RI < a.gruenbacher@computer.org > +and the SGI XFS development team, +.RI < linux-xfs@oss.sgi.com >. +Please send any bug reports or comments to these addresses. +.SH SEE ALSO +.BR getfattr (1), +.BR setfattr (1), +.BR open (2), +.BR stat (2), +.BR setxattr (2), +.BR listxattr (2), +.BR removexattr (2), +and +.BR attr (5). diff --git a/man/man2/listxattr.2 b/man/man2/listxattr.2 new file mode 100644 index 0000000..b1bf578 --- /dev/null +++ b/man/man2/listxattr.2 @@ -0,0 +1,137 @@ +.\" +.\" Extended attributes system calls manual pages +.\" +.\" (C) Andreas Gruenbacher, February 2001 +.\" (C) Silicon Graphics Inc, September 2001 +.\" +.TH LISTXATTR 2 "Extended Attributes" "Dec 2001" "System calls" +.SH NAME +listxattr, llistxattr, flistxattr \- list extended attribute names +.SH SYNOPSIS +.fam C +.nf +.B #include <attr/xattr.h> +.sp +.BI "ssize_t listxattr (const char\ *" path ", +.BI "\t\t\t\t char\ *" list ", size_t " size ); +.BI "ssize_t llistxattr (const char\ *" path ", +.BI "\t\t\t\t char\ *" list ", size_t " size ); +.BI "ssize_t flistxattr (int " filedes ", +.BI "\t\t\t\t char\ *" list ", size_t " size ); +.fi +.fam T +.SH DESCRIPTION +Extended attributes are name:value +pairs associated with inodes (files, directories, symlinks, etc). +They are extensions to the normal attributes which are associated +with all inodes in the system (i.e. the +.BR stat (2) +data). +A complete overview of extended attributes concepts can be found in +.BR attr (5). +.PP +.B listxattr +retrieves the +.I list +of extended attribute names associated with the given +.I path +in the filesystem. +The list is the set of (NULL-terminated) names, one after the other. +The length of the attribute name +.I list +is returned. +.PP +.B llistxattr +is identical to +.BR listxattr , +except in the case of a symbolic link, where the list of names of +extended attributes associated with the link itself is retrieved, +not the file that it refers to. +.PP +.B flistxattr +is identical to +.BR listxattr , +only the open file pointed to by +.I filedes +(as returned by +.BR open (2)) +is interrogated in place of +.IR path . +.PP +A single extended attribute +.I name +is a simple NULL-terminated string. +The name includes a namespace prefix \- there may be several, disjoint +namespaces associated with an individual inode. +.PP +An empty buffer of +.I size +zero can be passed into these calls to return the current size of the +list of extended attribute names, which can be used to estimate the +size of a buffer which is sufficiently large to hold the list of names. +.PP +The interface is designed to allow guessing of initial buffer +sizes, and to enlarge buffers when the return value indicates +that the buffer provided was too small. +.SH EXAMPLES +The +.I list +of names is returned as an unordered array of NULL-terminated character +strings (attribute names are separated by NULL characters), like this: +.fam C +.RS +.nf +user.name1\\0system.name1\\0user.name2\\0 +.fi +.RE +.fam T +.P +Filesystems like ext2, ext3 and XFS which implement POSIX ACLs using +extended attributes, might return a +.I list +like this: +.fam C +.RS +.nf +system.posix_acl_access\\0system.posix_acl_default\\0 +.fi +.RE +.fam T +.SH RETURN VALUE +On success, a positive number is returned indicating the size of the +extended attribute name list. +On failure, \-1 is returned and +.I errno +is set appropriately. +.PP +If the +.I size +of the +.I list +buffer is too small to hold the result, +.I errno +is set to ERANGE. +.PP +If extended attributes are not supported by the filesystem, or are disabled, +.I errno +is set to ENOTSUP. +.PP +The errors documented for the +.BR stat (2) +system call are also applicable here. +.SH AUTHORS +Andreas Gruenbacher, +.RI < a.gruenbacher@computer.org > +and the SGI XFS development team, +.RI < linux-xfs@oss.sgi.com >. +Please send any bug reports or comments to these addresses. +.SH SEE ALSO +.BR getfattr (1), +.BR setfattr (1), +.BR open (2), +.BR stat (2), +.BR getxattr (2), +.BR setxattr (2), +.BR removexattr (2), +and +.BR attr (5). diff --git a/man/man2/removexattr.2 b/man/man2/removexattr.2 new file mode 100644 index 0000000..63affc8 --- /dev/null +++ b/man/man2/removexattr.2 @@ -0,0 +1,91 @@ +.\" +.\" Extended attributes system calls manual pages +.\" +.\" (C) Andreas Gruenbacher, February 2001 +.\" (C) Silicon Graphics Inc, September 2001 +.\" +.TH REMOVEXATTR 2 "Extended Attributes" "Dec 2001" "System calls" +.SH NAME +removexattr, lremovexattr, fremovexattr \- remove an extended attribute +.SH SYNOPSIS +.fam C +.nf +.B #include <attr/xattr.h> +.sp +.BI "int removexattr (const char\ *" path ", const char\ *" name ); +.BI "int lremovexattr (const char\ *" path ", const char\ *" name ); +.BI "int fremovexattr (int " filedes ", const char\ *" name ); +.fi +.fam T +.SH DESCRIPTION +Extended attributes are +.IR name :\c +value pairs associated with inodes (files, directories, symlinks, etc). +They are extensions to the normal attributes which are associated +with all inodes in the system (i.e. the +.BR stat (2) +data). +A complete overview of extended attributes concepts can be found in +.BR attr (5). +.PP +.B removexattr +removes the extended attribute identified by +.I name +and associated with the given +.I path +in the filesystem. +.PP +.B lremovexattr +is identical to +.BR removexattr , +except in the case of a symbolic link, where the extended attribute is +removed from the link itself, not the file that it refers to. +.PP +.B fremovexattr +is identical to +.BR removexattr , +only the extended attribute is removed from the open file pointed to by +.I filedes +(as returned by +.BR open (2)) +in place of +.IR path . +.PP +An extended attribute name is a simple NULL-terminated string. +The +.I name +includes a namespace prefix \- there may be several, disjoint +namespaces associated with an individual inode. +.SH RETURN VALUE +On success, zero is returned. +On failure, \-1 is returned and +.I errno +is set appropriately. +.PP +If the named attribute does not exist, +.I errno +is set to ENOATTR. +.PP +If extended attributes are not supported by the filesystem, or are disabled, +.I errno +is set to ENOTSUP. +.PP +The errors documented for the +.BR stat (2) +system call are also applicable here. +.SH AUTHORS +Andreas Gruenbacher, +.RI < a.gruenbacher@computer.org > +and the SGI XFS development team, +.RI < linux-xfs@oss.sgi.com >. +Please send any bug reports or comments to these addresses. +.SH SEE ALSO +.BR getfattr (1), +.BR setfattr (1), +.BR open (2), +.BR stat (2), +.BR setxattr (2), +.BR getxattr (2), +.BR listxattr (2), +and +.BR attr (5). diff --git a/man/man2/setxattr.2 b/man/man2/setxattr.2 new file mode 100644 index 0000000..5a5f66f --- /dev/null +++ b/man/man2/setxattr.2 @@ -0,0 +1,126 @@ +.\" +.\" Extended attributes system calls manual pages +.\" +.\" (C) Andreas Gruenbacher, February 2001 +.\" (C) Silicon Graphics Inc, September 2001 +.\" +.TH SETXATTR 2 "Extended Attributes" "Dec 2001" "System calls" +.SH NAME +setxattr, lsetxattr, fsetxattr \- set an extended attribute value +.SH SYNOPSIS +.fam C +.nf +.B #include <attr/xattr.h> +.sp +.BI "int setxattr (const char\ *" path ", const char\ *" name ", +.BI "\t\t\t void\ *" value ", size_t " size ", int " flags ); +.BI "int lsetxattr (const char\ *" path ", const char\ *" name ", +.BI "\t\t\t void\ *" value ", size_t " size ", int " flags ); +.BI "int fsetxattr (int " filedes ", const char\ *" name ", +.BI "\t\t\t void\ *" value ", size_t " size ", int " flags ); +.fi +.fam T +.SH DESCRIPTION +Extended attributes are +.IR name :\c +.I value +pairs associated with inodes (files, directories, symlinks, etc). +They are extensions to the normal attributes which are associated +with all inodes in the system (i.e. the +.BR stat (2) +data). +A complete overview of extended attributes concepts can be found in +.BR attr (5). +.PP +.B setxattr +sets the +.I value +of the extended attribute identified by +.I name +and associated with the given +.I path +in the filesystem. +The +.I size +of the +.I value +must be specified. +.PP +.B lsetxattr +is identical to +.BR setxattr , +except in the case of a symbolic link, where the extended attribute is +set on the link itself, not the file that it refers to. +.PP +.B fsetxattr +is identical to +.BR setxattr , +only the extended attribute is set on the open file pointed to by +.I filedes +(as returned by +.BR open (2)) +in place of +.IR path . +.PP +An extended attribute name is a simple NULL-terminated string. +The +.I name +includes a namespace prefix \- there may be several, disjoint +namespaces associated with an individual inode. +The +.I value +of an extended attribute is a chunk of arbitrary textual or +binary data of specified length. +.PP +The +.I flags +parameter can be used to refine the semantics of the operation. +XATTR_CREATE specifies a pure create, which fails if the named +attribute exists already. +XATTR_REPLACE specifies a pure replace operation, which fails if the +named attribute does not already exist. +By default (no flags), the extended attribute will be created if +need be, or will simply replace the value if the attribute exists. +.SH RETURN VALUE +On success, zero is returned. +On failure, \-1 is returned and +.I errno +is set appropriately. +.PP +If XATTR_CREATE is specified, and the attribute exists already, +.I errno +is set to EEXIST. +If XATTR_REPLACE is specified, and the attribute does not exist, +.I errno +is set to ENOATTR. +If XATTR_REMOVE is specified, and the attribute does not exist, +.I errno +is set to ENOATTR. +.PP +If there is insufficient space remaining to store the extended attribute, +.I errno +is set to either ENOSPC, or EDQUOT if quota enforcement was the cause. +.PP +If extended attributes are not supported by the filesystem, or are disabled, +.I errno +is set to ENOTSUP. +.PP +The errors documented for the +.BR stat (2) +system call are also applicable here. +.SH AUTHORS +Andreas Gruenbacher, +.RI < a.gruenbacher@computer.org > +and the SGI XFS development team, +.RI < linux-xfs@oss.sgi.com >. +Please send any bug reports or comments to these addresses. +.SH SEE ALSO +.BR getfattr (1), +.BR setfattr (1), +.BR open (2), +.BR stat (2), +.BR getxattr (2), +.BR listxattr (2), +.BR removexattr (2), +and +.BR attr (5). diff --git a/man/man3/attr_get.3 b/man/man3/attr_get.3 index 2a49624..bff7c86 100644 --- a/man/man3/attr_get.3 +++ b/man/man3/attr_get.3 @@ -1,4 +1,4 @@ -.TH ATTR_GET 3 +.TH ATTR_GET 3 "Extended Attributes" "Dec 2001" "XFS Compatibility API" .SH NAME attr_get, attr_getf \- get the value of a user attribute of a filesystem object .SH C SYNOPSIS @@ -174,11 +174,7 @@ 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) +attr_multi(3), attr_multif(3), .br attr_remove(3), attr_removef(3), .br diff --git a/man/man3/attr_list.3 b/man/man3/attr_list.3 index cffe16d..e69de29 100644 --- a/man/man3/attr_list.3 +++ b/man/man3/attr_list.3 @@ -1,269 +0,0 @@ -.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 <attr/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 index 2daab79..699d218 100644 --- a/man/man3/attr_multi.3 +++ b/man/man3/attr_multi.3 @@ -1,4 +1,4 @@ -.TH ATTR_MULTI 3 +.TH ATTR_MULTI 3 "Extended Attributes" "Dec 2001" "XFS Compatibility API" .SH NAME attr_multi, attr_multif \- manipulate multiple user attributes on a filesystem object at once .SH C SYNOPSIS @@ -253,12 +253,8 @@ 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) diff --git a/man/man3/attr_remove.3 b/man/man3/attr_remove.3 index 1a72d50..4360c5f 100644 --- a/man/man3/attr_remove.3 +++ b/man/man3/attr_remove.3 @@ -1,4 +1,4 @@ -.TH ATTR_REMOVE 3 +.TH ATTR_REMOVE 3 "Extended Attributes" "Dec 2001" "XFS Compatibility API" .SH NAME attr_remove, attr_removef \- remove a user attribute of a filesystem object .SH C SYNOPSIS @@ -139,13 +139,9 @@ 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) +attr_multi(3), attr_multif(3), .br attr_set(3), attr_setf(3), .SH "DIAGNOSTICS" diff --git a/man/man3/attr_set.3 b/man/man3/attr_set.3 index 01a04ad..79b1e83 100644 --- a/man/man3/attr_set.3 +++ b/man/man3/attr_set.3 @@ -1,4 +1,4 @@ -.TH ATTR_SET 3 +.TH ATTR_SET 3 "Extended Attributes" "Dec 2001" "XFS Compatibility API" .SH NAME attr_set, attr_setf \- set the value of a user attribute of a filesystem object .SH C SYNOPSIS @@ -199,13 +199,9 @@ 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) +attr_multi(3), attr_multif(3), .br attr_remove(3), attr_removef(3), .SH "DIAGNOSTICS" diff --git a/man/man5/Makefile b/man/man5/Makefile new file mode 100644 index 0000000..b81e765 --- /dev/null +++ b/man/man5/Makefile @@ -0,0 +1,48 @@ +# +# 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 = 5 + +MAN_PAGES = $(shell echo *.$(MAN_SECTION)) +MAN_DEST = $(PKG_MAN_DIR)/man$(MAN_SECTION) +LSRCFILES = $(MAN_PAGES) + +default install : $(MAN_PAGES) + +include $(BUILDRULES) + +install-dev : default + $(INSTALL) -m 755 -d $(MAN_DEST) + $(INSTALL_MAN) diff --git a/man/man5/attr.5 b/man/man5/attr.5 new file mode 100644 index 0000000..4d82071 --- /dev/null +++ b/man/man5/attr.5 @@ -0,0 +1,110 @@ +.\" +.\" Extended attributes manual page +.\" +.\" (C) Andreas Gruenbacher, 2000 +.\" (C) Silicon Graphics Inc, 2001 +.\" +.TH ATTR 5 +.SH NAME +Extended attributes +.SH DESCRIPTION +Extended attributes are name:value pairs associated permanently with +files and directories, similar to the environment strings associated +with a process. +An attribute may be defined or undefined. +If it is defined, its value may be empty or non-empty. +.PP +Extended attributes are extensions to the normal attributes which are +associated with all inodes in the system (i.e. the +.BR stat (2) +data). +They are often used to provide additional functionality +to a filesystem \- for example, additional security features such as +Access Control Lists (ACLs) may be implemented using extended attributes. +.PP +Users with search access to a file or directory may retrieve a list of +attribute names defined for that file or directory. +.PP +Extended attributes are accessed as atomic objects. +Reading retrieves the whole value of an attribute and stores it in a buffer. +Writing replaces any previous value with the new value. +.PP +Currently, support for extended attributes is implemented on Linux by +the ext2, ext3 and XFS filesystem patches, which can be downloaded from +.B http://acl.bestbits.at/ +and +.B http://oss.sgi.com/projects/xfs/ +respectively. +.SH EXTENDED ATTRIBUTE NAMESPACES +Attribute names are zero-terminated strings and typically have a short +(filesystem dependent) length. +The attribute name is always specified in the full +.IR namespace.attribute +form, eg. +.I user.mime_type +or +.IR system.posix_acl_access . +.PP +The namespace mechanism is used to define different classes of extended +attributes. +These different classes exist for several reasons, e.g. the permissions +and capabilities required for manipulating extended attributes of one +namespace may differ to another. +They have also been used to distinguish filesystem-specific attribute +names from canonical, filesystem-independent attribute names. +.PP +The extended attribute namespace is always specified as the first +component of the name. +This greatly simplifies certain operations, and provides a consistent, +explicit interface for all operations. +.PP +Extended +.I user +attributes may be assigned to files and directories for storing arbitrary +additional information such as the mime type, character set or encoding +of a file. +User attributes are subject to the same permissions as the contents of a file. +The file owner can decide who is allowed to read and/or set these attributes. +.PP +Extended +.I system +attributes are used by the kernel to store system objects such as +Access Control Lists and Capabilities. +Read and write access permissions to system attributes +depend on the policy implemented for each system attribute implemented +in the kernel. +.PP +Additional types of extended attributes with different access permissions, +such as attributes that are accessible only to processes trusted by the +kernel, may be added in the future. +.SH FILESYSTEM DIFFERENCES +The kernel and the filesystem may place limits on the maximum number +and size of extended attributes that can be associated with a file. +.PP +In the current ext2 and ext3 filesystem implementations, all extended +attributes must fit on a single filesystem block (1024, 2048 or 4096 bytes, +depending on the block size specified when the filesystem +was created). This limit may be removed in a future version. +Device special files cannot be associated with extended user attributes +(but they may be associated with extended system attributes). Permissions +of device special files define access to the devices rather than to the +device special files. +.PP +In the XFS filesystem implementation, there is no practical limit on the +number of extended attributes associated with a file, and the algorithms +used to store extended attribute information on disk are scalable (stored +either inline in the inode, as an extent, or in a B+ tree). +XFS allows extended attributes to be associated with device inodes. +.SH ADDITIONAL NOTES +Since the filesystems on which extended attributes are stored might also +be used on architectures with a different byte order and machine word +size, care should be taken to store attribute values in an architecture +independent format. +.SH AUTHORS +Andreas Gruenbacher, +.RI < a.gruenbacher@computer.org > +and the SGI XFS development team, +.RI < linux-xfs@oss.sgi.com >. +.SH SEE ALSO +getfattr(1), +setfattr(1). |