名前

       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/ に書かれている。