docs/26003: getgroups(2) lists NGROUPS_MAX but not syslimits.h

[Bruce Evans]

On Sun, 27 Jan 2008 rwatson at 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().  <stdlib.h>
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