[PATCH] getgroups: document portability issues

[Eric Blake]

Because I actually managed to hit deadlock in libvirt's child
process due to glibc's mutex use in user database lookup, I
figured it is worth documenting the issue for others to be
aware of when writing a privileged multithreaded parent app
that spawns child processes owned by non-privileged ids.

* doc/glibc-functions/initgroups.texi (initgroups): Mention
multithread safety.
* doc/posix-functions/getpwuid.texi (getpwuid): Likewise.
* doc/posix-functions/getpwuid_r.texi (getpwuid_r): Likewise.
* doc/glibc-functions/getgrouplist.texi (getgrouplist): Mention
getugroups.
* doc/posix-functions/getgroups.texi (getgroups): Mention
multithread safety and mgetgroups.

Signed-off-by: Eric Blake <address@hidden>
---
 ChangeLog                             | 12 ++++++++++++
 doc/glibc-functions/getgrouplist.texi |  2 ++
 doc/glibc-functions/initgroups.texi   |  5 +++++
 doc/posix-functions/getgroups.texi    |  5 +++++
 doc/posix-functions/getpwuid.texi     |  4 ++++
 doc/posix-functions/getpwuid_r.texi   |  3 +++
 6 files changed, 31 insertions(+)

diff --git a/ChangeLog b/ChangeLog
index 9241e18..aa74ea4 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,15 @@
+2013-05-22  Eric Blake  <address@hidden>
+
+       getgroups: document portability issues
+       * doc/glibc-functions/initgroups.texi (initgroups): Mention
+       multithread safety.
+       * doc/posix-functions/getpwuid.texi (getpwuid): Likewise.
+       * doc/posix-functions/getpwuid_r.texi (getpwuid_r): Likewise.
+       * doc/glibc-functions/getgrouplist.texi (getgrouplist): Mention
+       getugroups.
+       * doc/posix-functions/getgroups.texi (getgroups): Mention
+       multithread safety and mgetgroups.
+
 2013-05-22  Bernhard Voelker <address@hidden>

        test-lchown, test-chown: also skip test if chown fails with EPERM
diff --git a/doc/glibc-functions/getgrouplist.texi 
b/doc/glibc-functions/getgrouplist.texi
index e0dfa49..8a37cb1 100644
--- a/doc/glibc-functions/getgrouplist.texi
+++ b/doc/glibc-functions/getgrouplist.texi
@@ -14,3 +14,5 @@ getgrouplist
 This function is missing on some platforms:
 Minix 3.1.8, AIX 5.1, HP-UX 11, IRIX 6.5, OSF/1 5.1, Solaris 11 2011-11, 
Cygwin 1.7.9, mingw, MSVC 9, BeOS.
 @end itemize
+
+The Gnulib module @code{getugroups} provides a similar API.
diff --git a/doc/glibc-functions/initgroups.texi 
b/doc/glibc-functions/initgroups.texi
index 2539fc2..ac55bca 100644
--- a/doc/glibc-functions/initgroups.texi
+++ b/doc/glibc-functions/initgroups.texi
@@ -11,6 +11,11 @@ initgroups
 Portability problems not fixed by Gnulib:
 @itemize
 @item
+This function is unsafe to call between @code{fork} and @code{exec} if
+the parent process is multi-threaded.  Instead, use @code{getgroups} or
address@hidden (or use the gnulib module @code{mgetgroups})
+before forking, and @code{setgroups} in the child.
address@hidden
 This function is missing on some platforms:
 mingw, MSVC 9, Interix 3.5, BeOS.
 @end itemize
diff --git a/doc/posix-functions/getgroups.texi 
b/doc/posix-functions/getgroups.texi
index 9119ea9..27dfdc4 100644
--- a/doc/posix-functions/getgroups.texi
+++ b/doc/posix-functions/getgroups.texi
@@ -26,9 +26,14 @@ getgroups
 Portability problems not fixed by Gnulib:
 @itemize
 @item
+This function is unsafe to call between @code{fork} and @code{exec} if
+the parent process is multi-threaded.
address@hidden
 It is unspecified whether the effective group id will be included in
 the returned list, nor whether the list will be sorted in any
 particular order.  For that matter, some platforms include the
 effective group id twice, if it is also a member of the current
 supplemental group ids.
 @end itemize
+
+The Gnulib module @code{mgetgroups} provides a similar API.
diff --git a/doc/posix-functions/getpwuid.texi 
b/doc/posix-functions/getpwuid.texi
index cfc765c..5f8308d 100644
--- a/doc/posix-functions/getpwuid.texi
+++ b/doc/posix-functions/getpwuid.texi
@@ -13,6 +13,10 @@ getpwuid
 Portability problems not fixed by Gnulib:
 @itemize
 @item
+This function is unsafe to call between @code{fork} and @code{exec} if
+the parent process is multi-threaded.  Instead, use @code{getpwuid_r}
+prior to forking.
address@hidden
 This function is missing on some platforms:
 mingw, MSVC 9.
 @end itemize
diff --git a/doc/posix-functions/getpwuid_r.texi 
b/doc/posix-functions/getpwuid_r.texi
index fd92724..367ba92 100644
--- a/doc/posix-functions/getpwuid_r.texi
+++ b/doc/posix-functions/getpwuid_r.texi
@@ -16,6 +16,9 @@ getpwuid_r
 Portability problems not fixed by Gnulib:
 @itemize
 @item
+This function is unsafe to call between @code{fork} and @code{exec} if
+the parent process is multi-threaded.  Use it prior to forking.
address@hidden
 This function is missing on some platforms:
 OpenBSD 3.8, Minix 3.1.8, mingw, MSVC 9, BeOS.
 @end itemize
-- 
1.8.1.4