From owner-freebsd-standards@FreeBSD.ORG Mon Jan 28 02:02:19 2008 Return-Path: Delivered-To: freebsd-standards@freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2001:4f8:fff6::34]) by hub.freebsd.org (Postfix) with ESMTP id BDBAD16A41A for ; Mon, 28 Jan 2008 02:02:19 +0000 (UTC) (envelope-from brde@optusnet.com.au) Received: from fallbackmx10.syd.optusnet.com.au (fallbackmx10.syd.optusnet.com.au [211.29.132.251]) by mx1.freebsd.org (Postfix) with ESMTP id 46A7713C4E1 for ; Mon, 28 Jan 2008 02:02:18 +0000 (UTC) (envelope-from brde@optusnet.com.au) Received: from mail35.syd.optusnet.com.au (mail35.syd.optusnet.com.au [211.29.133.51]) by fallbackmx10.syd.optusnet.com.au (8.13.1/8.13.1) with ESMTP id m0RFMU67030301 for ; Mon, 28 Jan 2008 02:22:30 +1100 Received: from besplex.bde.org (c211-30-219-213.carlnfd3.nsw.optusnet.com.au [211.30.219.213]) by mail35.syd.optusnet.com.au (8.13.1/8.13.1) with ESMTP id m0RFMOZ8028027 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=NO); Mon, 28 Jan 2008 02:22:26 +1100 Date: Mon, 28 Jan 2008 02:10:50 +1100 (EST) From: Bruce Evans X-X-Sender: bde@besplex.bde.org To: rwatson@freebsd.org In-Reply-To: <200801271104.m0RB4Dfc089466@freefall.freebsd.org> Message-ID: <20080128012436.W652@besplex.bde.org> References: <200801271104.m0RB4Dfc089466@freefall.freebsd.org> MIME-Version: 1.0 Content-Type: TEXT/PLAIN; charset=US-ASCII; format=flowed Cc: freebsd-standards@freebsd.org 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 List-Id: Standards compliance List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Mon, 28 Jan 2008 02:02:19 -0000 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