HTML rendering created 2025-09-06 byMichael Kerrisk, author ofThe Linux Programming Interface. For details of in-depthLinux/UNIX system programming training courses that I teach, lookhere. Hosting byjambit GmbH. |  |
NAME |LIBRARY |SYNOPSIS |DESCRIPTION |RETURN VALUE |VERSIONS |STANDARDS |HISTORY |SEE ALSO |COLOPHON | |
KEYCTL_INSTANTIATE(2const)KEYCTL_INSTANTIATE(2const)KEYCTL_INSTANTIATE, KEYCTL_INSTANTIATE_IOV, KEYCTL_NEGATE, KEYCTL_REJECT - key instantiation functions
Standard C library (libc,-lc)
#include <linux/keyctl.h>/* Definition ofKEY*constants */#include <sys/syscall.h>/* Definition ofSYS_*constants */#include <unistd.h>long syscall(size_t n;SYS_keyctl, KEYCTL_INSTANTIATE, key_serial_tkey,const voidpayload[n], size_tn,key_serial_tkeyring);long syscall(size_t n;SYS_keyctl, KEYCTL_INSTANTIATE_IOV, key_serial_tkey,const struct iovecpayload[n], unsigned intn,key_serial_tkeyring);long syscall(SYS_keyctl, KEYCTL_NEGATE, key_serial_tkey,unsigned inttimeout, key_serial_tkeyring);long syscall(SYS_keyctl, KEYCTL_REJECT, key_serial_tkey,unsigned inttimeout, interror, key_serial_tkeyring);
KEYCTL_INSTANTIATE (Positively) instantiate an uninstantiated key with a specified payload. The ID of the key to be instantiated is provided inkey. The key payload is specified in the buffer pointed to bypayload; the size of that buffer is specified inn. The payload may be a null pointer and the buffer size may be 0 if this is supported by the key type (e.g., it is a keyring). The operation may be fail if the payload data is in the wrong format or is otherwise invalid. Ifkeyring is nonzero, then, subject to the same constraints and rules asKEYCTL_LINK(2const), the instantiated key is linked into the keyring whose ID specified inkeyring. The caller must have the appropriate authorization key, and once the uninstantiated key has been instantiated, the authorization key is revoked. In other words, this operation is available only from arequest-key(8)-style program. Seerequest_key(2) for an explanation of uninstantiated keys and key instantiation.KEYCTL_INSTANTIATE_IOV Instantiate an uninstantiated key with a payload specified via a vector of buffers. This operation is the same asKEYCTL_INSTANTIATE, but the payload data is specified as an array ofiovec structures (seeiovec(3type)). The pointer to the payload vector is specified inpayload. The number of items in the vector is specified inn. Thekey andkeyring are interpreted as forKEYCTL_INSTANTIATE.KEYCTL_NEGATE Negatively instantiate an uninstantiated key. This operation is equivalent to the call: keyctl(KEYCTL_REJECT, key, timeout, ENOKEY, keyring);KEYCTL_REJECT Mark a key as negatively instantiated and set an expiration timer on the key. This operation provides a superset of the functionality of the earlierKEYCTL_NEGATEoperation. The ID of the key that is to be negatively instantiated is specified inkey. Thetimeout argument specifies the lifetime of the key, in seconds. Theerror argument specifies the error to be returned when a search hits this key; typically, this is one ofEKEYREJECTED,EKEYREVOKED, orEKEYEXPIRED. Ifkeyring is nonzero, then, subject to the same constraints and rules asKEYCTL_LINK(2const), the negatively instantiated key is linked into the keyring whose ID is specified inkeyring. The caller must have the appropriate authorization key. In other words, this operation is available only from arequest-key(8)-style program. Seerequest_key(2). The caller must have the appropriate authorization key, and once the uninstantiated key has been instantiated, the authorization key is revoked. In other words, this operation is available only from arequest-key(8)-style program. Seerequest_key(2) for an explanation of uninstantiated keys and key instantiation.
On success, 0 is returned. On error, -1 is returned, anderrno is set to indicate the error.
Wrappers are provided in thelibkeyutils library:keyctl_instantiate(3),keyctl_instantiate_iov(3),keyctl_negate(3), andkeyctl_reject(3).
Linux.
KEYCTL_INSTANTIATEKEYCTL_NEGATE Linux 2.6.10.KEYCTL_INSTANTIATE_IOVKEYCTL_REJECT Linux 2.6.39.
keyctl(2),keyctl_instantiate(3),keyctl_instantiate_iov(3),keyctl_negate(3),keyctl_reject(3)
This page is part of theman-pages (Linux kernel and C library user-space interface documentation) project. Information about the project can be found at ⟨https://www.kernel.org/doc/man-pages/⟩. If you have a bug report for this manual page, see ⟨https://git.kernel.org/pub/scm/docs/man-pages/man-pages.git/tree/CONTRIBUTING⟩. This page was obtained from the tarball man-pages-6.15.tar.gz fetched from ⟨https://mirrors.edge.kernel.org/pub/linux/docs/man-pages/⟩ on 2025-08-11. If you discover any rendering problems in this HTML version of the page, or you believe there is a better or more up- to-date source for the page, or you have corrections or improvements to the information in this COLOPHON (which isnot part of the original manual page), send a mail to man-pages@man7.orgLinux man-pages 6.15 2025-06-28KEYCTL_INSTANTIATE(2const)Pages that refer to this page:keyctl(2), KEYCTL_ASSUME_AUTHORITY(2const), KEYCTL_UPDATE(2const)
HTML rendering created 2025-09-06 byMichael Kerrisk, author ofThe Linux Programming Interface. For details of in-depthLinux/UNIX system programming training courses that I teach, lookhere. Hosting byjambit GmbH. | |