[src/netbsd-3]: src/lib/libc/gen Pull up revision 1.23 (requested by lukem in...

[tron <tron%NetBSD.org@localhost>]

details:   https://anonhg.NetBSD.org/src/rev/8e119e5c482e
branches:  netbsd-3
changeset: 576574:8e119e5c482e
user:      tron <tron%NetBSD.org@localhost>
date:      Mon Jul 11 21:22:58 2005 +0000

description:
Pull up revision 1.23 (requested by lukem in ticket #540):
Describe get{pw,gr}ent_r. XXX: Are they in any standards?

diffstat:

 lib/libc/gen/getgrent.3 |  50 +++++++++++++++++++++++++++++-------------------
 1 files changed, 30 insertions(+), 20 deletions(-)

diffs (105 lines):

diff -r 4afa87e67b18 -r 8e119e5c482e lib/libc/gen/getgrent.3
--- a/lib/libc/gen/getgrent.3   Mon Jul 11 21:22:39 2005 +0000
+++ b/lib/libc/gen/getgrent.3   Mon Jul 11 21:22:58 2005 +0000
@@ -1,4 +1,4 @@
-.\"    $NetBSD: getgrent.3,v 1.22.2.1 2005/05/28 13:42:45 tron Exp $
+.\"    $NetBSD: getgrent.3,v 1.22.2.2 2005/07/11 21:22:58 tron Exp $
 .\"
 .\" Copyright (c) 1989, 1991, 1993
 .\"    The Regents of the University of California.  All rights reserved.
@@ -29,11 +29,12 @@
 .\"
 .\"     @(#)getgrent.3 8.2 (Berkeley) 4/19/94
 .\"
-.Dd October 5, 2004
+.Dd April 4, 2005
 .Dt GETGRENT 3
 .Os
 .Sh NAME
 .Nm getgrent ,
+.Nm getgrent_r ,
 .Nm getgrgid ,
 .Nm getgrgid_r ,
 .Nm getgrnam ,
@@ -49,6 +50,13 @@
 .In grp.h
 .Ft struct group *
 .Fn getgrent void
+.Ft int
+.Fo getgrent_r
+.Fa "struct group *grp"
+.Fa "char *buffer"
+.Fa "size_t buflen"
+.Fa "struct group **result"
+.Fc
 .Ft struct group *
 .Fn getgrgid "gid_t gid"
 .Ft int
@@ -105,14 +113,19 @@
 respectively, returning the first one encountered.
 Identical group names or group ids may result in undefined behavior.
 .Pp
+The
+.Fn getgrent
+function sequentially reads the group database and is intended for programs
+that wish to step through the complete list of groups.
+.Pp
+All three functions will open the group file for reading, if necessary.
+.Pp
 The functions
-.Fn getgrnam_r
+.Fn getgrnam_r ,
+.Fn getgrgid_r ,
 and
-.Fn getgrgid_r
-search the group database for the given group name pointed to by
-.Ar name
-or the group id pointed to by
-.Ar gid ,
+.Fn getgrent_r
+act like their non re-entrant counterparts
 respectively, updating the contents of
 .Ar grp
 and storing a pointer to that in
@@ -129,14 +142,10 @@
 an error number will be returned and
 .Ar result
 will point to null.
-Identical group names or group ids may result in undefined behavior.
-.Pp
-The
-.Fn getgrent
-function sequentially reads the group database and is intended for programs
-that wish to step through the complete list of groups.
-.Pp
-All three functions will open the group file for reading, if necessary.
+Calling
+.Fn getgrent_r
+from multiple threads, will result in each thread reading a disjoint portion
+of the group database.
 .Pp
 The
 .Fn setgroupent
@@ -162,17 +171,18 @@
 function closes any open files.
 .Sh RETURN VALUES
 The functions
-.Fn getgrent ,
 .Fn getgrgid ,
+.Fn getgrnam ,
 and
-.Fn getgrnam ,
+.Fn getgrent
 return a pointer to the group entry if successful; if end-of-file
 is reached or an error occurs a null pointer is returned.
 .Pp
 The functions
-.Fn getgrgid_r
+.Fn getgrgid_r ,
+.Fn getgrnam_r ,
 and
-.Fn getgrnam_r
+.Fn getgrent_r
 return 0 if sucessful and update
 .Ar result
 to point to