diff options
Diffstat (limited to 'keyutils-1.5.6/recursive_key_scan.3')
| -rw-r--r-- | keyutils-1.5.6/recursive_key_scan.3 | 87 |
1 files changed, 87 insertions, 0 deletions
diff --git a/keyutils-1.5.6/recursive_key_scan.3 b/keyutils-1.5.6/recursive_key_scan.3 new file mode 100644 index 0000000..c07be85 --- /dev/null +++ b/keyutils-1.5.6/recursive_key_scan.3 @@ -0,0 +1,87 @@ +.\" +.\" Copyright (C) 2011 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 Licence +.\" as published by the Free Software Foundation; either version +.\" 2 of the Licence, or (at your option) any later version. +.\" +.TH RECURSIVE_KEY_SCAN 3 "10 Mar 2011" Linux "Linux Key Utility Calls" +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH NAME +recursive_key_scan \- Apply a function to all keys in a keyring tree +.br +recursive_session_key_scan \- Apply a function to all keys in the session keyring tree +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH SYNOPSIS +.nf +.B #include <keyutils.h> +.sp +.BI "typedef int (*" recursive_key_scanner_t ")(key_serial_t " parent , +.BI " key_serial_t " key ", char *" desc ", int " desc_len ", void *" data ");" +.sp +.BI "long recursive_key_scan(key_serial_t " keyring , +.BI " recursive_key_scanner_t " func ", void *" data ");" +.br +.BI "long recursive_session_key_scan(recursive_key_scanner_t " func , +.BI " void *" data ");" +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH DESCRIPTION +.BR recursive_key_scan () +performs a depth-first recursive scan of the specified +.I keyring +tree and applies +.I func +to every link found in the accessible keyrings in that tree. +.I data +is passed to each invocation of func. +.P +The return values of +.I func +are summed and returned as the overall return value. Errors are ignored. +Inaccessible keyrings are not scanned, but links to them are still passed to +func. +.P +.BR recursive_session_key_scan () +works exactly like +.IR recursive_key_scan () +with the caller's session keyring specified as the starting keyring. +.P +The callback function is called for each link found in all the keyrings in the +nominated tree and so may be called multiple times for a particular key if that +key has multiple links to it. +.P +The callback function is passed the following parameters: +.TP +.B parent +The keyring containing the link or 0 for the initial key. +.TP +.BR key +The key to which the link points. +.TP +.BR desc " and " desc_len +A pointer to the raw description and its length as retrieved with +.IR keyctl_describe_alloc (). +These will be NULL and -1 respectively if the description couldn't be +retrieved and errno will retain the error from +.IR keyctl_describe_alloc (). +.TP +.B data +The data passed to the scanner function. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH RETURN VALUE +These functions return the sum of the results of the callback functions they +invoke. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH ERRORS +Ignored. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH LINKING +When linking, +.B -lkeyutils +should be specified to the linker. +.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +.SH SEE ALSO +.BR keyctl (3), +.BR keyctl_describe_alloc (3) |