[src/trunk]: src/lib/libc/gen Describe get{pw, gr}ent_r. XXX: Are they in any ...

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

details:   https://anonhg.NetBSD.org/src/rev/45a2e6b8fa4c
branches:  trunk
changeset: 580002:45a2e6b8fa4c
user:      christos <christos%NetBSD.org@localhost>
date:      Mon Apr 04 14:19:55 2005 +0000

description:
Describe get{pw,gr}ent_r. XXX: Are they in any standards?

diffstat:

 lib/libc/gen/getgrent.3 |  50 +++++++++++++++++++++++++++++-------------------
 lib/libc/gen/getpwent.3 |  48 +++++++++++++++++++++++++++++-----------------
 2 files changed, 60 insertions(+), 38 deletions(-)

diffs (205 lines):

diff -r eb487644418e -r 45a2e6b8fa4c lib/libc/gen/getgrent.3
--- a/lib/libc/gen/getgrent.3   Mon Apr 04 13:34:40 2005 +0000
+++ b/lib/libc/gen/getgrent.3   Mon Apr 04 14:19:55 2005 +0000
@@ -1,4 +1,4 @@
-.\"    $NetBSD: getgrent.3,v 1.22 2004/10/05 03:03:24 lukem Exp $
+.\"    $NetBSD: getgrent.3,v 1.23 2005/04/04 14:19:55 christos 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
diff -r eb487644418e -r 45a2e6b8fa4c lib/libc/gen/getpwent.3
--- a/lib/libc/gen/getpwent.3   Mon Apr 04 13:34:40 2005 +0000
+++ b/lib/libc/gen/getpwent.3   Mon Apr 04 14:19:55 2005 +0000
@@ -1,4 +1,4 @@
-.\"    $NetBSD: getpwent.3,v 1.27 2005/03/31 11:44:26 wiz Exp $
+.\"    $NetBSD: getpwent.3,v 1.28 2005/04/04 14:19:55 christos Exp $
 .\"
 .\" Copyright (c) 1988, 1991, 1993
 .\"    The Regents of the University of California.  All rights reserved.
@@ -29,11 +29,12 @@
 .\"
 .\"     @(#)getpwent.3 8.2 (Berkeley) 12/11/93
 .\"
-.Dd March 30, 2005
+.Dd April 4, 2005
 .Dt GETPWENT 3
 .Os
 .Sh NAME
 .Nm getpwent ,
+.Nm getpwent_r ,
 .Nm getpwnam ,
 .Nm getpwnam_r ,
 .Nm getpwuid ,
@@ -48,6 +49,13 @@
 .In pwd.h
 .Ft struct passwd *
 .Fn getpwent void
+.Ft int
+.Fo getpwent_r
+.Fa "struct passwd *pw"
+.Fa "char *buffer"
+.Fa "size_t buflen"
+.Fa "struct passwd **result"
+.Fc
 .Ft struct passwd *
 .Fn getpwnam "const char *name"
 .Ft int
@@ -104,19 +112,25 @@
 .Fn getpwnam
 and
 .Fn getpwuid
-search the password database for the given user name or user id,
+search the password database for the given user name pointed to by
+.Ar name
+or user id pointed to by
+.Ar uid
 respectively, always returning the first one encountered.
 Identical user names or user ids may result in undefined behavior.
 .Pp
+The
+.Fn getpwent
+function
+sequentially reads the password database and is intended for programs
+that wish to process the complete list of users.
+.Pp
 The functions
-.Fn getpwnam_r
+.Fn getpwnam_r ,
+.Fn getpwuid_r ,
 and
-.Fn getpwuid_r
-search the password database for the given user name pointed to by
-.Ar name
-or the user id pointed to by
-.Ar uid ,
-respectively, updating the contents of
+.Fn getpwent_r
+act like their non re-entrant counterparts, updating the contents of
 .Ar pw
 and storing a pointer to that in
 .Ar result ,
@@ -132,13 +146,10 @@
 an error number will be returned and
 .Ar result
 will point to null.
-Identical user names or user ids may result in undefined behavior.
-.Pp
-The
-.Fn getpwent
-function
-sequentially reads the password database and is intended for programs
-that wish to process the complete list of users.
+Calling
+.Fn getpwent_r
+from multiple threads, will result in each thread reading a disjoint portion
+of the password database.
 .Pp
 The
 .Fn setpassent
@@ -196,8 +207,9 @@
 have no return value.
 The functions
 .Fn getpwnam_r ,
+.Fn getpwuid_r ,
 and
-.Fn getpwuid_r
+.Fn getpwent_r
 return
 .Dv 0
 on success and non-zero on failure.