fuse.4: ffix

[thirdparty/man-pages.git] / man2 / listxattr.2

diff --git a/man2/listxattr.2 b/man2/listxattr.2
index 7519bff5d0d494a9bba3914ed6cbdabf04306090..a38279909a85e686c23e249eafec829b33420d42 100644 (file)
--- a/man2/listxattr.2
+++ b/man2/listxattr.2
@@ -23,7 +23,7 @@
 .\" <http://www.gnu.org/licenses/>.
 .\" %%%LICENSE_END
 .\"
-.TH LISTXATTR 2 2015-05-07 "Linux" "Linux Programmer's Manual"
+.TH LISTXATTR 2 2017-09-15 "Linux" "Linux Programmer's Manual"
 .SH NAME
 listxattr, llistxattr, flistxattr \- list extended attribute names
 .SH SYNOPSIS
@@ -31,7 +31,7 @@ listxattr, llistxattr, flistxattr \- list extended attribute names
 .nf
 .B #include <sys/types.h>
 .B #include <sys/xattr.h>
-.sp
+.PP
 .BI "ssize_t listxattr(const char\ *" path ", char\ *" list \
 ", size_t " size );
 .BI "ssize_t llistxattr(const char\ *" path ", char\ *" list \
@@ -88,7 +88,7 @@ A single extended attribute
 is a null-terminated string.
 The name includes a namespace prefix; there may be several, disjoint
 namespaces associated with an individual inode.
-
+.PP
 If
 .I size
 is specified as zero, these calls return the current size of the
@@ -106,27 +106,23 @@ The
 .I list
 of names is returned as an unordered array of null-terminated character
 strings (attribute names are separated by null bytes (\(aq\\0\(aq)), like this:
-.fam C
-.RS
-.nf
-
+.PP
+.in +4n
+.EX
 user.name1\\0system.name1\\0user.name2\\0
-.fi
-.RE
-.fam T
-.P
+.EE
+.in
+.PP
 Filesystems that implement POSIX ACLs using
 extended attributes might return a
 .I list
 like this:
-.fam C
-.RS
-.nf
-
+.PP
+.in +4n
+.EX
 system.posix_acl_access\\0system.posix_acl_default\\0
-.fi
-.RE
-.fam T
+.EE
+.in
 .SH RETURN VALUE
 On success, a nonnegative number is returned indicating the size of the
 extended attribute name list.
@@ -136,8 +132,10 @@ is set appropriately.
 .SH ERRORS
 .TP
 .B E2BIG
-The size of the list of attribute names for this file exceeds
-the system-imposed limit.
+The size of the list of extended attribute names is larger than the maximum
+size allowed; the list cannot be retrieved.
+This can happen on filesystems that support an unlimited number of
+extended attributes per file such as XFS, for example.
 See BUGS.
 .TP
 .B ENOTSUP
@@ -164,6 +162,15 @@ These system calls are Linux-specific.
 .\" and the SGI XFS development team,
 .\" .RI < linux-xfs@oss.sgi.com >.
 .\" Please send any bug reports or comments to these addresses.
+.SH BUGS
+.\" The xattr(7) page refers to this text:
+As noted in
+.BR xattr (7),
+the VFS imposes a limit of 64\ kB on the size of the extended
+attribute name list returned by
+.BR listxattr (7).
+If the total size of attribute names attached to a file exceeds this limit,
+it is no longer possible to retrieve the list of attribute names.
 .SH EXAMPLE
 The following program demonstrates the usage of
 .BR listxattr ()
@@ -171,7 +178,7 @@ and
 .BR getxattr (2).
 For the file whose pathname is provided as a command-line argument,
 it lists all extended file attributes and their values.
-
+.PP
 To keep the code simple, the program assumes that attribute keys and
 values are constant during the execution of the program.
 A production program should expect and handle changes during
@@ -188,13 +195,13 @@ with a larger buffer each time it fails with the error
 Calls to
 .BR getxattr (2)
 could be handled similarly.
-
+.PP
 The following output was recorded by first creating a file, setting
 some extended file attributes,
 and then listing the attributes with the example program.
 .SS Example output
 .in +4n
-.nf
+.EX
 $ \fBtouch /tmp/foo\fP
 $ \fBsetfattr -n user.fred -v chocolate /tmp/foo\fP
 $ \fBsetfattr -n user.frieda -v bar /tmp/foo\fP
@@ -203,10 +210,10 @@ $ \fB./listxattr /tmp/foo\fP
 user.fred: chocolate
 user.frieda: bar
 user.empty: <no value>
-.fi
+.EE
 .in
 .SS Program source (listxattr.c)
-.nf
+.EX
 #include <malloc.h>
 #include <stdio.h>
 #include <stdlib.h>
@@ -319,16 +326,7 @@ main(int argc, char *argv[])
     free(buf);
     exit(EXIT_SUCCESS);
 }
-.fi
-.SH BUGS
-.\" The xattr(7) page refers to this text:
-As noted in
-.BR xattr (7),
-the VFS imposes a limit of 64 kB on the size of the extended
-attribute name list returned by
-.BR listxattr (7).
-If the total size of attribute names attached to a file exceeds this limit,
-it is no longer possible to retrieve the list of attribute names.
+.EE
 .SH SEE ALSO
 .BR getfattr (1),
 .BR setfattr (1),