update from main archive 961030cvs/libc-961031

Thu Oct 31 00:01:39 1996  Ulrich Drepper  <drepper@cygnus.com>

	* signal/Makefile (routines): Add sigwait.
	* signal/signal.h: Add prototype for sigwait.
	* sysdeps/posix/sigwait.c: New file.  Implementation of sigwait
	function from POSIX.1c.
	* sysdeps/stub/sigwait.c: New file.  Stub version of sigwait.

Wed Oct 30 02:01:17 1996  Richard Henderson  <rth@tamu.edu>

	* sunrpc/xdr_float.c (xdr_float): Handle sizeof(float)!=sizeof(long),
	but don't bother going farther than sizeof(float)==sizeof(int).
	(xdr_double): Handle little-endian machines!  Handle sizeof(double)
	!= 2*sizeof(long), though again don't bother with more than int.

Thu Oct 29 16:09:42 1996  Craig Metz  <cmetz@inner.net>

	* sysdeps/posix/getaddrinfo.c: Use buffer limits for inet_ntop
	function.

Tue Oct 29 12:37:22 1996  Ulrich Drepper  <drepper@cygnus.com>

	* Makerules: Create symbolic links for linking in $(libdir).
	(make-link): Use absolute path for destination if this is not in
	the same directory.

	* elf/rtld.c (dl_main): When verifying don't check the name of
	the dynamic linker.

	* shlib-versions: Change entries for Hurd specific libs from
	*-*-gnu* to *-*-gnu?* so that i586-pc-linux-gnu does not match
	these entries.

	* assert/assert.h: Reformat copyright.
	Change reference to ANSI into reference to ISO C.
	* ctype/ctype.h: Likewise.
	* errno.h: Likewise.
	* limits.h: Likewise.
	* math/math.h: Likewise.
	* setjmp/setjmp.h: Likewise.
	* stdio/stdio.h: Likewise.
	* libio/stdio.h: Likewise.
	* stdlib/stdlib.h: Likewise.
	* string/string.h: Likewise.
	* time/time.h: Likewise.

	* string/argz.h: Use __const is definitions.

	* elf/dlfcn.h: Use __const and __P.  Reformat copyright.
	* misc/err.h: Likewise.

	* wctype/wctype.h (wctrans_t): Use __const instead of const.

	* Makeconfig ($(common-objpfx)soversions.mk): Generate list of
	sonames for versioned libraries.
	* Makefile: Remove code to generate libc-version.h.
	Generate gnu/lib-names.h with info from soversions.mk.
	* features.h: Define __GLIBC__ and __GLIBC_MINOR__.

	* dirent/tst-seekdir.c: Initialize save3.
	* grp/testgrp.c: Initialize my_group.

	* grp/fgetgrent_r.c: Change interface to follow POSIX.1c.
	* grp/grp.h: Likewise.
	* nss/getXXbyYY.c: Likewise.
	* nss/getXXbyYY_r.c: Likewise.
	* nss/getXXent.c: Likewise.
	* nss/getXXent_r.c: Likewise.
	* pwd/fgetpwent_r.c: Likewise.
	* pwd/pwd.h: Likewise.
	* shadow/fgetspent_r.c: Likewise.
	* shadow/sgetspent.c: Likewise.
	* shadow/sgetspent_r.c: Likewise.
	* grp/fgetgrent.c: Adapt for change in interface of fgetgrent_r.
	* pwd/fgetpwent.c: Likewise, for fgetpwent_r.c.
	* shadow/fgetspent.c: Likewise, for fgetpwent_r.c.
	* resolv/netdb.h: Adapt prototypes for reentrant functions to
	follow POSIX.1c.
	* sunrpc/rpc/netdb.h: Likewise,
	* shadow/shadow.h: Likewise.

	* inet/getnetgrent_r.c: Follow change in pwd/grp function interface.

	* sysdeps/unix/getlogin_r.c: Return ERANGE when buffer is too small.

	* inet/herrno.c: Don't define __h_errno.  Only h_errno otherwise the
	ELF aliasing creates strange situations.
	* sysdeps/unix/sysv/linux/errnos.H: Define __set_errno as inline
	function.
	* sysdeps/unix/sysv/linux/i386/sysdep.S: Don't define __errno.
	* sysdeps/unix/sysv/linux/m68k/sysdep.S: Likewise.

	* libio/libio.h: Don't declare _IO_flockfile and _IO_funlockfile
	weak.

	* locale/programs/charmap.c: Add casts to prevent warnings.
	* locale/programs/linereader.h: Likewise.
	* locale/programs/ld-collate.c: Likewise.
	* locale/programs/stringtrans.c: Likewise.
	Change types for various variables to prevent warnings.
	* locale/programs/ld-ctype.c: Likewise.
	* locale/programs/linereader.h (lr_ungetc): Likewise.
	* locale/programs/charset.h (struct charset): Use `unsigned int'
	as type for width_default.
	* posix/regex.c: Change type of `this_reg' variables.
	* stdio-common/Makefile: Use -Wno-format for tstdiomisc.c.
	* stdio-common/bug5.c: De-ANSI-fy.  Use correct types for
	variables.
	* stdio-common/printf_fp.c: Initialize to_shift.
	* stdio-common/test_rdwr.c: Add cast.
	* stdio-common/vfprintf.c: Add casts and use correct types to
	prevent warnings.
	* stdio-common/vfscanf.c: Initialize str and strptr.
	* sysdeps/libm-ieee754/e_jnf.c: Use correct types to prevent warnings.
	* sysdeps/libm-ieee754/e_pow.c: Likewise.
	* sysdeps/libm-ieee754/e_powf.c: Likewise.
	* sysdeps/libm-ieee754/e_rem_pio2f.c: Likewise.
	* time/test-tz.c: Likewise.

	* manual/creature.texi: Document _REENTRANT and _THREAD_SAFE.
	* manual/libc.texinfo: Prevent makeinfo failure by avoiding
	libc.cp index.  This must be fixed.
	* manual/nss.texi: Adapt for correct POSIX.1c interface of
	reentrant functions.
	* manual/users.texi: Document netgroup functions.

	* po/es.po: Updated.
	* po/fr.po: Updated.

	* posix/fnmatch.c: Change to match libit version.

	* posix/unistd.h: Change prototype for ttyname_r to match POSIX.1c.
	* sysdep/posix/ttyname_r.c: Likewise.

	* stdlib/atexit.h (__new_exitfn): Add internal locking.
	* stdlib/exit.c: De-ANSI-fy.  Handle new ef_us value for flavor.
	* stdlib/exit.h: De-ANSI-fy.  Define new ef_us value for flavor.
	* stdlib/random.c (__srandom): Add internal locking.
	(__initstate): Likewise.
	(__setstate): Likewise.
	(__random): Likewise.

Mon Oct 28 22:28:37 1996  NIIBE Yutaka  <gniibe@mri.co.jp>

	* sysdeps/generic/crypt-entry.c (crypt_r): Use __set_errno.
	(crypt): Likewise.
	* resolv/gethnamaddr.c (gethostbyname2): Likewise.
	* sysdeps/generic/uname.c: Likewise.
	* sysdeps/posix/rename.c: Likewise.
	* sysdeps/stub/setrlimit.c: Likewise.

	* nss/nss_db/db-netgrp.c (_nss_db_setnetgrent): Fix typo.

Sun Oct 27 11:12:50 1996  Andreas Schwab  <schwab@issan.informatik.uni-dortmund.de>

	* locale/programs/ld-collate.c (collate_order_elem): Fix format
	string.
	(collate_element_to): Cast field width argument to `int' for
	format string.
	(collate_symbol): Likewise.
	(collate_order_elem): Likewise.
	(collate_weight_bsymbol): Likewise.
	(collate_simple_weight): Likewise.

	* locale/programs/ld-time.c (STRARR_ELEM): Fix format string.

	* locale/programs/ld-ctype.c (ctype_class_newP): Add missing
	argument for format string.
	(ctype_map_newP): Likewise.
	(set_class_defaults): Fix format string.

	* locale/programs/localedef.c (construct_output_path): Putting an
	explicit \0 into the format string does not work, use %c.

Sat Oct 26 20:38:36 1996  Richard Henderson  <rth@tamu.edu>

	* Makerules: Install all shared libraries in $(slibdir).

	* login/Makefile: Build libutil.so in others pass after
	libc.so is created.

	* misc/mntent.h: Include <paths.h> for _PATH_MNTTAB & _PATH_MOUNTED.

	* string/stratcliff.c: Allocate 3 pages instead of one, then use
	mprotect so that we know that the adjacent pages are inaccessible.

	* resource/sys/resource.h: Move all structures and enums to ...
	* sysdeps/generic/resourcebits.h: ... here ...
	* sysdeps/unix/bsd/sun/sunos4/resourcebits.h: ... and here.
	* sysdeps/unix/sysv/linux/alpha/resourcebits.h: Remove.
	* sysdeps/unix/sysv/linux/i386/resourcebits.h: Remove.
	* sysdeps/unix/sysv/linux/m68k/resourcebits.h: Remove.
	* sysdeps/unix/sysv/linux/mips/resourcebits.h: Remove.
	* sysdeps/unix/sysv/linux/resourcebits.h: New file.  Use kernel
	header for RLIMIT_* definitions.  The members of struct rlimit
	are longs.


Thu Oct 24 17:43:34 1996  Andreas Schwab  <schwab@issan.informatik.uni-dortmund.de>

	* MakeTAGS (sysdep-dirs): Fix typo.

Wed Oct 23 03:45:22 1996  Ulrich Drepper  <drepper@cygnus.com>

	* Makefile (headers): Don't mention libc-version.h.
	(install-others): ...but here.

	* time/strptime.c: Recognize %s, %u, %g, and %G format.
 	nothing is found.  This guarantees all subsequent calls behave
	* sysdeps/unix/sysv/linux/syscalls.list: Change function name for
	* io/getwd.c (getwd) [! PATH_MAX]: Don't assume that the user's
	buffer is any longer than the amount necessary to hold the
	filename; the Hurd getcwd uses the *entire* contents of the
	buffer, however long it is specified to be.
	* posix/getconf.c: De-ANSI-fy.  Recognize POSIX.2 constant names.
	since these do not depend on the platform.

1 files changed, 333 insertions, 27 deletions

diff --git a/manual/users.texi b/manual/users.texi
index b1d0d6f929..e20c90ddaa 100644
--- a/manual/users.texi
+++ b/manual/users.texi
@@ -1,4 +1,4 @@
-@node Users and Groups, System Information, Name Service Switch, Top
+@node Users and Groups
 @chapter Users and Groups
 
 Every user who can log in on the system is identified by a unique number
@@ -46,11 +46,12 @@ can use to examine these databases.
                         	 accessing the user database.
 * Group Database::              Functions and data structures for
                         	 accessing the group database.
+* Netgroup Database::           Functions for accessing the netgroup database.
 * Database Example::            Example program showing use of database
 				 inquiry functions.
 @end menu
 
-@node User and Group IDs
+@node User and Group IDs, Process Persona, Users and Groups, Users and Groups
 @section User and Group IDs
 
 @cindex login name
@@ -71,7 +72,7 @@ not accessible to users who are not a member of that group.  Each group
 has a @dfn{group name} and @dfn{group ID}.  @xref{Group Database},
 for how to find information about a group ID or group name.
 
-@node Process Persona
+@node Process Persona, Why Change Persona, User and Group IDs, Users and Groups
 @section The Persona of a Process
 @cindex persona
 @cindex effective user ID
@@ -113,7 +114,7 @@ its permission to access files, see @ref{Access Permission}.
 The user ID of a process also controls permissions for sending signals
 using the @code{kill} function.  @xref{Signaling Another Process}.
 
-@node Why Change Persona
+@node Why Change Persona, How Change Persona, Process Persona, Users and Groups
 @section Why Change the Persona of a Process?
 
 The most obvious situation where it is necessary for a process to change
@@ -145,7 +146,7 @@ the game program wants to update this file, it can change its effective
 user ID to be that for @code{games}.  In effect, the program must
 adopt the persona of @code{games} so it can write the scores file.
 
-@node How Change Persona
+@node How Change Persona, Reading Persona, Why Change Persona, Users and Groups
 @section How an Application Can Change Persona
 @cindex @code{setuid} programs
 
@@ -176,7 +177,7 @@ when they are not needed, which makes for more robustness.
 
 @c !!! talk about _POSIX_SAVED_IDS
 
-@node Reading Persona
+@node Reading Persona, Setting User ID, How Change Persona, Users and Groups
 @section Reading the Persona of a Process
 
 Here are detailed descriptions of the functions for reading the user and
@@ -261,7 +262,7 @@ read_all_groups (void)
 @end smallexample
 @end deftypefun
 
-@node Setting User ID
+@node Setting User ID, Setting Groups, Reading Persona, Users and Groups
 @section Setting the User ID
 
 This section describes the functions for altering the user ID (real
@@ -324,7 +325,7 @@ have permission to change to the specified ID.
 @end table
 @end deftypefun
 
-@node Setting Groups
+@node Setting Groups, Enable/Disable Setuid, Setting User ID, Users and Groups
 @section Setting the Group IDs
 
 This section describes the functions for altering the group IDs (real
@@ -399,7 +400,7 @@ the user name @var{user}.  The group ID @var{gid} is also included.
 @c groups USER is a member of.
 @end deftypefun
 
-@node Enable/Disable Setuid
+@node Enable/Disable Setuid, Setuid Program Example, Setting Groups, Users and Groups
 @section Enabling and Disabling Setuid Access
 
 A typical setuid program does not need its special access all of the
@@ -465,7 +466,7 @@ feature with a preprocessor conditional, like this:
 #endif
 @end smallexample
 
-@node Setuid Program Example
+@node Setuid Program Example, Tips for Setuid, Enable/Disable Setuid, Users and Groups
 @section Setuid Program Example
 
 Here's an example showing how to set up a program that changes its
@@ -605,7 +606,7 @@ record_score (int score)
 @end group
 @end smallexample
 
-@node Tips for Setuid
+@node Tips for Setuid, Who Logged In, Setuid Program Example, Users and Groups
 @section Tips for Writing Setuid Programs
 
 It is easy for setuid programs to give the user access that isn't
@@ -649,7 +650,7 @@ would ordinarily have permission to access those files.  You can use the
 uses the real user and group IDs, rather than the effective IDs.
 @end itemize
 
-@node Who Logged In
+@node Who Logged In, User Database, Tips for Setuid, Users and Groups
 @section Identifying Who Logged In
 @cindex login name, determining
 @cindex user ID, determining
@@ -703,7 +704,7 @@ For most purposes, it is more useful to use the environment variable
 precisely because the user can set @code{LOGNAME} arbitrarily.
 @xref{Standard Environment}.
 
-@node User Database
+@node User Database, Group Database, Who Logged In, Users and Groups
 @section User Database
 @cindex user database
 @cindex password database
@@ -721,7 +722,7 @@ network server gives access to it.
 * Writing a User Entry::        How a program can rewrite a user's record.
 @end menu
 
-@node User Data Structure
+@node User Data Structure, Lookup User, User Database, User Database
 @subsection The Data Structure that Describes a User
 
 The functions and data structures for accessing the system user database
@@ -762,7 +763,7 @@ be used.
 @end table
 @end deftp
 
-@node Lookup User
+@node Lookup User, Scanning All Users, User Data Structure, User Database
 @subsection Looking Up One User
 @cindex converting user ID to user name
 @cindex converting user name to user ID
@@ -783,6 +784,27 @@ user ID @var{uid}.
 @end deftypefun
 
 @comment pwd.h
+@comment POSIX.1c
+@deftypefun int getpwuid_r (uid_t @var{uid}, struct passwd *@var{result_buf}, char *@var{buffer}, size_t @var{buflen}, struct passwd **@var{result})
+This function is similar to @code{getpwuid} in that is returns
+information about the user whose user ID is @var{uid}.  But the result
+is not placed in a static buffer.  Instead the user supplied structure
+pointed to by @var{result_buf} is filled with the information.  The
+first @var{buflen} bytes of the additional buffer pointed to by
+@var{buffer} are used to contain additional information, normally
+strings which are pointed to by the elements of the result structure.
+
+If the return value is @code{0} the pointer returned in @var{result}
+points to the record which contains the wanted data (i.e., @var{result}
+contains the value @var{result_buf}).  In case the return value is non
+null there is no user in the data base with user ID @var{uid} or the
+buffer @var{buffer} is too small to contain all the needed information.
+In the later case the global @var{errno} variable is set to
+@code{ERANGE}.
+@end deftypefun
+
+
+@comment pwd.h
 @comment POSIX.1
 @deftypefun {struct passwd *} getpwnam (const char *@var{name})
 This function returns a pointer to a statically-allocated structure
@@ -793,7 +815,28 @@ This structure may be overwritten on subsequent calls to
 A null pointer value indicates there is no user named @var{name}.
 @end deftypefun
 
-@node Scanning All Users
+@comment pwd.h
+@comment POSIX.1c
+@deftypefun int getpwnam_r (const char *@var{name}, struct passwd *@var{result_buf}, char *@var{buffer}, size_t @var{buflen}, struct passwd **@var{result})
+This function is similar to @code{getpwnam} in that is returns
+information about the user whose user name is @var{name}.  But the result
+is not placed in a static buffer.  Instead the user supplied structure
+pointed to by @var{result_buf} is filled with the information.  The
+first @var{buflen} bytes of the additional buffer pointed to by
+@var{buffer} are used to contain additional information, normally
+strings which are pointed to by the elements of the result structure.
+
+If the return value is @code{0} the pointer returned in @var{result}
+points to the record which contains the wanted data (i.e., @var{result}
+contains the value @var{result_buf}).  In case the return value is non
+null there is no user in the data base with user name @var{name} or the
+buffer @var{buffer} is too small to contain all the needed information.
+In the later case the global @var{errno} variable is set to
+@code{ERANGE}.
+@end deftypefun
+
+
+@node Scanning All Users, Writing a User Entry, Lookup User, User Database
 @subsection Scanning the List of All Users
 @cindex scanning the user list
 
@@ -816,14 +859,33 @@ This stream must correspond to a file in the same format as the standard
 password database file.  This function comes from System V.
 @end deftypefun
 
+@comment pwd.h
+@comment GNU
+@deftypefun int fgetpwent_r (FILE *@var{stream}, struct passwd *@var{result_buf}, char *@var{buffer}, size_t @var{buflen}, struct passwd **@var{result})
+This function is similar to @code{fgetpwent} in that it reads the next
+user entry from @var{stream}.  But the result is returned in the
+structure pointed to by @var{result_buf}.  The
+first @var{buflen} bytes of the additional buffer pointed to by
+@var{buffer} are used to contain additional information, normally
+strings which are pointed to by the elements of the result structure.
+
+This stream must correspond to a file in the same format as the standard
+password database file.
+
+If the funciton returns null @var{result} points to the structure with
+the wanted data (normally this is in @var{result_buf}).  If errors
+occured the return value is non-null and @var{result} contains a null
+pointer.
+@end deftypefun
+
 The way to scan all the entries in the user database is with
 @code{setpwent}, @code{getpwent}, and @code{endpwent}.
 
 @comment pwd.h
 @comment SVID, BSD
 @deftypefun void setpwent (void)
-This function initializes a stream which @code{getpwent} uses to read
-the user database.
+This function initializes a stream which @code{getpwent} and
+@code{getpwent_r} use to read the user database.
 @end deftypefun
 
 @comment pwd.h
@@ -834,15 +896,35 @@ initialized by @code{setpwent}.  It returns a pointer to the entry.  The
 structure is statically allocated and is rewritten on subsequent calls
 to @code{getpwent}.  You must copy the contents of the structure if you
 wish to save the information.
+
+A null pointer is returned in case no further entry is available.
+@end deftypefun
+
+@comment pwd.h
+@comment GNU
+@deftypefun int getpwent_r (struct passwd *@var{result_buf}, char *@var{buffer}, int @var{buflen}, struct passwd **@var{result})
+This function is similar to @code{getpwent} in that it returns the next
+entry from the stream initialized by @code{setpwent}.  But in contrast
+to the @code{getpwent} function this function is reentrant since the
+result is placed in the user supplied structure pointed to by
+@var{result_buf}.  Additional data, normally the strings pointed to by
+the elements of the result structure, are placed in the additional
+buffer or length @var{buflen} starting at @var{buffer}.
+
+If the function returns null @var{result} points to the structure with
+the wanted data (normally this is in @var{result_buf}).  If errors
+occured the return value is non-null and @var{result} contains a null
+pointer.
 @end deftypefun
 
 @comment pwd.h
 @comment SVID, BSD
 @deftypefun void endpwent (void)
-This function closes the internal stream used by @code{getpwent}.
+This function closes the internal stream used by @code{getpwent} or
+@code{getpwent_r}.
 @end deftypefun
 
-@node Writing a User Entry
+@node Writing a User Entry,  , Scanning All Users, User Database
 @subsection Writing a User Entry
 
 @comment pwd.h
@@ -862,7 +944,7 @@ would inevitably leave out much of the important information.
 The function @code{putpwent} is declared in @file{pwd.h}.
 @end deftypefun
 
-@node Group Database
+@node Group Database, Netgroup Database, User Database, Users and Groups
 @section Group Database
 @cindex group database
 @pindex /etc/group
@@ -878,7 +960,7 @@ service provides access to it.
 * Scanning All Groups::         Scanning the list of all groups.
 @end menu
 
-@node Group Data Structure
+@node Group Data Structure, Lookup Group, Group Database, Group Database
 @subsection The Data Structure for a Group
 
 The functions and data structures for accessing the system group
@@ -905,7 +987,7 @@ null pointer.
 @end table
 @end deftp
 
-@node Lookup Group
+@node Lookup Group, Scanning All Groups, Group Data Structure, Group Database
 @subsection Looking Up One Group
 @cindex converting group name to group ID
 @cindex converting group ID to group name
@@ -926,6 +1008,26 @@ A null pointer indicates there is no group with ID @var{gid}.
 @end deftypefun
 
 @comment grp.h
+@comment POSIX.1c
+@deftypefun int getgrgid_r (gid_t @var{gid}, struct group *@var{result_buf}, char *@var{buffer}, size_t @var{buflen}, struct group **@var{result})
+This function is similar to @code{getgrgid} in that is returns
+information about the group whose group ID is @var{gid}.  But the result
+is not placed in a static buffer.  Instead the user supplied structure
+pointed to by @var{result_buf} is filled with the information.  The
+first @var{buflen} bytes of the additional buffer pointed to by
+@var{buffer} are used to contain additional information, normally
+strings which are pointed to by the elements of the result structure.
+
+If the return value is @code{0} the pointer returned in @var{result}
+points to the record which contains the wanted data (i.e., @var{result}
+contains the value @var{result_buf}).  In case the return value is non
+null there is no group in the data base with group ID @var{gid} or the
+buffer @var{buffer} is too small to contain all the needed information.
+In the later case the global @var{errno} variable is set to
+@code{ERANGE}.
+@end deftypefun
+
+@comment grp.h
 @comment SVID, BSD
 @deftypefun {struct group *} getgrnam (const char *@var{name})
 This function returns a pointer to a statically-allocated structure
@@ -936,7 +1038,27 @@ This structure may be overwritten by subsequent calls to
 A null pointer indicates there is no group named @var{name}.
 @end deftypefun
 
-@node Scanning All Groups
+@comment grp.h
+@comment POSIX.1c
+@deftypefun int getgrnam_r (const char *@var{name}, struct group *@var{result_buf}, char *@var{buffer}, size_t @var{buflen}, struct group **@var{result})
+This function is similar to @code{getgrnam} in that is returns
+information about the group whose group name is @var{name}.  But the result
+is not placed in a static buffer.  Instead the user supplied structure
+pointed to by @var{result_buf} is filled with the information.  The
+first @var{buflen} bytes of the additional buffer pointed to by
+@var{buffer} are used to contain additional information, normally
+strings which are pointed to by the elements of the result structure.
+
+If the return value is @code{0} the pointer returned in @var{result}
+points to the record which contains the wanted data (i.e., @var{result}
+contains the value @var{result_buf}).  In case the return value is non
+null there is no group in the data base with group name @var{name} or the
+buffer @var{buffer} is too small to contain all the needed information.
+In the later case the global @var{errno} variable is set to
+@code{ERANGE}.
+@end deftypefun
+
+@node Scanning All Groups,  , Lookup Group, Group Database
 @subsection Scanning the List of All Groups
 @cindex scanning the group list
 
@@ -960,6 +1082,25 @@ The stream must correspond to a file in the same format as the standard
 group database file.
 @end deftypefun
 
+@comment grp.h
+@comment GNU
+@deftypefun int fgetgrent_r (FILE *@var{stream}, struct group *@var{result_buf}, char *@var{buffer}, size_t @var{buflen}, struct group **@var{result})
+This function is similar to @code{fgetgrent} in that it reads the next
+user entry from @var{stream}.  But the result is returned in the
+structure pointed to by @var{result_buf}.  The
+first @var{buflen} bytes of the additional buffer pointed to by
+@var{buffer} are used to contain additional information, normally
+strings which are pointed to by the elements of the result structure.
+
+This stream must correspond to a file in the same format as the standard
+group database file.
+
+If the funciton returns null @var{result} points to the structure with
+the wanted data (normally this is in @var{result_buf}).  If errors
+occured the return value is non-null and @var{result} contains a null
+pointer.
+@end deftypefun
+
 The way to scan all the entries in the group database is with
 @code{setgrent}, @code{getgrent}, and @code{endgrent}.
 
@@ -967,7 +1108,7 @@ The way to scan all the entries in the group database is with
 @comment SVID, BSD
 @deftypefun void setgrent (void)
 This function initializes a stream for reading from the group data base.
-You use this stream by calling @code{getgrent}.
+You use this stream by calling @code{getgrent} or @code{getgrent_r}.
 @end deftypefun
 
 @comment grp.h
@@ -981,12 +1122,177 @@ wish to save the information.
 @end deftypefun
 
 @comment grp.h
+@comment GNU
+@deftypefun int getgrent_r (struct group *@var{result_buf}, char *@var{buffer}, size_t @var{buflen}, struct group **@var{result})
+This function is similar to @code{getgrent} in that it returns the next
+entry from the stream initialized by @code{setgrent}.  But in contrast
+to the @code{getgrent} function this function is reentrant since the
+result is placed in the user supplied structure pointed to by
+@var{result_buf}.  Additional data, normally the strings pointed to by
+the elements of the result structure, are placed in the additional
+buffer or length @var{buflen} starting at @var{buffer}.
+
+If the function returns null @var{result} points to the structure with
+the wanted data (normally this is in @var{result_buf}).  If errors
+occured the return value is non-null and @var{result} contains a null
+pointer.
+@end deftypefun
+
+@comment grp.h
 @comment SVID, BSD
 @deftypefun void endgrent (void)
-This function closes the internal stream used by @code{getgrent}.
+This function closes the internal stream used by @code{getgrent} or
+@code{getgrent_r}.
+@end deftypefun
+
+@node Netgroup Database, Database Example, Group Database, Users and Groups
+@section Netgroup Database
+
+@menu
+* Netgroup Data::                  Data in the Netgroup database and where
+                                   it comes from.
+* Lookup Netgroup::                How to look for a particular netgroup.
+* Netgroup Membership::            How to test for netgroup membership.
+@end menu
+
+@node Netgroup Data, Lookup Netgroup, Netgroup Database, Netgroup Database
+@subsection Netgroup Data
+
+@cindex{Netgroup}
+Sometimes it is useful group users according to other criterias like the
+ones used in the @xref{Group Database}.  E.g., it is useful to associate
+a certain group of users with a certain machine.  On the other hand
+grouping of host names is not supported so far.
+
+In Sun Microsystems SunOS appeared a new kind of database, the netgroup
+database.  It allows to group hosts, users, and domain freely, giving
+them individual names.  More concrete: a netgroup is a list of triples
+consisting of a host name, a user name, and a domain name, where any of
+the entries can be a wildcard entry, matching all inputs.  A last
+possibility is that names of other netgroups can also be given in the
+list specifying a netgroup.  So one can construct arbitrary hierachies
+without loops.
+
+Sun's implementation allows netgroups only for the @code{nis} or
+@code{nisplus} service @pxref{Services in the NSS configuration}.  The
+implementation in the GNU C library has no such restriction.  An entry
+in either of the input services must have the following form:
+
+@smallexample
+@var{groupname} ( @var{groupname} | @code{(}@var{hostname}@code{,}@var{username}@code{,}@code{domainname}@code{)} )+
+@end smallexample
+
+Any of the fields in the triple can be empty which means anything
+matches.  While describing te functions we will see that the opposite
+case is useful as well.  I.e., there shall be entries which will not
+match any input.  For entries like a name consisting of the single
+character @code{-} shall be used.
+
+@node Lookup Netgroup, Netgroup Membership, Netgroup Data, Netgroup Database
+@subsection Looking up one Netgroup
+
+The lookup functions for netgroups are a bit different to all other
+system database handling functions.  Since a single netgroup can contain
+many entries a two-step process is needed.  First a single netgroup is
+selected and then one can iterate over all entries in this netgroup.
+These functions are declared in @file{netdb.h}.
+
+@comment netdb.h
+@deftypefun int setnetgrent (const char *@var{netgroup})
+A call to this function initializes the internal state of the library to
+allow following calls of the @code{getnetgrent} iterate over all entries
+in the netgroup with name @var{netgroup}.
+
+When the call is successful (i.e., when a netgroup with this name exist)
+the return value is @code{1}.  When the return value is @code{0} no
+netgroup of this name is known or some other error occured.
+@end deftypefun
+
+It is important to remember that there is only one single state for
+iterating the netgroups.  Even if the programmer uses the
+@code{getnetgrent_r} function the result is not really reentrant since
+always only one single netgroup at a time can be processed.  If the
+program needs to process more than one netgroup simultaneously she
+must protect this by using external locking.  This problem was
+introduced in the original netgroups implementation in SunOS and since
+we must stay compatible it is not possible to change this.
+
+Some other functions also use the netgroups state.  Currently these are
+the @code{innetgr} function and parts of the implementation of the
+@code{compat} service part of the NSS implementation.
+
+@comment netdb.h
+@deftypefun int getnetgrent (char **@var{hostp}, char **@var{userp}, char **@var{domainp})
+This function returns the next unprocessed entry of the currently
+selected netgroup.  The string pointers, which addresses are passed in
+the arguments @var{hostp}, @var{userp}, and @var{domainp}, will contain
+after a successful call pointers to appropriate strings.  If the string
+in the next entry is empty the pointer has the value @code{NULL}.
+The returned string pointers are only valid unless no of the netgroup
+related functions are called.
+
+The return value is @code{1} if the next entry was successfully read.  A
+value of @code{0} means no further entry exist or internal errors occured.
+@end deftypefun
+
+@comment netdb.h
+@deftypefun int getnetgrent_r (char **@var{hostp}, char **@var{userp}, char **@var{domainp}, char *@var{buffer}, int @var{buflen})
+This function is similar to @code{getnetgrent} with only one exception:
+the strings the three string pointers @var{hostp}, @var{userp}, and
+@var{domainp} point to, are placed in the buffer of @var{buflen} bytes
+starting at @var{buffer}.  This means the returned values are valid
+even after other netgroup related functions are called.
+
+The return value is @code{1} if the next entry was successfully read and
+the buffer contains enough room to place the strings in it.  @code{0} is
+returned in case no more entries are found, the buffer is too small, or
+internal errors occured.
+
+This function is a GNU extension.  The original implementation in the
+SunOS libc does not provide this function.
+@end deftypefun
+
+@comment netdb.h
+@deftypefun void endnetgrent (void)
+This function free all buffers which were allocated to process the last
+selected netgroup.  As a result all string pointers returned by calls
+to @code{getnetgrent} are invalid afterwards.
+@end deftypefun
+
+@node Netgroup Membership,  , Lookup Netgroup, Netgroup Database
+@subsection Testing for Netgroup Membership
+
+It is often not necessary to scan the whole netgroup since often the
+only interesting question is whether a given entry is part of the
+selected netgroup.
+
+@comment netdb.h
+@deftypefun int innetgr (const char *@var{netgroup}, const char *@var{host}, const char *@var{user}, const char *@var{domain})
+This function tests whether the triple specified by the parameters
+@var{hostp}, @var{userp}, and @var{domainp} is part of the netgroup
+@var{netgroup}.  Using this function has the advantage that
+
+@enumerate
+@item
+no other netgroup function can use the global netgroup state since
+internal locking is used and
+@item
+the function is implemented more efficiently than successive calls
+to the other @code{set}/@code{get}/@code{endnetgrent} functions.
+@end enumerate
+
+Any of the pointers @var{hostp}, @var{userp}, and @var{domainp} can be
+@code{NULL} which means any value is excepted in this position.  This is
+also true for the name @code{-} which should not match any other string
+otherwise.
+
+The return value is @code{1} if an entry matching the given triple is
+found in the netgroup.  The return value is @code{0} is the netgroup
+itself is not found, the netgroup does not contain the triple or
+internal errors occured.
 @end deftypefun
 
-@node Database Example
+@node Database Example,  , Netgroup Database, Users and Groups
 @section User and Group Database Example
 
 Here is an example program showing the use of the system database inquiry