1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
|
.\" Copyright, the authors of the Linux man-pages project
.\"
.\" SPDX-License-Identifier: Linux-man-pages-copyleft
.\"
.TH KEYCTL_SESSION_TO_PARENT 2const 2025-06-01 "Linux man-pages (unreleased)"
.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 <linux/keyctl.h>" " /* Definition of " KEY* " constants */"
.BR "#include <sys/syscall.h>" " /* Definition of " SYS_* " constants */"
.B #include <unistd.h>
.P
.B 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)
|
