# KEYCTL_GET_KEYRING_ID

## NAME



           KEYCTL_GET_KEYRING_ID - map a special key ID to a real key ID for
           this process
    


## LIBRARY



           Standard C library (_libc_ , _-lc_)
    


## SYNOPSIS



           **#include <linux/keyctl.h>  **/* Definition of **KEY*** constants */
           **#include <sys/syscall.h>   **/* Definition of **SYS_*** constants */
           **#include <unistd.h>**
    
           **long syscall(SYS_keyctl, KEYCTL_GET_KEYRING_ID, key_serial_t** _key_**,**
                        **int** _arg3_**);**
    


## DESCRIPTION



           Map a special key ID to a real key ID for this process.
    
           This operation looks up the special key whose ID is provided in
           _key_.  If the special key is found, the ID of the corresponding
           real key is returned as the function result.  The following values
           may be specified in _key_ :
    
           **KEY_SPEC_THREAD_KEYRING**
                  This specifies the calling thread's thread-specific
                  keyring.  See thread-keyring(7).
    
           **KEY_SPEC_PROCESS_KEYRING**
                  This specifies the caller's process-specific keyring.  See
                  process-keyring(7).
    
           **KEY_SPEC_SESSION_KEYRING**
                  This specifies the caller's session-specific keyring.  See
                  session-keyring(7).
    
           **KEY_SPEC_USER_KEYRING**
                  This specifies the caller's UID-specific keyring.  See
                  user-keyring(7).
    
           **KEY_SPEC_USER_SESSION_KEYRING**
                  This specifies the caller's UID-session keyring.  See
                  user-session-keyring(7).
    
           **KEY_SPEC_REQKEY_AUTH_KEY**(since Linux 2.6.16)
                  This specifies the authorization key created by
                  request_key(2) and passed to the process it spawns to
                  generate a key.  This key is available only in a
                  request-key(8)-style program that was passed an
                  authorization key by the kernel and ceases to be available
                  once the requested key has been instantiated; see
                  request_key(2).
    
           **KEY_SPEC_REQUESTOR_KEYRING**(since Linux 2.6.29)
                  This specifies the key ID for the request_key(2)
                  destination keyring.  This keyring is available only in a
                  request-key(8)-style program that was passed an
                  authorization key by the kernel and ceases to be available
                  once the requested key has been instantiated; see
                  request_key(2).
    
           The behavior if the key specified in _key_ does not exist depends on
           the value of _arg3_.  If _arg3_ contains a nonzero value, then —if it
           is appropriate to do so (e.g., when looking up the user, user-
           session, or session key)— a new key is created and its real key ID
           returned as the function result.  Otherwise, the operation fails
           with the error **ENOKEY**.
    
           If a valid key ID is specified in _key_ , and the key exists, then
           this operation simply returns the key ID.  If the key does not
           exist, the call fails with error **ENOKEY**.
    
           The caller must have _search_ permission on a keyring in order for
           it to be found.
    


## RETURN VALUE



           On success, the ID of the requested keyring.
    
           On error, -1 is returned, and _errno_ is set to indicate the error.
    


## ERRORS



           **ENOKEY** The key specified in _key_ did not exist, and _arg3_ was zero
                  (meaning don't create the key if it didn't exist).
    


## VERSIONS



           A wrapper is provided in the _libkeyutils_ library:
           keyctl_get_keyring_ID(3).
    


## STANDARDS



           Linux.
    


* * *