Debian Codegraph @

upstream/fedora-44/man2const/KEYCTL_SET_TIMEOUT.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_SET_TIMEOUT 2const 2024-08-21 "Linux man-pages 6.13"
10 .SH NAME
11 KEYCTL_SET_TIMEOUT
12 \-
13 set the expiration timer on a key
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_SET_TIMEOUT, key_serial_t " key \
24 ", time_t " t );
25 .fi
26 .SH DESCRIPTION
27 Set a timeout on a key.
28 .P
29 The ID of the key is specified in
30 .IR key .
31 The timeout value, in seconds from the current time,
32 is specified in
33 .IR t .
34 The timeout is measured against the realtime clock.
35 .P
36 Specifying the timeout value as 0 clears any existing timeout on the key.
37 .P
38 The
39 .I /proc/keys
40 file displays the remaining time until each key will expire.
41 (This is the only method of discovering the timeout on a key.)
42 .P
43 The caller must either have the
44 .I setattr
45 permission on the key
46 or hold an instantiation authorization token for the key (see
47 .BR request_key (2)).
48 .P
49 The key and any links to the key will be
50 automatically garbage collected after the timeout expires.
51 Subsequent attempts to access the key will then fail with the error
52 .BR EKEYEXPIRED .
53 .P
54 This operation cannot be used to set timeouts on revoked, expired,
55 or negatively instantiated keys.
56 .SH RETURN VALUE
57 On success,
58 0 is returned.
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_set_timeout (3).
68 .SH STANDARDS
69 Linux.
70 .SH HISTORY
71 Linux 2.6.16.
72 .SH SEE ALSO
73 .BR keyctl (2),
74 .BR keyctl_set_timeout (3)