From owner-freebsd-standards@FreeBSD.ORG Sun Jan 27 16:00:04 2008 Return-Path: Delivered-To: freebsd-standards@hub.freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2001:4f8:fff6::34]) by hub.freebsd.org (Postfix) with ESMTP id BDE6016A418 for ; Sun, 27 Jan 2008 16:00:04 +0000 (UTC) (envelope-from gnats@FreeBSD.org) Received: from freefall.freebsd.org (freefall.freebsd.org [IPv6:2001:4f8:fff6::28]) by mx1.freebsd.org (Postfix) with ESMTP id AD0F913C45A for ; Sun, 27 Jan 2008 16:00:04 +0000 (UTC) (envelope-from gnats@FreeBSD.org) Received: from freefall.freebsd.org (gnats@localhost [127.0.0.1]) by freefall.freebsd.org (8.14.2/8.14.2) with ESMTP id m0RG04WE014721 for ; Sun, 27 Jan 2008 16:00:04 GMT (envelope-from gnats@freefall.freebsd.org) Received: (from gnats@localhost) by freefall.freebsd.org (8.14.2/8.14.1/Submit) id m0RG04Gt014720; Sun, 27 Jan 2008 16:00:04 GMT (envelope-from gnats) Date: Sun, 27 Jan 2008 16:00:04 GMT Message-Id: <200801271600.m0RG04Gt014720@freefall.freebsd.org> To: freebsd-standards@FreeBSD.org From: Bruce Evans Cc: Subject: Re: docs/26003: getgroups(2) lists NGROUPS_MAX but not syslimits.h X-BeenThere: freebsd-standards@freebsd.org X-Mailman-Version: 2.1.5 Precedence: list Reply-To: Bruce Evans List-Id: Standards compliance List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Sun, 27 Jan 2008 16:00:04 -0000 The following reply was made to PR docs/26003; it has been noted by GNATS. From: Bruce Evans To: rwatson@freebsd.org Cc: freebsd-standards@freebsd.org Subject: Re: docs/26003: getgroups(2) lists NGROUPS_MAX but not syslimits.h Date: Mon, 28 Jan 2008 02:10:50 +1100 (EST) On Sun, 27 Jan 2008 rwatson@freebsd.org wrote: > Synopsis: getgroups(2) lists NGROUPS_MAX but not syslimits.h > It seems like we understand the problem, but still no conclusion on the > exact fix--perhaps unistd.h needs to find NGROUPS_MAX somehow without > polluting the namespace too much more? Of course not. There are only man page bugs. There is a good interface for determining the size of the array needed, and it doesn't involve {NGROUPS_MAX} -- just call getgroups() with gidsetlen == 0 to determine the size. Synopses shouldn't mention includes that are only needed for some uses of interfaces, especially here since the use is a bad one (to be unportable by hard-coding NGROUPS_MAX). The includes are already sufficient for using {NGROUPS_MAX} in its portable form sysconf(_SC_NGROUPS_MAX), except you will also need malloc(). for using malloc() is another include that doesn't belong in the synopsis. If you want better wording for {NGROUPS_MAX} in this man page, see POSIX. POSIX.1-2001-draft7 actually doesn't do much more than say {NGROUPS_MAX}+1 where FreeBSD says NGROUPS_MAX. The {FOO} markup is documented elsewhere. It is very useful for avoiding repeating the documentation of the messes required for using limits. It is barely used in FreeBSD (FreeBSD tends to document only unportabilities like hard-coding NAME_MAX and PATH_MAX). The +1 is because the euid may be returned in the list. FreeBSD apparently doesn't do this, and its man page doesn't say that it might be needed. POSIX gives an example of using sysconf(_SC_NGROUPS_MAX) will no error checking for sysconf() or malloc(). POSIX's rationale for getgroups() notes that {NGROUPS_MAX} might not be constant. Bruce