diff options
Diffstat (limited to 'keyutils-1.5.6/keyctl_describe.3')
| -rw-r--r-- | keyutils-1.5.6/keyctl_describe.3 | 110 |
1 files changed, 110 insertions, 0 deletions
diff --git a/keyutils-1.5.6/keyctl_describe.3 b/keyutils-1.5.6/keyctl_describe.3 new file mode 100644 index 0000000..e125ab8 --- /dev/null +++ b/keyutils-1.5.6/keyctl_describe.3 @@ -0,0 +1,110 @@ +.\" +.\" 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 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 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 +.BR keyctl (1), +.br +.BR add_key (2), +.br +.BR keyctl (2), +.br +.BR request_key (2), +.br +.BR keyctl (3), +.br +.BR request-key (8) |