diff options
Diffstat (limited to 'man2/listxattr.2')
| -rw-r--r-- | man2/listxattr.2 | 322 |
1 files changed, 0 insertions, 322 deletions
diff --git a/man2/listxattr.2 b/man2/listxattr.2 deleted file mode 100644 index 30a4d8230..000000000 --- a/man2/listxattr.2 +++ /dev/null @@ -1,322 +0,0 @@ -.\" 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 (date) "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> -.PP -.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). -.PP -.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. -.PP -.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. -.PP -.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 . -.PP -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. -.PP -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: -.PP -.in +4n -.EX -user.name1\e0system.name1\e0user.name2\e0 -.EE -.in -.PP -Filesystems that implement POSIX ACLs using -extended attributes might return a -.I list -like this: -.PP -.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. -.PP -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. -.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 -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. -.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 -.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) |