GETGROUPS

Section: Linux Programmer's Manual (2)
Updated: 2019-03-06
Index JM Home Page

名前

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).

この文書について

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

Linux マニュアル一覧

[man1] [man2] [man3] [man4] [man5] [man6] [man7] [man8]
[a] [b] [c] [d] [e] [f] [g] [h] [i] [j] [k] [l] [m] [n] [o] [p] [q] [r] [s] [t] [u] [v] [w] [x] [y] [z]