# keyctl_search

## NAME



           keyctl_search - search a keyring for a key
    


## SYNOPSIS



           **#include <keyutils.h>**
    
           **long keyctl_search(key_serial_t** _keyring_**, const char ***_type_**,**
           **const char ***_description_**, key_serial_t** _destination_**);**
    


## DESCRIPTION



           **keyctl_search**() recursively searches the _keyring_ for a key of the
           specified _type_ and _description_.
    
           If found, the key will be attached to the _destination_ keyring (if
           given), and its serial number will be returned.
    
           The source keyring must grant **search** permission to the caller, and
           for a key to be found, it must also grant **search** permission to the
           caller.  Child keyrings will be only be recursively searched if
           they grant **search** permission to the caller as well.
    
           If the destination keyring is **zero** , no attempt will be made to
           forge a link to the key, and just the serial number will be
           returned.
    
           If the destination keyring is given, then the link may only be
           formed if the found key grants the caller **link** permission and the
           destination keyring grants the caller **write** permission.
    
           If the search is successful, and if the destination keyring
           already contains a link to a key that matches the specified _type_
           and _description_ , then that link will be replaced by a link to the
           found key.
    
           The source keyring and destination keyring serial numbers may be
           those of valid keyrings to which the caller has appropriate
           permission, or they may be special keyring IDs:
    
           **KEY_SPEC_THREAD_KEYRING**
                  This specifies the caller's thread-specific keyring.
    
           **KEY_SPEC_PROCESS_KEYRING**
                  This specifies the caller's process-specific keyring.
    
           **KEY_SPEC_SESSION_KEYRING**
                  This specifies the caller's session-specific keyring.
    
           **KEY_SPEC_USER_KEYRING**
                  This specifies the caller's UID-specific keyring.
    
           **KEY_SPEC_USER_SESSION_KEYRING**
                  This specifies the caller's UID-session keyring.
    


## RETURN VALUE



           On success **keyctl_search**() returns the serial number of the key it
           found.  On error, the value **-1** will be returned and _errno_ will
           have been set to an appropriate error.
    


## ERRORS



           **ENOKEY** One of the keyrings doesn't exist, no key was found by the
                  search, or the only key found by the search was a negative
                  key.
    
           **ENOTDIR**
                  One of the keyrings is a valid key that isn't a keyring.
    
           **EKEYEXPIRED**
                  One of the keyrings has expired, or the only key found was
                  expired.
    
           **EKEYREVOKED**
                  One of the keyrings has been revoked, or the only key found
                  was revoked.
    
           **ENOMEM** Insufficient memory to expand the destination keyring.
    
           **EDQUOT** The key quota for this user would be exceeded by creating a
                  link to the found key in the destination keyring.
    
           **EACCES** The source keyring didn't grant **search** permission, the
                  destination keyring didn't grant **write** permission or the
                  found key didn't grant **link** permission to the caller.
    


## LINKING



           Although this is a Linux system call, it is not present in _libc_
           but can be found rather in _libkeyutils_.  When linking, **-lkeyutils**
           should be specified to the linker.
    


* * *