From 541329d51f82bce83bd81ff7640edabfc32d149c Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Juan=20Jos=C3=A9=20Arboleda?= <soyjuanarbol@gmail.com>
Date: Mon, 27 May 2024 16:47:52 -0500
Subject: doc: add entries for extended getpw
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

This patch adds documentation for the introduced `uv_os_get_passwd2`,
`uv_os_get_group`, `uv_os_free_group` methods in
https://github.com/libuv/libuv/pull/3523

Fixes: https://github.com/libuv/libuv/issues/4007
Signed-off-by: Juan José Arboleda <soyjuanarbol@gmail.com>
---
 docs/src/misc.rst | 41 +++++++++++++++++++++++++++++++++++++++++
 1 file changed, 41 insertions(+)

(limited to 'docs/src')

diff --git a/docs/src/misc.rst b/docs/src/misc.rst
index 98961830..239fc176 100644
--- a/docs/src/misc.rst
+++ b/docs/src/misc.rst
@@ -199,6 +199,18 @@ Data types
             char* homedir;
         } uv_passwd_t;
 
+.. c:type:: uv_group_s
+
+    Data type for group file information.
+
+    ::
+
+        typedef struct uv_group_s {
+          char* groupname;
+          unsigned long gid;
+          char** members;
+        };
+
 .. c:type:: uv_utsname_t
 
     Data type for operating system name and version information.
@@ -566,6 +578,35 @@ API
 
     .. versionadded:: 1.9.0
 
+.. c:function:: int uv_os_get_passwd2(uv_passwd_t* pwd, uv_uid_t uid)
+
+    Gets a subset of the password file entry for the provided uid.
+    The populated data includes the username, euid, gid, shell,
+    and home directory. On non-Windows systems, all data comes from
+    :man:`getpwuid_r(3)`. On Windows, uid and gid are set to -1 and have no
+    meaning, and shell is `NULL`. After successfully calling this function, the
+    memory allocated to `pwd` needs to be freed with
+    :c:func:`uv_os_free_passwd`.
+
+    .. versionadded:: 1.45.0
+
+.. c:function:: int uv_os_get_group(uv_group_s* group, uv_uid_t gid)
+
+    Gets a subset of the group file entry for the provided uid.
+    The populated data includes the group name, gid, and members. On non-Windows
+    systems, all data comes from :man:`getgrgid_r(3)`. On Windows, uid and gid
+    are set to -1 and have no meaning. After successfully calling this function,
+    the memory allocated to `group` needs to be freed with
+    :c:func:`uv_os_free_group`.
+
+    .. versionadded:: 1.45.0
+
+.. c:function:: void uv_os_free_group(uv_passwd_t* pwd)
+
+    Frees the memory previously allocated with :c:func:`uv_os_get_group`.
+
+    .. versionadded:: 1.45.0
+
 .. c:function:: void uv_os_free_passwd(uv_passwd_t* pwd)
 
     Frees the `pwd` memory previously allocated with :c:func:`uv_os_get_passwd`.
-- 
cgit v1.2.3