Debian Codegraph @

upstream/debian-unstable/man2/KEYCTL_DESCRIBE.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_DESCRIBE 2const 2026-02-08 "Linux man-pages 6.18"
8 .SH NAME
9 KEYCTL_DESCRIBE
10 \-
11 describe a key
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 .BR "long syscall(" "size_t size;"
22 .BI " SYS_keyctl, KEYCTL_DESCRIBE, key_serial_t " key ,
23 .BI " char " desc "[_Nullable " size "], size_t " size );
24 .fi
25 .SH DESCRIPTION
26 Obtain a string describing the attributes of a specified key.
27 .P
28 The ID of the key to be described is specified in
29 .IR key .
30 The descriptive string is returned in the buffer pointed to by
31 .IR desc ;
32 .I size
33 specifies the size of that buffer in bytes.
34 .P
35 The key must grant the caller
36 .I view
37 permission.
38 .P
39 The returned string is null-terminated and
40 contains the following information about the key:
41 .P
42 .in +4n
43 .IR type ; uid ; gid ; perm ; description
44 .in
45 .P
46 In the above,
47 .I type
48 and
49 .I description
50 are strings,
51 .I uid
52 and
53 .I gid
54 are decimal strings, and
55 .I perm
56 is a hexadecimal permissions mask.
57 The descriptive string is written with the following format:
58 .P
59 .in +4n
60 .EX
61 %s;%d;%d;%08x;%s
62 .EE
63 .in
64 .P
65 .B Note: the intention is that the descriptive string should
66 .B be extensible in future kernel versions.
67 In particular, the
68 .I description
69 field will not contain semicolons;
70 .\" FIXME But, the kernel does not enforce the requirement
71 .\" that the key description contains no semicolons!
72 .\" So, user space has no guarantee here??
73 .\" Either something more needs to be said here,
74 .\" or a kernel fix is required.
75 it should be parsed by working backwards from the end of the string
76 to find the last semicolon.
77 This allows future semicolon-delimited fields to be inserted
78 in the descriptive string in the future.
79 .P
80 Writing to the buffer is attempted only when
81 .I desc
82 is non-NULL and the specified buffer size
83 is large enough to accept the descriptive string
84 (including the terminating null byte).
85 .\" Function commentary says it copies up to buflen bytes, but see the
86 .\" (buffer && buflen >= ret) condition in keyctl_describe_key() in
87 .\" security/keyctl.c
88 In order to determine whether the buffer size was too small,
89 check to see if the return value of the operation is greater than
90 .IR size .
91 .SH RETURN VALUE
92 On success,
93 the size of the description (including the terminating null byte),
94 irrespective of the provided buffer size.
95 .P
96 On error, \-1 is returned, and
97 .I errno
98 is set to indicate the error.
99 .SH VERSIONS
100 A wrapper is provided in the
101 .I libkeyutils
102 library:
103 .BR keyctl_describe (3).
104 .SH STANDARDS
105 Linux.
106 .SH HISTORY
107 Linux 2.6.10.
108 .SH SEE ALSO
109 .BR keyctl (2),
110 .BR keyctl_describe (3),
111 .BR keyctl_describe_alloc (3)