.\" Copyright 2016, Michael Kerrisk .\" Copyright 2016, Eugene Syromyatnikov .\" A very few fragments remain from an earlier version of this page .\" written by David Howells (dhowells@redhat.com) .\" Copyright 2024, Alejandro Colomar .\" .\" SPDX-License-Identifier: Linux-man-pages-copyleft .\" .TH KEYCTL_SESSION_TO_PARENT 2const 2024-08-21 "Linux man-pages 6.10" .SH NAME KEYCTL_SESSION_TO_PARENT \- set the parent process's session keyring .SH LIBRARY Standard C library .RI ( libc ,\~ \-lc ) .SH SYNOPSIS .nf .BR "#include " " /* Definition of " KEY* " constants */" .BR "#include " " /* Definition of " SYS_* " constants */" .B #include .P .BI long syscall(SYS_keyctl, KEYCTL_SESSION_TO_PARENT); .fi .SH DESCRIPTION Replace the session keyring to which the .I parent of the calling process subscribes with the session keyring of the calling process. .\" What is the use case for KEYCTL_SESSION_TO_PARENT? .\" David Howells: the Process Authentication Groups people requested this, .\" but then didn't use it; maybe there are no users. .P The keyring will be replaced in the parent process at the point where the parent next transitions from kernel space to user space. .P The keyring must exist and must grant the caller .I link permission. The parent process must be single-threaded and have the same effective ownership as this process and must not be set-user-ID or set-group-ID. The UID of the parent process's existing session keyring (f it has one), as well as the UID of the caller's session keyring much match the caller's effective UID. .P The fact that it is the parent process that is affected by this operation allows a program such as the shell to start a child process that uses this operation to change the shell's session keyring. (This is what the .BR keyctl (1) .B new_session command does.) .SH RETURN VALUE On success, 0 is returned. .P On error, \-1 is returned, and .I errno is set to indicate the error. .SH ERRORS .TP .B EPERM All of the UIDs (GIDs) of the parent process do not match the effective UID (GID) of the calling process. .TP .B EPERM The UID of the parent's existing session keyring or the UID of the caller's session keyring did not match the effective UID of the caller. .TP .B EPERM The parent process is not single-threaded. .TP .B EPERM The parent process is .BR init (1) or a kernel thread. .SH VERSIONS A wrapper is provided in the .I libkeyutils library: .BR keyctl_session_to_parent (3). .SH STANDARDS Linux. .SH HISTORY Linux 2.6.32. .\" commit ee18d64c1f632043a02e6f5ba5e045bb26a5465f .SH SEE ALSO .BR keyctl (2), .BR keyctl_session_to_parent (3)