[illumos-gate merge]

commit f2c438c5058c64b7373448f239156bf60009abcb
    7024 Add getgrouplist() to illumos
commit adc528899caad05412c9b8d397e277900adf786b
    13207 Creating an aggr with more than 128 Tx or Rx rings panics

2 files changed, 209 insertions, 1 deletions

diff --git a/usr/src/man/man3c/Makefile b/usr/src/man/man3c/Makefile
index ea7b4d4834..e9f8f2cafd 100644
--- a/usr/src/man/man3c/Makefile
+++ b/usr/src/man/man3c/Makefile
@@ -14,7 +14,7 @@
 # Copyright 2018 Nexenta Systems, Inc.
 # Copyright 2013, OmniTI Computer Consulting, Inc. All rights reserved.
 # Copyright 2014 Garrett D'Amore <garrett@damore.org>
-# Copyright 2018 Joyent, Inc.
+# Copyright 2020 Joyent, Inc.
 # Copyright 2018 Jason King
 # Copyright 2019 OmniOS Community Edition (OmniOSce) Association.
 #
@@ -172,6 +172,7 @@ MANFILES=	__fbufsize.3c					\
 		getenv.3c					\
 		getexecname.3c					\
 		getgrnam.3c					\
+		getgrouplist.3c					\
 		gethostid.3c					\
 		gethostname.3c					\
 		gethrtime.3c					\
diff --git a/usr/src/man/man3c/getgrouplist.3c b/usr/src/man/man3c/getgrouplist.3c
new file mode 100644
index 0000000000..f1e10695e3
--- /dev/null
+++ b/usr/src/man/man3c/getgrouplist.3c
@@ -0,0 +1,207 @@
+.\"
+.\" This file and its contents are supplied under the terms of the
+.\" Common Development and Distribution License ("CDDL"), version 1.0.
+.\" You may only use this file in accordance with the terms of version
+.\" 1.0 of the CDDL.
+.\"
+.\" A full copy of the text of the CDDL should have accompanied this
+.\" source.  A copy of the CDDL is also available via the Internet at
+.\" http://www.illumos.org/license/CDDL.
+.\"
+.\"
+.\" Copyright 2020 Joyent, Inc.
+.\"
+.Dd November 22, 2020
+.Dt GETGROUPLIST 3C
+.Os
+.Sh NAME
+.Nm getgrouplist
+.Nd calculate group access list
+.Sh SYNOPSIS
+.In grp.h
+.Ft int
+.Fo getgrouplist
+.Fa "const char *user"
+.Fa "gid_t agroup"
+.Fa "gid_t *groups"
+.Fa "int *ngroups"
+.Fc
+.Sh DESCRIPTION
+The
+.Fn getgrouplist
+function queries the group database to obtain the list of groups that
+.Fa user
+belongs to.
+The
+.Fa agroup
+group is always added to the resulting group list.
+This value is typically the primary gid of the user from the
+.Sy passwd
+database.
+.Pp
+When calling
+.Fn getgrouplist ,
+the caller should set the maximum number of groups that
+.Fa groups
+can hold in
+.Fa *ngroups .
+The value of
+.Dv NGROUPS_MAX
+can be used to size
+.Fa groups
+to ensure it can hold any number of groups supported by the system.
+.Pp
+Upon return,
+.Fn getgrouplist
+stores the list of groups that
+.Fa user
+belongs to in
+.Fa groups
+and stores the number of groups
+.Fa user
+belongs to in
+.Fa *ngroups
+.Po
+this may be a smaller than the value passed in when
+calling
+.Fn getgrouplist
+.Pc .
+If
+.Fa groups
+is too small to hold all of the groups
+.Fa user
+belongs to,
+.Fn getgrouplist
+fails and sets
+.Fa *ngroups
+to a value large enough to hold the full result.
+.Sh RETURN VALUES
+On success,
+.Fn getgrouplist
+returns the number of groups
+.Fa user
+belongs to, fills in
+.Fa groups
+with the gids of the groups
+.Fa user
+belongs to, and also sets
+.Fa *ngroups
+to the number of groups
+.Fa user
+belongs to.
+.Pp
+On failure,
+.Fn getgrouplist
+returns -1 and
+.Va errno
+is set.
+.Pp
+The behavior of
+.Fn getgrouplist
+is undefined if the total number of groups a user belongs to exceeds
+.Dv NGROUPS_MAX .
+.Pp
+Note that on
+.Fx ,
+.Fn getgrouplist
+always returns -1 on failure or 0 on success.
+A caller must rely on the value set in
+.Fa *ngroups
+upon return to determine the number of entries in
+.Fa groups .
+.Pp
+On Linux, both glibc and musl return the number of groups
+.Fa user
+belongs to on success and returns -1 on failure.
+.Pp
+None of these other implementations document any
+.Va errno
+values on failure, however their implementations show that
+.Va errno
+may be set on failure.
+Software using
+.Fn getgrouplist
+should be aware of these differences when attemping to write portable
+software.
+.Sh EXAMPLES
+.Sy Example 1
+Print all the groups for a user.
+.Bd -literal
+#include <pwd.h>
+#include <grp.h>
+#include <stdlib.h>
+#include <stdio.h>
+#include <limits.h>
+#include <err.h>
+
+void
+printgroups(const char *user)
+{
+    struct passwd *pw;
+    gid_t *groups;
+    int ngroups, ret;
+
+    if ((groups = calloc(NGROUPS_MAX, sizeof (gid_t))) == NULL)
+        err(EXIT_FAILURE, "calloc");
+
+    if ((pw = getpwnam(user)) == NULL)
+        err(EXIT_FAILURE, "getpwname");
+
+    ngroups = NGROUPS_MAX;
+    ret = getgrouplist(user, pw->pw_gid, groups, &ngroups);
+    if (ret < 0)
+        err(EXIT_FAILURE, "getgrouplist");
+
+    for (int i = 0; i < ret; i++) {
+        struct group *gr = getgrgid(groups[i]);
+
+        (void) printf("%s ", gr->gr_name);
+    }
+    (void) fputc('\\n', stdout);
+
+    free(groups);
+}
+.Ed
+.Sh ERRORS
+On failure,
+.Fn getgrouplist
+returns -1, and will set errno to one one of the following values:
+.Bl -tag -width Dv
+.It Er ENOMEM
+Not enough memory to complete the request.
+.It Er EINVAL
+One of the parameters is invalid
+.Po
+for example,
+.Fa ngroups
+is
+.Dv NULL
+.Pc .
+.It Dv ERANGE
+The supplied value of
+.Fa *ngroups
+is too small to hold the results.
+.Fa *ngroups
+is set
+.Po
+upon return
+.Pc
+to a value large enough to hold the results, and a partial set of
+results is written to
+.Fa groups .
+The value written to
+.Fa *ngroups
+may be larger than the value returned by a successful call to
+.Fn getgrouplist .
+.El
+.Sh INTERFACE STABILITY
+.Sy Uncommitted
+.Sh MT-LEVEL
+.Sy MT-Safe
+.Sh SEE ALSO
+.Xr groups 1 ,
+.Xr getuid 2 ,
+.Xr getgrnam 3C ,
+.Xr getgroups 3C ,
+.Xr initgroups 3C ,
+.Xr limits.h 3HEAD