Debian Codegraph @

upstream/fedora-44/man2const/KEYCTL_SESSION_TO_PARENT.2const

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