Debian Codegraph @

upstream/debian-unstable/man2/KEYCTL_SESSION_TO_PARENT.2const

raw
1 .\" Copyright 2016, Michael Kerrisk <[email protected]>
2 .\" Copyright 2016, Eugene Syromyatnikov <[email protected]>
3 .\" Copyright, the authors of the Linux man-pages project
4 .\"
5 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
6 .\"
7 .TH KEYCTL_SESSION_TO_PARENT 2const 2026-02-08 "Linux man-pages 6.18"
8 .SH NAME
9 KEYCTL_SESSION_TO_PARENT
10 \-
11 set the parent process's session keyring
12 .SH LIBRARY
13 Standard C library
14 .RI ( libc ,\~ \-lc )
15 .SH SYNOPSIS
16 .nf
17 .BR "#include <linux/keyctl.h>" " /* Definition of " KEY* " constants */"
18 .BR "#include <sys/syscall.h>" " /* Definition of " SYS_* " constants */"
19 .B #include <unistd.h>
20 .P
21 .B long syscall(SYS_keyctl, KEYCTL_SESSION_TO_PARENT);
22 .fi
23 .SH DESCRIPTION
24 Replace the session keyring to which the
25 .I parent
26 of the calling process
27 subscribes with the session keyring of the calling process.
28 .\" What is the use case for KEYCTL_SESSION_TO_PARENT?
29 .\" David Howells: the Process Authentication Groups people requested this,
30 .\" but then didn't use it; maybe there are no users.
31 .P
32 The keyring will be replaced in the parent process at the point
33 where the parent next transitions from kernel space to user space.
34 .P
35 The keyring must exist and must grant the caller
36 .I link
37 permission.
38 The parent process must be single-threaded and have
39 the same effective ownership as this process
40 and must not be set-user-ID or set-group-ID.
41 The UID of the parent process's existing session keyring (f it has one),
42 as well as the UID of the caller's session keyring
43 much match the caller's effective UID.
44 .P
45 The fact that it is the parent process that is affected by this operation
46 allows a program such as the shell to start a child process that
47 uses this operation to change the shell's session keyring.
48 (This is what the
49 .BR keyctl (1)
50 .B new_session
51 command does.)
52 .SH RETURN VALUE
53 On success,
54 0 is returned.
55 .P
56 On error, \-1 is returned, and
57 .I errno
58 is set to indicate the error.
59 .SH ERRORS
60 .TP
61 .B EPERM
62 All of the UIDs (GIDs) of the parent process do not match
63 the effective UID (GID) of the calling process.
64 .TP
65 .B EPERM
66 The UID of the parent's existing session keyring or
67 the UID of the caller's session keyring did not match
68 the effective UID of the caller.
69 .TP
70 .B EPERM
71 The parent process is not single-threaded.
72 .TP
73 .B EPERM
74 The parent process is
75 .BR init (1)
76 or a kernel thread.
77 .SH VERSIONS
78 A wrapper is provided in the
79 .I libkeyutils
80 library:
81 .BR keyctl_session_to_parent (3).
82 .SH STANDARDS
83 Linux.
84 .SH HISTORY
85 Linux 2.6.32.
86 .\" commit ee18d64c1f632043a02e6f5ba5e045bb26a5465f
87 .SH SEE ALSO
88 .BR keyctl (2),
89 .BR keyctl_session_to_parent (3)