Debian Codegraph @

upstream/fedora-44/man2const/KEYCTL_JOIN_SESSION_KEYRING.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_JOIN_SESSION_KEYRING 2const 2024-08-21 "Linux man-pages 6.13"
10 .SH NAME
11 KEYCTL_JOIN_SESSION_KEYRING
12 \-
13 replace the session keyring this process subscribes to with a new one
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 .B long syscall(SYS_keyctl, KEYCTL_JOIN_SESSION_KEYRING,
24 .BI " char *_Nullable " desc );
25 .fi
26 .SH DESCRIPTION
27 Replace the session keyring this process subscribes to with
28 a new session keyring.
29 .\" This may be useful in conjunction with some sort of
30 .\" session management framework that is employed by the application.
31 .P
32 If
33 .I desc
34 is NULL,
35 an anonymous keyring with the description "_ses" is created
36 and the process is subscribed to that keyring as its session keyring,
37 displacing the previous session keyring.
38 .P
39 Otherwise,
40 .I desc
41 is treated as the description (name) of a keyring,
42 and the behavior is as follows:
43 .IP \[bu] 3
44 If a keyring with a matching description exists,
45 the process will attempt to subscribe to that keyring
46 as its session keyring if possible;
47 if that is not possible, an error is returned.
48 In order to subscribe to the keyring,
49 the caller must have
50 .I search
51 permission on the keyring.
52 .IP \[bu]
53 If a keyring with a matching description does not exist,
54 then a new keyring with the specified description is created,
55 and the process is subscribed to that keyring as its session keyring.
56 .SH RETURN VALUE
57 On success,
58 the ID of the joined session keyring.
59 .P
60 On error, \-1 is returned, and
61 .I errno
62 is set to indicate the error.
63 .SH VERSIONS
64 A wrapper is provided in the
65 .I libkeyutils
66 library:
67 .BR keyctl_join_session_keyring (3).
68 .SH STANDARDS
69 Linux.
70 .SH HISTORY
71 Linux 2.6.10.
72 .SH SEE ALSO
73 .BR keyctl (2),
74 .BR keyctl_join_session_keyring (3)