名前

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