+.\" Copyright (C) Andreas Gruenbacher, February 2001
+.\" Copyright (C) Silicon Graphics Inc, September 2001
.\"
-.\" Extended attributes system calls manual pages
-.\"
-.\" (C) Andreas Gruenbacher, February 2001
-.\" (C) Silicon Graphics Inc, September 2001
-.\"
+.\" %%%LICENSE_START(GPLv2+_DOC_FULL)
.\" This is free documentation; you can redistribute it and/or
.\" modify it under the terms of the GNU General Public License as
.\" published by the Free Software Foundation; either version 2 of
.\" GNU General Public License for more details.
.\"
.\" You should have received a copy of the GNU General Public
-.\" License along with this manual; if not, write to the Free
-.\" Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111,
-.\" USA.
+.\" License along with this manual; if not, see
+.\" <http://www.gnu.org/licenses/>.
+.\" %%%LICENSE_END
.\"
-.TH GETXATTR 2 "Extended Attributes" "Dec 2001" "Linux Programmer's Manual"
+.TH GETXATTR 2 2020-06-09 "Linux" "Linux Programmer's Manual"
.SH NAME
getxattr, lgetxattr, fgetxattr \- retrieve an extended attribute value
.SH SYNOPSIS
.fam C
.nf
.B #include <sys/types.h>
-.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 );
+.B #include <sys/xattr.h>
+.PP
+.BI "ssize_t getxattr(const char\ *" path ", const char\ *" name ,
+.BI " void\ *" value ", size_t " size );
+.BI "ssize_t lgetxattr(const char\ *" path ", const char\ *" name ,
+.BI " void\ *" value ", size_t " size );
+.BI "ssize_t fgetxattr(int " fd ", const char\ *" name ,
+.BI " 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).
+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
+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).
+.BR xattr (7).
.PP
.BR getxattr ()
-retrieves the
-.I value
-of the extended attribute identified by
+retrieves the 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.
+The attribute value is placed in the buffer pointed to by
+.IR value ;
+.I size
+specifies the size of that buffer.
+The return value of the call is the number of bytes placed in
+.IR value .
.PP
.BR lgetxattr ()
-is identical to
+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.
.BR fgetxattr ()
is identical to
.BR getxattr (),
-only the open file pointed to by
-.I filedes
+only the open file referred to by
+.I fd
(as returned by
.BR open (2))
is interrogated in place of
.PP
An extended attribute
.I name
-is a simple NULL-terminated string.
+is a 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.
+binary data that was assigned using
+.BR setxattr (2).
.PP
-An empty buffer of
+If
.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.
+is specified as zero, these calls return the current size of the
+named extended attribute (and leave
+.I value
+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
+attribute value may change between the two calls,
+so that it is still necessary to check the return status
+from the second call.)
.SH RETURN VALUE
-On success, a positive number is returned indicating the size of the
-extended attribute value.
+On success, these calls return a nonnegative value which is
+the size (in bytes) 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
+.SH ERRORS
+.TP
+.B E2BIG
+The size of the attribute value is larger than the maximum size allowed; the
+attribute cannot be retrieved.
+This can happen on filesystems that support
+very large attribute values such as NFSv4, for example.
+.TP
+.B ENODATA
+The named attribute does not exist, or the process has no access to
+this attribute.
+.\" .RB ( ENOATTR
+.\" is defined to be a synonym for
+.\" .BR ENODATA
+.\" in
+.\" .IR <attr/attributes.h> .)
+.TP
+.B ENOTSUP
+Extended attributes are not supported by the filesystem, or are disabled.
+.TP
+.B ERANGE
+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.
+buffer is too small to hold the result.
.PP
-The errors documented for the
+In addition, the errors documented in
.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.
+can also occur.
+.SH VERSIONS
+These system calls have been available on Linux since kernel 2.4;
+glibc support is provided since version 2.3.
+.SH CONFORMING TO
+These system calls are Linux-specific.
+.\" .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 EXAMPLES
+See
+.BR listxattr (2).
.SH SEE ALSO
.BR getfattr (1),
.BR setfattr (1),
.BR removexattr (2),
.BR setxattr (2),
.BR stat (2),
-.BR attr (5)
+.BR symlink (7),
+.BR xattr (7)
projects / thirdparty / man-pages.git / blobdiff