名前

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

Linux                                              2020-02-09                                          CAPGET(2)