aboutsummaryrefslogtreecommitdiff
path: root/manual/users.texi
diff options
context:
space:
mode:
authorUlrich Drepper <drepper@redhat.com>1996-10-31 02:57:12 +0000
committerUlrich Drepper <drepper@redhat.com>1996-10-31 02:57:12 +0000
commitba1ffaa1c6989873b57edc84491bfd1308b2190d (patch)
tree77274c1136f21a58e60397fdd62ad03846bc5888 /manual/users.texi
parentf0f4432f46882d22f61a89f4130a697313f53901 (diff)
downloadglibc-ba1ffaa1c6989873b57edc84491bfd1308b2190d.tar
glibc-ba1ffaa1c6989873b57edc84491bfd1308b2190d.tar.gz
glibc-ba1ffaa1c6989873b57edc84491bfd1308b2190d.tar.bz2
glibc-ba1ffaa1c6989873b57edc84491bfd1308b2190d.zip
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.
Diffstat (limited to 'manual/users.texi')
-rw-r--r--manual/users.texi360
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