git: 57d53eb6832f - stable/12 - extattr_get_file(2): clarify RETURN VALUES

The branch stable/12 has been updated by ngie:

URL: https://cgit.FreeBSD.org/src/commit/?id=57d53eb6832f78cdf42e6ded97f7b5e64a829eb7

commit 57d53eb6832f78cdf42e6ded97f7b5e64a829eb7
Author:     Enji Cooper <ngie@FreeBSD.org>
AuthorDate: 2020-12-08 04:16:05 +0000
Commit:     Enji Cooper <ngie@FreeBSD.org>
CommitDate: 2022-04-11 01:23:36 +0000

    extattr_get_file(2): clarify RETURN VALUES
    
    While some of the syscalls' behavior were documented and implied in the
    RETURN VALUES section by earlier, e.g., the DESCRIPTION sections, as having
    behavior of the other calls (`*_fd` vs `*_file` vs `*_link`), there was a lot
    of implied return value behavior in the section prior to this change.
    
    Explicitly document the syscall behavior per the current implementation in
    sys/kern/vfs_extattr.c so others can better develop based on its explicit
    documented behavior instead of having to digest the context of the manpage to
    understand the appropriate behavior.
    
    MFC after:      1 week
    MFC with:       r368431, r368433, r368434
    Sponsored by:   DellEMC Isilon
    
    (cherry picked from commit cf681016d47ed689da60c8cfe1a4fb894e036b4d)
---
 lib/libc/sys/extattr_get_file.2 | 19 +++++++++++++++----
 1 file changed, 15 insertions(+), 4 deletions(-)

diff --git a/lib/libc/sys/extattr_get_file.2 b/lib/libc/sys/extattr_get_file.2
index a9a2defa8448..bc46440d46ab 100644
--- a/lib/libc/sys/extattr_get_file.2
+++ b/lib/libc/sys/extattr_get_file.2
@@ -169,21 +169,32 @@ For more information on named extended attributes, please see
 .Xr extattr 9 .
 .Sh RETURN VALUES
 If successful, the
+.Fn extattr_get_fd ,
 .Fn extattr_get_file ,
+.Fn extattr_get_link ,
+.Fn extattr_list_fd ,
+.Fn extattr_list_file ,
+.Fn extattr_list_link ,
+.Fn extattr_set_fd ,
 .Fn extattr_set_file ,
 and
-.Fn extattr_list_file
+.Fn extattr_set_link
 calls return the number of bytes
 that were read or written from the
 .Fa data ,
-respectively, or if
+respectively.
+If
 .Fa data
 was
 .Dv NULL ,
 then
-.Fn extattr_get_file
+.Fn extattr_get_fd ,
+.Fn extattr_get_file ,
+.Fn extattr_get_link ,
+.Fn extattr_list_fd ,
+.Fn extattr_list_file ,
 and
-.Fn extattr_list_file
+.Fn extattr_list_link
 return the number of bytes available to read.
 If any of the calls are unsuccessful, the value \-1 is returned
 and the global variable