1 files changed, 109 insertions, 0 deletions
diff --git a/keyutils-1.5.6/keyctl_read.3 b/keyutils-1.5.6/keyctl_read.3
new file mode 100644
index 0000000..01905e5
--- /dev/null
+++ b/keyutils-1.5.6/keyctl_read.3
@@ -0,0 +1,109 @@
+.\"
+.\" 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_READ 3 "4 May 2006" Linux "Linux Key Management Calls"
+.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.SH NAME
+keyctl_read \- Read a key
+.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.SH SYNOPSIS
+.nf
+.B #include <keyutils.h>
+.sp
+.BI "long keyctl_read(key_serial_t " key ", char *" buffer ,
+.BI "size_t" buflen ");"
+.sp
+.BI "long keyctl_read_alloc(key_serial_t " key ", void **" _buffer ");"
+.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.SH DESCRIPTION
+.BR keyctl_read ()
+reads the payload of a key if the key type supports it.
+.P
+The caller must have
+.B read
+permission on a key to be able to read it.
+.P
+.I buffer
+and
+.I buflen
+specify the buffer into which the payload data will be placed.  If the buffer
+is too small, the full size of the payload will be returned, and no copy will
+take place.
+.P
+.BR keyctl_read_alloc ()
+is similar to
+.BR keyctl_read ()
+except that it allocates a buffer big enough to hold the payload data and
+places the data in it.  If successful, A pointer to the buffer is placed in
+.IR *_buffer .
+The caller must free the buffer.
+.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.SH READING KEYRINGS
+This call can be used to list the contents of a keyring.  The data is
+presented to the user as an array of
+.B key_serial_t
+values, each of which corresponds to a key to which the keyring holds a link.
+.P
+The size of the keyring will be sizeof(key_serial_t) multiplied by the number
+of keys.  The size of key_serial_t is invariant across different word sizes,
+though the byte-ordering is as appropriate for the kernel.
+.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.SH RETURN VALUE
+On success
+.BR keyctl_read ()
+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_read_alloc ()
+returns the amount of data in the buffer.  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 readable
+by the calling process.
+.TP
+.B EOPNOTSUPP
+The key type does not support reading of the payload data.
+.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.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)