The getgrouplist() function shall fill in the array groups with the supplementary groups for the user specified by user. On entry, ngroups shall refer to an integer containing the maximum number of elements in the groups array. The group group shall also be included in the values returned in groups. It is expected that group would be specified as the user's primary group from the password file (obtainable via getpwnam() or a similar function).
If on entry the value referenced by ngroups was greater than or equal to the number of supplementary group identifiers to be copied to the array identified by groups, getgrouplist() shall return the number of group identifiers actually copied, and shall set the value referenced by ngroups to this value.
If on entry the value referenced by ngroups
was less than the number of supplementary
group identifiers, getgrouplist() shall return
-1. The initial ngroups
entries in groups shall be overwritten.
If the number of groups exceeds the input
ngroups value, then as well as returning
-1, ngroups shall be set
to the number of groups that would have been placed in
groups if it had been large enough.
Note: In such a case, the caller can use the information returned to make a further getgrouplist() call with a correctly sized groups array.
If user does not refer to a valid user on the system, then the behavior of this function is undefined.