getgroups: document portability issues

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 <eblake@redhat.com>

diff --git a/ChangeLog b/ChangeLog
index 9241e189c5f2df1947b4c9159b7a882a7868650f..aa74ea4f32d5c41e6c5b9e8448c7cc6fcf918d52 100644 (file)
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,15 @@
+2013-05-22  Eric Blake  <eblake@redhat.com>
+
+       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 <mail@bernhard-voelker.de>
 
        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 e0dfa4976e9bb2a025814098975f8f3a5650cbb3..8a37cb1e9d62077c952b8005b6984f2bcbbd2b63 100644 (file)
--- a/doc/glibc-functions/getgrouplist.texi
+++ b/doc/glibc-functions/getgrouplist.texi
@@ -14,3 +14,5 @@ Portability problems not fixed by Gnulib:
 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 2539fc2762459ff8d51afd5a0dabe62a6e5631d6..ac55bca6e38e5c3c1c684175587bc4dba089d16f 100644 (file)
--- a/doc/glibc-functions/initgroups.texi
+++ b/doc/glibc-functions/initgroups.texi
@@ -11,6 +11,11 @@ Portability problems fixed by Gnulib:
 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
+@code{getgrouplist} (or use the gnulib module @code{mgetgroups})
+before forking, and @code{setgroups} in the child.
+@item
 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 9119ea90f9b142a6f12297bce0629669081cbfae..27dfdc4bd9be33777567f24a1c9e612db8e3639a 100644 (file)
--- a/doc/posix-functions/getgroups.texi
+++ b/doc/posix-functions/getgroups.texi
@@ -26,9 +26,14 @@ even though that was a different size than an array of @samp{gid_t}.
 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.
+@item
 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 cfc765c375b6c3e07bb002ade4e7e650d44240b6..5f8308d53ad8a077222ed9262ad3e27643cb685b 100644 (file)
--- a/doc/posix-functions/getpwuid.texi
+++ b/doc/posix-functions/getpwuid.texi
@@ -13,6 +13,10 @@ Portability problems fixed by Gnulib:
 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.
+@item
 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 fd9272446d6192777cc47b0fc3301ad7e389335f..367ba925ff487e8b16f8866e80abeffc981edfca 100644 (file)
--- a/doc/posix-functions/getpwuid_r.texi
+++ b/doc/posix-functions/getpwuid_r.texi
@@ -16,6 +16,9 @@ Solaris 11 2011-11 (when @code{_POSIX_PTHREAD_SEMANTICS} is not defined).
 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.
+@item
 This function is missing on some platforms:
 OpenBSD 3.8, Minix 3.1.8, mingw, MSVC 9, BeOS.
 @end itemize