Debian Codegraph @

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