[src/trunk]: src/lib/libc/gen Expand description of return value.

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

details:   https://anonhg.NetBSD.org/src/rev/bd8f3f6ec2bb
branches:  trunk
changeset: 570198:bd8f3f6ec2bb
user:      lukem <lukem%NetBSD.org@localhost>
date:      Tue Sep 28 10:49:22 2004 +0000

description:
Expand description of return value.
Remove bug about incorrect sizing calculation; it seems to DTRT for me.
Also reference group(5).

diffstat:

 lib/libc/gen/getgrouplist.3 |  22 ++++++++++------------
 1 files changed, 10 insertions(+), 12 deletions(-)

diffs (56 lines):

diff -r 74a8343a5488 -r bd8f3f6ec2bb lib/libc/gen/getgrouplist.3
--- a/lib/libc/gen/getgrouplist.3       Tue Sep 28 10:46:19 2004 +0000
+++ b/lib/libc/gen/getgrouplist.3       Tue Sep 28 10:49:22 2004 +0000
@@ -1,4 +1,4 @@
-.\"    $NetBSD: getgrouplist.3,v 1.10 2003/08/07 16:42:49 agc Exp $
+.\"    $NetBSD: getgrouplist.3,v 1.11 2004/09/28 10:49:22 lukem Exp $
 .\"
 .\" Copyright (c) 1991, 1993
 .\"    The Regents of the University of California.  All rights reserved.
@@ -29,7 +29,7 @@
 .\"
 .\"     @(#)getgrouplist.3     8.1 (Berkeley) 6/9/93
 .\"
-.Dd April 25, 1999
+.Dd September 28, 2004
 .Dt GETGROUPLIST 3
 .Os
 .Sh NAME
@@ -67,9 +67,14 @@
 The
 .Fn getgrouplist
 function
+returns 0 if successful, and 
 returns \-1 if the size of the group list is too small to
 hold all the user's groups.
-Here, the group array will be filled with as many groups as will fit.
+In the latter case, the
+.Fa groups
+array will be filled with as many groups as will fit and
+.Fa ngroups
+will contain the total number of groups found.
 .Sh FILES
 .Bl -tag -width /etc/group -compact
 .It Pa /etc/group
@@ -77,7 +82,8 @@
 .El
 .Sh SEE ALSO
 .Xr setgroups 2 ,
-.Xr initgroups 3
+.Xr initgroups 3 ,
+.Xr group 5 .
 .Sh HISTORY
 The
 .Fn getgrouplist
@@ -93,11 +99,3 @@
 the group structure will
 be overwritten in the call to
 .Fn getgrouplist .
-.Pp
-In the case where the group array is too small and duplicate gids
-have been suppressed, the returned
-.Fa ngroups
-will be too large by a factor of the difference between the given
-size and the number of matches.
-This is not considered to be a major problem, since it's still going
-to be a smaller figure than when duplicates were not suppressed.