Merging upstream version 6.8.

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 322 insertions, 0 deletions

diff --git a/man/man2/listxattr.2 b/man/man2/listxattr.2
new file mode 100644
index 0000000..0697b15
--- /dev/null
+++ b/man/man2/listxattr.2
@@ -0,0 +1,322 @@
+.\" Copyright (C) Andreas Gruenbacher, February 2001
+.\" Copyright (C) Silicon Graphics Inc, September 2001
+.\" Copyright (C) 2015 Heinrich Schuchardt <xypron.glpk@gmx.de>
+.\"
+.\" SPDX-License-Identifier: GPL-2.0-or-later
+.\"
+.TH listxattr 2 2024-05-02 "Linux man-pages (unreleased)"
+.SH NAME
+listxattr, llistxattr, flistxattr \- list extended attribute names
+.SH LIBRARY
+Standard C library
+.RI ( libc ", " \-lc )
+.SH SYNOPSIS
+.nf
+.B #include <sys/xattr.h>
+.P
+.BI "ssize_t listxattr(const char *" path ", char *_Nullable " list \
+", size_t " size );
+.BI "ssize_t llistxattr(const char *" path ", char *_Nullable " list \
+", size_t " size );
+.BI "ssize_t flistxattr(int " fd ", char *_Nullable " list ", size_t " size );
+.fi
+.SH DESCRIPTION
+Extended attributes are
+.IR name : value
+pairs associated with inodes (files, directories, symbolic links, 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 xattr (7).
+.P
+.BR listxattr ()
+retrieves the list
+of extended attribute names associated with the given
+.I path
+in the filesystem.
+The retrieved list is placed in
+.IR list ,
+a caller-allocated buffer whose size (in bytes) is specified in the argument
+.IR size .
+The list is the set of (null-terminated) names, one after the other.
+Names of extended attributes to which the calling process does not
+have access may be omitted from the list.
+The length of the attribute name
+.I list
+is returned.
+.P
+.BR 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.
+.P
+.BR flistxattr ()
+is identical to
+.BR listxattr (),
+only the open file referred to by
+.I fd
+(as returned by
+.BR open (2))
+is interrogated in place of
+.IR path .
+.P
+A single extended attribute
+.I name
+is a null-terminated string.
+The name includes a namespace prefix; there may be several, disjoint
+namespaces associated with an individual inode.
+.P
+If
+.I size
+is specified as zero, these calls return the current size of the
+list of extended attribute names (and leave
+.I list
+unchanged).
+This can be used to determine the size of the buffer that
+should be supplied in a subsequent call.
+(But, bear in mind that there is a possibility that the
+set of extended attributes may change between the two calls,
+so that it is still necessary to check the return status
+from the second call.)
+.SS Example
+The
+.I list
+of names is returned as an unordered array of null-terminated character strings
+(attribute names are separated by null bytes (\[aq]\e0\[aq])),
+like this:
+.P
+.in +4n
+.EX
+user.name1\e0system.name1\e0user.name2\e0
+.EE
+.in
+.P
+Filesystems that implement POSIX ACLs using
+extended attributes might return a
+.I list
+like this:
+.P
+.in +4n
+.EX
+system.posix_acl_access\e0system.posix_acl_default\e0
+.EE
+.in
+.SH RETURN VALUE
+On success, a nonnegative number is returned indicating the size of the
+extended attribute name list.
+On failure, \-1 is returned and
+.I errno
+is set to indicate the error.
+.SH ERRORS
+.TP
+.B E2BIG
+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
+Extended attributes are not supported by the filesystem, or are disabled.
+.TP
+.B ERANGE
+The
+.I size
+of the
+.I list
+buffer is too small to hold the result.
+.P
+In addition, the errors documented in
+.BR stat (2)
+can also occur.
+.SH STANDARDS
+Linux.
+.SH HISTORY
+Linux 2.4,
+glibc 2.3.
+.\" .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 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 ().
+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 EXAMPLES
+The following program demonstrates the usage of
+.BR listxattr ()
+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.
+.P
+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
+execution of the program.
+For example,
+the number of bytes required for attribute keys
+might increase between the two calls to
+.BR listxattr ().
+An application could handle this possibility using
+a loop that retries the call
+(perhaps up to a predetermined maximum number of attempts)
+with a larger buffer each time it fails with the error
+.BR ERANGE .
+Calls to
+.BR getxattr (2)
+could be handled similarly.
+.P
+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
+.EX
+$ \fBtouch /tmp/foo\fP
+$ \fBsetfattr \-n user.fred \-v chocolate /tmp/foo\fP
+$ \fBsetfattr \-n user.frieda \-v bar /tmp/foo\fP
+$ \fBsetfattr \-n user.empty /tmp/foo\fP
+$ \fB./listxattr /tmp/foo\fP
+user.fred: chocolate
+user.frieda: bar
+user.empty: <no value>
+.EE
+.in
+.SS Program source (listxattr.c)
+.\" SRC BEGIN (listxattr.c)
+.EX
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+#include <sys/xattr.h>
+\&
+int
+main(int argc, char *argv[])
+{
+    char     *buf, *key, *val;
+    ssize_t  buflen, keylen, vallen;
+\&
+    if (argc != 2) {
+        fprintf(stderr, "Usage: %s path\en", argv[0]);
+        exit(EXIT_FAILURE);
+    }
+\&
+    /*
+     * Determine the length of the buffer needed.
+     */
+    buflen = listxattr(argv[1], NULL, 0);
+    if (buflen == \-1) {
+        perror("listxattr");
+        exit(EXIT_FAILURE);
+    }
+    if (buflen == 0) {
+        printf("%s has no attributes.\en", argv[1]);
+        exit(EXIT_SUCCESS);
+    }
+\&
+    /*
+     * Allocate the buffer.
+     */
+    buf = malloc(buflen);
+    if (buf == NULL) {
+        perror("malloc");
+        exit(EXIT_FAILURE);
+    }
+\&
+    /*
+     * Copy the list of attribute keys to the buffer.
+     */
+    buflen = listxattr(argv[1], buf, buflen);
+    if (buflen == \-1) {
+        perror("listxattr");
+        exit(EXIT_FAILURE);
+    }
+\&
+    /*
+     * Loop over the list of zero terminated strings with the
+     * attribute keys. Use the remaining buffer length to determine
+     * the end of the list.
+     */
+    key = buf;
+    while (buflen > 0) {
+\&
+        /*
+         * Output attribute key.
+         */
+        printf("%s: ", key);
+\&
+        /*
+         * Determine length of the value.
+         */
+        vallen = getxattr(argv[1], key, NULL, 0);
+        if (vallen == \-1)
+            perror("getxattr");
+\&
+        if (vallen > 0) {
+\&
+            /*
+             * Allocate value buffer.
+             * One extra byte is needed to append 0x00.
+             */
+            val = malloc(vallen + 1);
+            if (val == NULL) {
+                perror("malloc");
+                exit(EXIT_FAILURE);
+            }
+\&
+            /*
+             * Copy value to buffer.
+             */
+            vallen = getxattr(argv[1], key, val, vallen);
+            if (vallen == \-1) {
+                perror("getxattr");
+            } else {
+                /*
+                 * Output attribute value.
+                 */
+                val[vallen] = 0;
+                printf("%s", val);
+            }
+\&
+            free(val);
+        } else if (vallen == 0) {
+            printf("<no value>");
+        }
+\&
+        printf("\en");
+\&
+        /*
+         * Forward to next attribute key.
+         */
+        keylen = strlen(key) + 1;
+        buflen \-= keylen;
+        key += keylen;
+    }
+\&
+    free(buf);
+    exit(EXIT_SUCCESS);
+}
+.EE
+.\" SRC END
+.SH SEE ALSO
+.BR getfattr (1),
+.BR setfattr (1),
+.BR getxattr (2),
+.BR open (2),
+.BR removexattr (2),
+.BR setxattr (2),
+.BR stat (2),
+.BR symlink (7),
+.BR xattr (7)