---
name: "KEYCTL_GET_KEYRING_ID"
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_GET_KEYRING_ID"
---

# KEYCTL\_GET\_KEYRING\_ID(2const)

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

## 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)](/thread-keyring/7.md).

- **KEY\_SPEC\_PROCESS\_KEYRING**

  This specifies the caller's process-specific keyring. See [**process-keyring**(7)](/process-keyring/7.md).

- **KEY\_SPEC\_SESSION\_KEYRING**

  This specifies the caller's session-specific keyring. See [**session-keyring**(7)](/session-keyring/7.md).

- **KEY\_SPEC\_USER\_KEYRING**

  This specifies the caller's UID-specific keyring. See [**user-keyring**(7)](/user-keyring/7.md).

- **KEY\_SPEC\_USER\_SESSION\_KEYRING**

  This specifies the caller's UID-session keyring. See [**user-session-keyring**(7)](/user-session-keyring/7.md).

- **KEY\_SPEC\_REQKEY\_AUTH\_KEY** (since Linux 2.6.16)

  This specifies the authorization key created by [**request\_key**(2)](/request_key/2.md) and passed to the process it spawns to generate a key. This key is available only in a [**request-key**(8)](/request-key/8.md)-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)](/request_key/2.md).

- **KEY\_SPEC\_REQUESTOR\_KEYRING** (since Linux 2.6.29)

  This specifies the key ID for the [**request\_key**(2)](/request_key/2.md) destination keyring. This keyring is available only in a [**request-key**(8)](/request-key/8.md)-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)](/request_key/2.md).

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)](/keyctl_get_keyring_ID/3.md).

## STANDARDS

Linux.

## HISTORY

Linux 2.6.10.

## SEE ALSO

[**keyctl**(2)](/keyctl/2.md), [**keyctl\_get\_keyring\_ID**(3)](/keyctl_get_keyring_ID/3.md)