getxattr.2: Various rewordings plus one or two details clarified

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
This commit is contained in:
Michael Kerrisk 2015-01-24 10:27:54 +01:00
parent f1ec5ad108
commit fae9230bda
1 changed files with 23 additions and 19 deletions

View File

@ -52,16 +52,17 @@ A complete overview of extended attributes concepts can be found in
.BR attr (5). .BR attr (5).
.PP .PP
.BR getxattr () .BR getxattr ()
retrieves the retrieves the value of the extended attribute identified by
.I value
of the extended attribute identified by
.I name .I name
and associated with the given and associated with the given
.I path .I path
in the filesystem. in the filesystem.
The length of the attribute The attribute value is placed in the buffer pointed to by
.I value .IR value ;
is returned. .I size
specifies the size of that buffer.
The return value of the call is the number of bytes placed in
.IR value .
.PP .PP
.BR lgetxattr () .BR lgetxattr ()
is identical to is identical to
@ -81,25 +82,28 @@ is interrogated in place of
.PP .PP
An extended attribute An extended attribute
.I name .I name
is a simple null-terminated string. is a null-terminated string.
The name includes a namespace prefix; there may be several, disjoint The name includes a namespace prefix; there may be several, disjoint
namespaces associated with an individual inode. namespaces associated with an individual inode.
The value of an extended attribute is a chunk of arbitrary textual or 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 .PP
An empty buffer of If
.I size .I size
zero can be passed into these calls to return the current size of the is specified as zero, these calls return the current size of the
named extended attribute, which can be used to estimate the size of a named extended attribute (and leave
buffer which is sufficiently large to hold the value associated with .I value
the extended attribute. unchanged).
.PP This can be used to determine the size of the buffer that
The interface is designed to allow guessing of initial buffer should be supplied in a subsequent call.
sizes, and to enlarge buffers when the return value indicates (But, bear in mind that there is a possibility that the
that the buffer provided was too small. 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 .SH RETURN VALUE
On success, a nonnegative number is returned indicating the size of the On success, these calls return a nonnegative value which is
extended attribute value. the size (in bytes) of the extended attribute value.
On failure, \-1 is returned and On failure, \-1 is returned and
.I errno .I errno
is set appropriately. is set appropriately.