名前

       capget, capset - スレッドのケーパビリティを設定/取得する

書式

       #include <sys/capability.h>

       int capget(cap_user_header_t hdrp, cap_user_data_t datap);

       int capset(cap_user_header_t hdrp, const cap_user_data_t datap);

説明

       この二つのシステムコールはスレッドのケーパビリティを取得したり設定したりするための    生の
       カーネルインターフェースである。 これらのシステムコールは  Linux  特有であるというだけでな
       く、    カーネル    API    は変更されるかもしれず、これらのシステムコールの使用法    (特に
       cap_user_*_t 型という書式) はカーネルのリビジョン毎に拡張されるかもしれないが、 以前のプロ
       グラムはそのまま動作する。

       移植性のあるインターフェースは  cap_set_proc(3)  と cap_get_proc(3)  である。 可能ならばア
       プリケーションはこれらの関数を使用すべきである。

   現在の詳細
       現在のカーネルの詳細について注意を述べておく。 構造体は以下のように定義される。

           #define _LINUX_CAPABILITY_VERSION_1  0x19980330
           #define _LINUX_CAPABILITY_U32S_1     1

                   /* V2 added in Linux 2.6.25; deprecated */
           #define _LINUX_CAPABILITY_VERSION_2  0x20071026
           #define _LINUX_CAPABILITY_U32S_2     2

                   /* V3 added in Linux 2.6.26 */
           #define _LINUX_CAPABILITY_VERSION_3  0x20080522
           #define _LINUX_CAPABILITY_U32S_3     2

           typedef struct __user_cap_header_struct {
              __u32 version;
              int pid;
           } *cap_user_header_t;

           typedef struct __user_cap_data_struct {
              __u32 effective;
              __u32 permitted;
              __u32 inheritable;
           } *cap_user_data_t;

       フィールド effective, permitted, inheritable は、  capabilities(7)  で定義されるケーパビリ
       ティのビットマスクである。 CAP_* はビット番号を表すインデックス値であり、 ビットフィールド
       に OR を行う前に CAP_* の値の分だけビットシフトを行う必要がある。 typedef の方はポインター
       なので、 このシステムコールに渡す構造体を定義するには、 struct __user_cap_header_struct と
       struct __user_cap_data_struct という名前を使用しなければならない。

       Kernels    prior    to    2.6.25    prefer    32-bit     capabilities     with     version
       _LINUX_CAPABILITY_VERSION_1.   Linux  2.6.25  added  64-bit  capability sets, with version
       _LINUX_CAPABILITY_VERSION_2.  There was, however, an API glitch, and  Linux  2.6.26  added
       _LINUX_CAPABILITY_VERSION_3 to fix the problem.

       Note  that  64-bit capabilities use datap[0] and datap[1], whereas 32-bit capabilities use
       only datap[0].

       On kernels that support file capabilities (VFS capabilities support), these  system  calls
       behave  slightly  differently.   This  support was added as an option in Linux 2.6.24, and
       became fixed (nonoptional) in Linux 2.6.33.

       capget()  では、 hdrp->pid  のフィールド値にケーパビリティを知りたいプロセスのプロセス  ID
       を 指定することで、任意のプロセスのケーパビリティを調べることができる。

       このデータの詳細は capabilities(7)  を参照すること。

   VFS ケーパビリティがサポートされている場合
       VFS capabilities employ a file extended attribute (see xattr(7))  to allow capabilities to
       be attached to executables.  This privilege model obsoletes kernel support for one process
       asynchronously  setting  the  capabilities  of another.  That is, on kernels that have VFS
       capabilities support, when calling capset(), the only permitted values for hdrp->pid are 0
       or, equivalently, the value returned by gettid(2).

   VFS ケーパビリティがサポートされていない場合
       On  older kernels that do not provide VFS capabilities support capset() can, if the caller
       has the CAP_SETPCAP capability, be used to change not only the caller's own  capabilities,
       but  also the capabilities of other threads.  The call operates on the capabilities of the
       thread specified by the pid field of hdrp when that is nonzero, or on the capabilities  of
       the  calling thread if pid is 0.  If pid refers to a single-threaded process, then pid can
       be specified as a traditional process ID; operating on a thread of a multithreaded process
       requires  a  thread  ID of the type returned by gettid(2).  For capset(), pid can also be:
       -1, meaning perform the change on all threads except the caller and init(1);  or  a  value
       less  than  -1,  in  which  case the change is applied to all members of the process group
       whose ID is -pid.

返り値

       成功した場合は 0 が返される。エラーの場合は -1 が返され、 errno が適切に設定される。

       hdrp  のフィールド  version  にサポートされていない値が指定された場合、   呼び出しはエラー
       EINVAL で失敗し、 version にカーネル推奨の _LINUX_CAPABILITY_VERSION_? を設定する。 このよ
       うにして、現在の推奨ケーパビリティリビジョンが何かを 調べることができる。

エラー

       EFAULT 不正なメモリーアドレス。 hdrp は NULL であってはならない。 datap に NULL を指定して
              よいのは、ユーザーがカーネルがサポートしている 推奨のケーパビリティバージョンを判定
              しようとしているときだけである。

       EINVAL 引数のどれかが無効である。

       EPERM  An attempt was made to add  a  capability  to  the  permitted  set,  or  to  set  a
              capability in the effective set that is not in the permitted set.

       EPERM  An attempt was made to add a capability to the inheritable set, and either:

              *  that capability was not in the caller's bounding set; or

              *  the  capability  was not in the caller's permitted set and the caller lacked the
                 CAP_SETPCAP capability in its effective set.

       EPERM  呼び出し元が自分以外のスレッドのケーパビリティを capset()  を使って修正しようとした
              が、十分な特権がなかった。  VFS ケーパビリティをサポートしているカーネルでは、 この
              操作が許可されることは決してない。 VFS ケーパビリティをサポートしていないカーネルで
              は、 CAP_SETPCAP ケーパビリティが必要である。 (バージョン 2.6.11 より前のカーネルに
              は、 このケーパビリティを持たないスレッドが pid フィールドに 0 でない値  (つまり、0
              の代わりに  getpid(2)  が返す値) を指定して自分自身のケーパビリティを変更しようとし
              た場合にも、 このエラーが発生するというバグがあった。)

       ESRCH  そのようなスレッドが存在しない。

準拠

       これらのシステムコールは Linux 独自である。

注意

       ケーパビリティを設定したり取得したりする機能のための移植性ある  インターフェースは  libcap
       ライブラリによって提供される。 このライブラリは以下から入手できる:
       ⟨http://git.kernel.org/cgit/linux/kernel/git/morgan/libcap.git⟩

関連項目

       clone(2), gettid(2), capabilities(7)

この文書について

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