名前

       getgroups, setgroups - 補助グループ ID のリストを取得/設定する

書式

       #include <sys/types.h>
       #include <unistd.h>

       int getgroups(int size, gid_t list[]);

       #include <grp.h>

       int setgroups(size_t size, const gid_t *list);

   glibc 向けの機能検査マクロの要件 (feature_test_macros(7)  参照):

       setgroups():
           Since glibc 2.19:
               _DEFAULT_SOURCE
           Glibc 2.19 and earlier:
               _BSD_SOURCE

説明

       getgroups()  は呼び出し元プロセスの補助グループ (supplementary group) ID を list に返す。 size 引数には、
       list  により参照されるバッファーに格納できる要素の最大数を設定すべきである。 呼び出し元プロセスが size 個
       より多くの補助グループのメンバの場合には、エラーとなる。

       この関数を呼び出したプロセスの実効グループ ID が、 返されるリストに含まれるかどうかは規定されていない (し
       たがって、アプリケーションは getegid(2) を呼び出し、その結果の値を追加・削除すべきである)。

       size が 0 ならば、 list は修正されないが、そのプロセスの補助グループ ID の合計数が返される。 これを使うこ
       とで、それ以降の getgroups()  の呼び出しで必要となる動的割り当てバッファー list  のサイズを、呼び出し元が
       決定することができる。

       setgroups()   sets  the  supplementary  group  IDs  for  the calling process.  Appropriate privileges are
       required (see the description of the EPERM error, below).  The size  argument  specifies  the  number  of
       supplementary  group  IDs  in the buffer pointed to by list.  A process can drop all of its supplementary
       groups with the call:

           setgroups(0, NULL);

返り値

       getgroups()  は、成功すると補助グループ ID の数を返す。 エラーの場合 -1 を返し、 errno を適切に設定する。

       setgroups()  は、成功すると 0 を返す。 エラーの場合 -1 を返し、 errno を適切に設定する。

エラー

       EFAULT list が不正なアドレスである。

       getgroups()  は、上記に加えて以下のエラーで失敗する可能性がある。

       EINVAL size が補助グループ ID の数より小さいが 0 でない。

       setgroups()  は、上記に加えて以下のエラーで失敗する可能性がある。

       EINVAL size が NGROUPS_MAX より大きい (NGROUPS_MAX は Linux 2.6.4  より前では  32、Linux  2.6.4  以降では
              65536)。

       ENOMEM メモリー不足。

       EPERM  The calling process has insufficient privilege (the caller does not have the CAP_SETGID capability
              in the user namespace in which it resides).

       EPERM (Linux 3.19 以降)
              The   use   of   setgroups()    is  denied  in  this  user  namespace.   See  the  description  of
              /proc/[pid]/setgroups in user_namespaces(7).

準拠

       getgroups(): SVr4, 4.3BSD, POSIX.1-2001, POSIX.1-2008.

       setgroups(): SVr4, 4.3BSD.  Since setgroups()  requires privilege, it is not covered by POSIX.1.

注意

       プロセスは、実効グループ ID に加え、最大  NGROUPS_MAX  までの補助グループ  ID  を持つことができる。  定数
       NGROUPS_MAX  は  <limits.h> で定義されている。 補助グループ ID の集合は親プロセスから継承され、 execve(2)
       の前後で保持される。

       補助グループ ID の最大数は、実行時に sysconf(3)  を使って以下のようにして調べることができる:

           long ngroups_max;
           ngroups_max = sysconf(_SC_NGROUPS_MAX);

       getgroups() の返り値の最大値は、この値より大きくなることはない。 Linux 2.6.4 以降では、補助グループ ID の
       最大数も Linux 固有の読み込み専用のファイル /proc/sys/kernel/ngroups_max 経由で公開されている。

       元々の Linux の getgroups() システムコールは 16 ビットのグループ  ID  だけ  に対応していた。その後、Linux
       2.4  で、32  ビットの ID に対応した getgroups() が追加された。glibc の getgroups のラッパー関数はカーネル
       バージョンによるこの違いを吸収している。

   C ライブラリとカーネルの違い
       At the kernel level, user IDs and group IDs are a per-thread attribute.  However, POSIX requires that all
       threads in a process share the same credentials.  The NPTL threading  implementation  handles  the  POSIX
       requirements  by  providing  wrapper  functions for the various system calls that change process UIDs and
       GIDs.  These wrapper functions (including the one for setgroups())  employ a  signal-based  technique  to
       ensure  that  when  one  thread  changes credentials, all of the other threads in the process also change
       their credentials.  For details, see nptl(7).

関連項目

       getgid(2), setgid(2), getgrouplist(3), group_member(3), initgroups(3), capabilities(7), credentials(7)

この文書について

       この man ページは Linux man-pages プロジェクトのリリース 5.10  の一部である。プロジェクトの説明とバグ報告
       に関する情報は https://www.kernel.org/doc/man-pages/ に書かれている。

Linux                                              2019-03-06                                       GETGROUPS(2)