s3:include: Fix the smbc_fgetxattr() documentation in libsmbclient

BUG: https://bugzilla.samba.org/show_bug.cgi?id=15960

Signed-off-by: Andreas Schneider <asn@samba.org>
Reviewed-by: Ralph Boehme <slow@samba.org>
Autobuild-User(master): Andreas Schneider <asn@cryptomilk.org>
Autobuild-Date(master): Tue Dec  9 19:33:22 UTC 2025 on atb-devel-224

diff --git a/source3/include/libsmbclient.h b/source3/include/libsmbclient.h
index 948eba3361a630f55e6fd4d9d300ba0e03d54b9b..e3a2094754e825bcda1ac0187e83f852a9a3044d 100644 (file)
--- a/source3/include/libsmbclient.h
+++ b/source3/include/libsmbclient.h
@@ -2477,6 +2477,31 @@ int smbc_lgetxattr(const char *url,
  *                  to names.  Without the plus sign, SIDs are not mapped;
  *                  rather they are simply converted to a string format.
  *
+ *                  When POSIX extensions are enabled (via
+ *                  smbc_setOptionPosixExtensions()), the following additional
+ *                  attribute names are available:
+ *
+ *                     posix.attr.enabled
+ *                        Returns "1" if POSIX extensions are active on the
+ *                        server connection, "0" otherwise. The value buffer
+ *                        must be at least 2 bytes to include the null
+ *                        terminator. The returned size is 1 (excluding the
+ *                        null terminator).
+ *                        This is only a check on internal structures, it
+ *                        doesn't produce any network traffic.
+ *
+ *                     smb311_posix.statinfo
+ *                        Returns POSIX stat information via a network call to
+ *                        the server. The value buffer must be at least
+ *                        sizeof(struct stat) + 4 bytes. The buffer contains a
+ *                        struct stat followed by 4 bytes of DOS attributes.
+ *                        The returned size is sizeof(struct stat), which
+ *                        should be used as the offset to read the DOS
+ *                        attributes from the buffer. This provides e.g the
+ *                        correct uid/gid on the server and hardlink counts
+ *                        (st_nlink) and other POSIX metadata not available
+ *                        through standard stat calls.
+ *
  * @param value     A pointer to a buffer in which the value of the specified
  *                  attribute will be placed (unless size is zero).
  *
@@ -2485,7 +2510,8 @@ int smbc_lgetxattr(const char *url,
  *                  required to hold the attribute value will be returned,
  *                  but nothing will be placed into the value buffer.
  *
- * @return          0 on success, < 0 on error with errno set:
+ * @return          On success, the number of bytes of the extended attribute
+ *                  returned. On error, -1 is returned with errno set:
  *                  - EINVAL  The client library is not properly initialized
  *                            or one of the parameters is not of a correct
  *                            form