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

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

details:   https://anonhg.NetBSD.org/src/rev/09ad6e4821fe
branches:  netbsd-3
changeset: 576581:09ad6e4821fe
user:      tron <tron%NetBSD.org@localhost>
date:      Mon Jul 11 21:26:17 2005 +0000

description:
Pull up revision 1.31 (requested by lukem in ticket #540):
Clarify getpw*_r() return value when entry isn't found.
Improve markup of various constants.

diffstat:

 lib/libc/gen/getpwent.3 |  25 ++++++++++++++++++-------
 1 files changed, 18 insertions(+), 7 deletions(-)

diffs (69 lines):

diff -r dac3aadaf0ae -r 09ad6e4821fe lib/libc/gen/getpwent.3
--- a/lib/libc/gen/getpwent.3   Mon Jul 11 21:25:27 2005 +0000
+++ b/lib/libc/gen/getpwent.3   Mon Jul 11 21:26:17 2005 +0000
@@ -1,4 +1,4 @@
-.\"    $NetBSD: getpwent.3,v 1.25.2.6 2005/07/11 21:24:19 tron Exp $
+.\"    $NetBSD: getpwent.3,v 1.25.2.7 2005/07/11 21:26:17 tron Exp $
 .\"
 .\" Copyright (c) 1988, 1991, 1993
 .\"    The Regents of the University of California.  All rights reserved.
@@ -29,7 +29,7 @@
 .\"
 .\"     @(#)getpwent.3 8.2 (Berkeley) 12/11/93
 .\"
-.Dd April 4, 2005
+.Dd April 19, 2005
 .Dt GETPWENT 3
 .Os
 .Sh NAME
@@ -134,7 +134,8 @@
 .Ar pw
 and storing a pointer to that in
 .Ar result ,
-and returning 0.
+and returning
+.Dv 0 .
 Storage used by
 .Ar pw
 is allocated from
@@ -142,10 +143,18 @@
 which is
 .Ar buflen
 bytes in size.
+If the requested entry cannot be found,
+.Ar result
+will point to
+.Dv NULL
+and
+.Dv 0
+will be returned.
 If an error occurs,
-an error number will be returned and
+a non-zero error number will be returned and
 .Ar result
-will point to null.
+will point to
+.Dv NULL .
 Calling
 .Fn getpwent_r
 from multiple threads will result in each thread reading a disjoint portion
@@ -199,7 +208,9 @@
 and
 .Fn getpwuid ,
 return a valid pointer to a passwd structure on success
-and a null pointer if end-of-file is reached or an error occurs.
+and a
+.Dv NULL .
+pointer if the entry was not found or an error occurs.
 The
 .Fn setpassent
 function returns 0 on failure and 1 on success.
@@ -216,7 +227,7 @@
 .Fn getpwent_r
 return
 .Dv 0
-on success and non-zero on failure.
+on success or entry not found and non-zero on failure.
 .Sh FILES
 .Bl -tag -width /etc/master.passwd -compact
 .It Pa /etc/pwd.db