From fae9230bda99b27d6f67eebe1c0c0f096da1e10e Mon Sep 17 00:00:00 2001
From: Michael Kerrisk <mtk.manpages@gmail.com>
Date: Sat, 24 Jan 2015 10:27:54 +0100
Subject: [PATCH] getxattr.2: Various rewordings plus one or two details
 clarified

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
---
 man2/getxattr.2 | 42 +++++++++++++++++++++++-------------------
 1 file changed, 23 insertions(+), 19 deletions(-)

diff --git a/man2/getxattr.2 b/man2/getxattr.2
index 617ddf939..5c270a15f 100644
--- a/man2/getxattr.2
+++ b/man2/getxattr.2
@@ -52,16 +52,17 @@ A complete overview of extended attributes concepts can be found in
 .BR attr (5).
 .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
@@ -81,25 +82,28 @@ 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 nonnegative 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.