.\" Copyright (C) 2006 Red Hat, Inc. All Rights Reserved.
.\" Written by David Howells (dhowells@redhat.com)
.\"
.\" %%%LICENSE_START(GPLv2+_SW_ONEPARA)
.\" This program is free software; you can redistribute it and/or
.\" modify it under the terms of the GNU General Public License
.\" as published by the Free Software Foundation; either version
.\" 2 of the License, or (at your option) any later version.
.\" %%%LICENSE_END
.\"
.\"*******************************************************************
.\"
.\" This file was generated with po4a. Translate the source file.
.\"
.\"*******************************************************************
.TH REQUEST_KEY 2 2010\-02\-25 Linux "Linux Key Management Calls"
.SH 名前
request_key \- カーネルの鍵管理機能から鍵を取得する
.SH 書式
.nf
\fB#include <keyutils.h>\fP
.sp
\fBkey_serial_t request_key(const char *\fP\fItype\fP\fB, const char *\fP\fIdescription\fP\fB,\fP
\fB                         const char *\fP\fIcallout_info\fP\fB,\fP
\fB                         key_serial_t \fP\fIkeyring\fP\fB);\fP
.fi
.SH 説明
\fBrequest_key\fP()  asks the kernel to find a key of the given \fItype\fP that
matches the specified \fIdescription\fP and, if successful, to attach it to the
nominated \fIkeyring\fP and to return its serial number.
.P
\fBrequest_key\fP()  first recursively searches all the keyrings attached to
the calling process in the order thread\-specific keyring, process\-specific
keyring and then session keyring for a matching key.
.P
If \fBrequest_key\fP()  is called from a program invoked by \fBrequest_key\fP()
on behalf of some other process to generate a key, then the keyrings of that
other process will be searched next, using that other process's UID, GID,
groups, and security context to control access.
.P
The keys in each keyring searched are checked for a match before any child
keyrings are recursed into.  Only keys that are \fBsearchable\fP for the caller
may be found, and only \fBsearchable\fP keyrings may be searched.
.P
If the key is not found, then, if \fIcallout_info\fP is set, this function will
attempt to look further afield.  In such a case, the \fIcallout_info\fP is
passed to a user\-space service such as \fB/sbin/request\-key\fP to generate the
key.
.P
If that is unsuccessful also, then an error will be returned, and a
temporary negative key will be installed in the nominated \fIkeyring\fP.  This
will expire after a few seconds, but will cause subsequent calls to
\fBrequest_key\fP()  to fail until it does.
.P
The \fIkeyring\fP serial number may be that of a valid keyring to which the
caller has write permission, or it may be a special keyring ID:
.TP 
\fBKEY_SPEC_THREAD_KEYRING\fP
この値は呼び出し元スレッド固有の鍵リングを指定する。
.TP 
\fBKEY_SPEC_PROCESS_KEYRING\fP
この値は呼び出し元プロセス固有の鍵リングを指定する。
.TP 
\fBKEY_SPEC_SESSION_KEYRING\fP
この値は呼び出し元セッション固有の鍵リングを指定する。
.TP 
\fBKEY_SPEC_USER_KEYRING\fP
この値は呼び出し元の UID 固有の鍵リングを指定する。
.TP 
\fBKEY_SPEC_USER_SESSION_KEYRING\fP
この値は呼び出し元の UID のセッションの鍵リングを指定する。
.P
If a key is created, no matter whether it's a valid key or a negative key,
it will displace any other key of the same type and description from the
destination \fIkeyring\fP.
.SH 返り値
成功すると \fBrequest_key\fP() は見つかった鍵のシリアル番号を返す。 エラーの場合、 値 \-1 が返され、 \fIerrno\fP
にエラーを示す値が設定される。
.SH エラー
.TP 
\fBEACCES\fP
そのユーザーは指定された鍵リングを変更できない。
.TP 
\fBEINTR\fP
要求がシングルで中断された。
.TP 
\fBEDQUOT\fP
この鍵を作成するか、鍵を鍵リングに追加すると、 このユーザーの鍵リングのクォータを超過してしまう。
.TP 
\fBEKEYEXPIRED\fP
期限切れの鍵が見つかったが、 新しい代わりの鍵が取得できなかった。
.TP 
\fBEKEYREJECTED\fP
新しい鍵の生成が拒否された。
.TP 
\fBEKEYREVOKED\fP
廃止された鍵が見つかったが、 新しい代わりの鍵が取得できなかった。
.TP 
\fBENOMEM\fP
鍵を作成するのに十分なメモリーがない。
.TP 
\fBENOKEY\fP
合致する鍵が見つからなかった。
.SH LINKING
これは Linux のシステムコールだが、 \fIlibc\fP には存在せず、 代わりに \fIlibkeyutils\fP に存在する。 リンクする際には、
リンカーに \fB\-lkeyutils\fP を指定する必要がある。
.SH 関連項目
\fBkeyctl\fP(1), \fBadd_key\fP(2), \fBkeyctl\fP(2), \fBrequest\-key\fP(8)
.SH この文書について
この man ページは Linux \fIman\-pages\fP プロジェクトのリリース 3.79 の一部
である。プロジェクトの説明とバグ報告に関する情報は
http://www.kernel.org/doc/man\-pages/ に書かれている。