getgroups

Section: System Calls (2)
Updated: 2026-02-08
Index JM Home Page roff page
 

名前

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

ライブラリ

標準 C ライブラリ (libc,~-lc)  

書式

#include <unistd.h>

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

#include <grp.h>

int setgroups(size_t size, const gid_t list[size]);

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, (gid_t [0]){});
 

返り値

On success, getgroups() returns the number of supplementary group IDs. On error, -1 is returned, and errno is set to indicate the error.

On success, setgroups() returns 0. On error, -1 is returned, and errno is set to indicate the error.  

エラー

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

バージョン

 

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

標準規格

getgroups()
POSIX.1-2024.
setgroups()
なし。
 

歴史

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

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

注意

プロセスは、実効グループ 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 経由で公開されている。  

例

#include <err.h>
#include <stddef.h>
#include <stdint.h>
#include <stdio.h>
#include <stdlib.h>
#include <sys/types.h>
#include <unistd.h>

#define MALLOC(n, T)  ((T *) reallocarray(NULL, n, sizeof(T)))

static gid_t *agetgroups(size_t *ngids);

int
main(void)
{
    gid_t   *gids;
    size_t  n;

    gids = agetgroups(&n);
    if (gids == NULL)
        err(EXIT_FAILURE, "agetgroups");

    if (n != 0) {
        printf("%jd", (intmax_t) gids[0]);
        for (size_t i = 1; i < n; i++)
            printf(" %jd", (intmax_t) gids[i]);
    }
    puts("");

    free(gids);
    exit(EXIT_SUCCESS);
}

static gid_t *
agetgroups(size_t *ngids)
{
    int    n;
    gid_t  *gids;

    n = getgroups(0, NULL);
    if (n == -1)
        return NULL;

    gids = MALLOC(n, gid_t);
    if (gids == NULL)
        return NULL;

    n = getgroups(n, gids);
    if (n == -1) {
        free(gids);
        return NULL;
    }

    *ngids = n;
    return gids;
}
 

関連項目

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


 

Index

名前
ライブラリ
書式
説明
返り値
エラー
バージョン
C ライブラリとカーネルの違い
標準規格
歴史
注意
例
関連項目

This document was created by man2html, using the manual pages.