jpayne@68: .\"
jpayne@68: .\" Copyright (C) 2006 Red Hat, Inc. All Rights Reserved.
jpayne@68: .\" Written by David Howells (dhowells@redhat.com)
jpayne@68: .\"
jpayne@68: .\" This program is free software; you can redistribute it and/or
jpayne@68: .\" modify it under the terms of the GNU General Public License
jpayne@68: .\" as published by the Free Software Foundation; either version
jpayne@68: .\" 2 of the License, or (at your option) any later version.
jpayne@68: .\"
jpayne@68: .TH KEYCTL_READ 3 "21 Feb 2014" Linux "Linux Key Management Calls"
jpayne@68: .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
jpayne@68: .SH NAME
jpayne@68: keyctl_read \- read a key
jpayne@68: .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
jpayne@68: .SH SYNOPSIS
jpayne@68: .nf
jpayne@68: .B #include <keyutils.h>
jpayne@68: .sp
jpayne@68: .BI "long keyctl_read(key_serial_t " key ", char *" buffer ,
jpayne@68: .BI "size_t" buflen ");"
jpayne@68: .sp
jpayne@68: .BI "long keyctl_read_alloc(key_serial_t " key ", void **" _buffer ");"
jpayne@68: .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
jpayne@68: .SH DESCRIPTION
jpayne@68: .BR keyctl_read ()
jpayne@68: reads the payload of a key if the key type supports it.
jpayne@68: .P
jpayne@68: The caller must have
jpayne@68: .B read
jpayne@68: permission on a key to be able to read it.
jpayne@68: .P
jpayne@68: .I buffer
jpayne@68: and
jpayne@68: .I buflen
jpayne@68: specify the buffer into which the payload data will be placed.  If the buffer
jpayne@68: is too small, then the full size of the payload will be returned, and the
jpayne@68: contents of the buffer may be overwritten in some undefined way.
jpayne@68: .P
jpayne@68: .BR keyctl_read_alloc ()
jpayne@68: is similar to
jpayne@68: .BR keyctl_read ()
jpayne@68: except that it allocates a buffer big enough to hold the payload data and
jpayne@68: places the data in it.  If successful, a pointer to the buffer is placed in
jpayne@68: .IR *_buffer .
jpayne@68: The caller must free the buffer.
jpayne@68: .P
jpayne@68: .BR keyctl_read_alloc ()
jpayne@68: adds a NUL character after the data it retrieves, though this is not counted
jpayne@68: in the size value it returns.
jpayne@68: .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
jpayne@68: .SH READING KEYRINGS
jpayne@68: This call can be used to list the contents of a keyring.  The data is
jpayne@68: presented to the user as an array of
jpayne@68: .B key_serial_t
jpayne@68: values, each of which corresponds to a key to which the keyring holds a link.
jpayne@68: .P
jpayne@68: The size of the keyring will be sizeof(key_serial_t) multiplied by the number
jpayne@68: of keys.  The size of key_serial_t is invariant across different word sizes,
jpayne@68: though the byte-ordering is as appropriate for the kernel.
jpayne@68: .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
jpayne@68: .SH RETURN VALUE
jpayne@68: On success
jpayne@68: .BR keyctl_read ()
jpayne@68: returns the amount of data placed into the buffer.  If the buffer was too
jpayne@68: small, then the size of buffer required will be returned, and the contents of
jpayne@68: the buffer may have been overwritten in some undefined way.
jpayne@68: .P
jpayne@68: On success
jpayne@68: .BR keyctl_read_alloc ()
jpayne@68: returns the amount of data in the buffer.
jpayne@68: .P
jpayne@68: On error, both functions set
jpayne@68: .I errno
jpayne@68: to an appropriate code and return the value
jpayne@68: .BR -1 .
jpayne@68: .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
jpayne@68: .SH ERRORS
jpayne@68: .TP
jpayne@68: .B ENOKEY
jpayne@68: The key specified is invalid.
jpayne@68: .TP
jpayne@68: .B EKEYEXPIRED
jpayne@68: The key specified has expired.
jpayne@68: .TP
jpayne@68: .B EKEYREVOKED
jpayne@68: The key specified had been revoked.
jpayne@68: .TP
jpayne@68: .B EACCES
jpayne@68: The key exists, but is not
jpayne@68: .B readable
jpayne@68: by the calling process.
jpayne@68: .TP
jpayne@68: .B EOPNOTSUPP
jpayne@68: The key type does not support reading of the payload data.
jpayne@68: .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
jpayne@68: .SH LINKING
jpayne@68: This is a library function that can be found in
jpayne@68: .IR libkeyutils .
jpayne@68: When linking,
jpayne@68: .B \-lkeyutils
jpayne@68: should be specified to the linker.
jpayne@68: .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
jpayne@68: .SH SEE ALSO
jpayne@68: .ad l
jpayne@68: .nh
jpayne@68: .BR keyctl (1),
jpayne@68: .BR add_key (2),
jpayne@68: .BR keyctl (2),
jpayne@68: .BR request_key (2),
jpayne@68: .BR keyctl (3),
jpayne@68: .BR keyrings (7),
jpayne@68: .BR keyutils (7)