listxattr.2: Add note on handling increases in sizes of keys or values

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

diff --git a/man2/listxattr.2 b/man2/listxattr.2
index 7b39df65aacee532beb141cc053e4733ecf3caaa..52c32ffb7a35ed6c6491ce9189b431dbe00e9e8c 100644 (file)
--- a/man2/listxattr.2
+++ b/man2/listxattr.2
@@ -171,6 +171,18 @@ 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.
 
 The following output was recorded by first creating a file, setting
 some extended file attributes,