From f948a874e78ef8d9dcfbbff85255cd546fb56a26 Mon Sep 17 00:00:00 2001
From: lukem <lukem@NetBSD.org>
Date: Tue, 19 Apr 2005 04:26:16 +0000
Subject: [PATCH] Clarify getpw*_r() return value when entry isn't found.
 Improve markup of various constants.

---
 lib/libc/gen/getpwent.3 | 27 +++++++++++++++++++--------
 1 file changed, 19 insertions(+), 8 deletions(-)

diff --git a/lib/libc/gen/getpwent.3 b/lib/libc/gen/getpwent.3
index 2d2d89d62cc9..9a6855e4d1fe 100644
--- a/lib/libc/gen/getpwent.3
+++ b/lib/libc/gen/getpwent.3
@@ -1,4 +1,4 @@
-.\"	$NetBSD: getpwent.3,v 1.30 2005/04/04 18:26:19 wiz Exp $
+.\"	$NetBSD: getpwent.3,v 1.31 2005/04/19 04:26:16 lukem 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 @@ act like their non re-entrant counterparts, updating the contents of
 .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 @@ is allocated from
 which is
 .Ar buflen
 bytes in size.
-If an error occurs,
-an error number will be returned and
+If the requested entry cannot be found,
 .Ar result
-will point to null.
+will point to
+.Dv NULL
+and
+.Dv 0
+will be returned.
+If an error occurs,
+a non-zero error number will be returned and
+.Ar result
+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 @@ The functions
 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 @@ and
 .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