---
name: "KEYCTL_SEARCH"
section: "2const"
platform: "linux"
package: "man-pages"
version: "6.19-1"
release: "Arch Linux 2026-11-01"
platforms: ["linux"]
url: "https://new.carta.tech/KEYCTL_SEARCH"
---

# KEYCTL\_SEARCH(2const)

search a keyring for a key

## NAME

KEYCTL\_SEARCH - search a keyring for a key

## 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\_SEARCH, key\_serial\_t** *src***,**              **char \****type***, char \****desc***,**              **unsigned long** *dst***);**

## DESCRIPTION

Search for a key in a keyring tree, returning its ID and optionally linking it to a specified keyring.

The tree to be searched is specified by passing the ID of the head keyring in *src*. The search is performed breadth-first and recursively.

The *type* and *desc* arguments specify the key to be searched for: *type* contains the key type (a null-terminated character string up to 32 bytes in size, including the terminating null byte), and *desc* contains the description of the key (a null-terminated character string up to 4096 bytes in size, including the terminating null byte).

The source keyring must grant *search* permission to the caller. When performing the recursive search, only keyrings that grant the caller *search* permission will be searched. Only keys with for which the caller has *search* permission can be found.

If the key is found, its ID is returned as the function result.

If the key is found and *dst* is nonzero, then, subject to the same constraints and rules as [**KEYCTL\_LINK**(2const)](/KEYCTL_LINK/2const.md), the key is linked into the keyring whose ID is specified in *dst*. If the destination keyring specified in *dst* already contains a link to a key that has the same type and description, then that link will be displaced by a link to the key found by this operation.

Instead of valid existing keyring IDs, the source (*src*) and destination (*dst*) keyrings can be one of the special keyring IDs listed under [**KEYCTL\_GET\_KEYRING\_ID**(2const)](/KEYCTL_GET_KEYRING_ID/2const.md).

## RETURN VALUE

On success, the ID of the key that was found.

On error, -1 is returned, and *errno* is set to indicate the error.

## ERRORS

- **EINVAL**

  The size of the description in *desc* (including the terminating null byte) exceeded 4096 bytes.

## VERSIONS

A wrapper is provided in the *libkeyutils* library: [**keyctl\_search**(3)](/keyctl_search/3.md).

## STANDARDS

Linux.

## HISTORY

Linux 2.6.10.

## SEE ALSO

[**keyctl**(2)](/keyctl/2.md), [**keyctl\_search**(3)](/keyctl_search/3.md)