--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/CSP2/CSP2_env/env-d9b9114564458d9d-741b3de822f2aaca6c6caa4325c4afce/share/man/man3/keyctl_describe.3	Tue Mar 18 16:23:26 2025 -0400
@@ -0,0 +1,112 @@
+.\"
+.\" Copyright (C) 2006 Red Hat, Inc. All Rights Reserved.
+.\" Written by David Howells (dhowells@redhat.com)
+.\"
+.\" This program is free software; you can redistribute it and/or
+.\" modify it under the terms of the GNU General Public License
+.\" as published by the Free Software Foundation; either version
+.\" 2 of the License, or (at your option) any later version.
+.\"
+.TH KEYCTL_DESCRIBE 3 "4 May 2006" Linux "Linux Key Management Calls"
+.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.SH NAME
+keyctl_describe \- describe a key
+.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.SH SYNOPSIS
+.nf
+.B #include <keyutils.h>
+.sp
+.BI "long keyctl_describe(key_serial_t " key ", char *" buffer ,
+.BI "size_t" buflen ");"
+.sp
+.BI "long keyctl_describe_alloc(key_serial_t " key ", char **" _buffer ");"
+.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.SH DESCRIPTION
+.BR keyctl_describe ()
+describes the attributes of a key as a NUL-terminated string.
+.P
+The caller must have
+.B view
+permission on a key to be able to get a description of it.
+.P
+.I buffer
+and
+.I buflen
+specify the buffer into which the key description will be placed.  If the
+buffer is too small, the full size of the description will be returned, and no
+copy will take place.
+.P
+.BR keyctl_describe_alloc ()
+is similar to
+.BR keyctl_describe ()
+except that it allocates a buffer big enough to hold the description and
+places the description in it.  If successful, A pointer to the buffer is
+placed in
+.IR *_buffer .
+The caller must free the buffer.
+.P
+The description will be a string of format:
+.IP
+.B "\*(lq%s;%d;%d;%08x;%s\*(rq"
+.P
+where the arguments are: key type name, key UID, key GID, key permissions mask
+and key description.
+.P
+.B NOTE!
+The key description will not contain any semicolons, so that should be
+separated out by working backwards from the end of the string.  This permits
+extra information to be inserted before it by later versions of the kernel
+simply by inserting more semicolon-terminated substrings.
+.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.SH RETURN VALUE
+On success
+.BR keyctl_describe ()
+returns the amount of data placed into the buffer.  If the buffer was too
+small, then the size of buffer required will be returned, but no data will be
+transferred.  On error, the value
+.B -1
+will be returned and
+.I errno
+will have been set to an appropriate error.
+.P
+On success
+.BR keyctl_describe_alloc ()
+returns the amount of data in the buffer, less the NUL terminator.  On error, the value
+.B -1
+will be returned and
+.I errno
+will have been set to an appropriate error.
+.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.SH ERRORS
+.TP
+.B ENOKEY
+The key specified is invalid.
+.TP
+.B EKEYEXPIRED
+The key specified has expired.
+.TP
+.B EKEYREVOKED
+The key specified had been revoked.
+.TP
+.B EACCES
+The key exists, but is not
+.B viewable
+by the calling process.
+.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.SH LINKING
+This is a library function that can be found in
+.IR libkeyutils .
+When linking,
+.B \-lkeyutils
+should be specified to the linker.
+.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.SH SEE ALSO
+.ad l
+.nh
+.BR keyctl (1),
+.BR add_key (2),
+.BR keyctl (2),
+.BR request_key (2),
+.BR keyctl (3),
+.BR keyrings (7),
+.BR keyutils (7)