keyctl_join_session_keyring.3

   1 .\"
   2 .\" Copyright (C) 2006 Red Hat, Inc. All Rights Reserved.
   3 .\" Written by David Howells (dhowells@redhat.com)
   4 .\"
   5 .\" This program is free software; you can redistribute it and/or
   6 .\" modify it under the terms of the GNU General Public License
   7 .\" as published by the Free Software Foundation; either version
   8 .\" 2 of the License, or (at your option) any later version.
   9 .\"
  10 .TH KEYCTL_JOIN_SESSION_KEYRING 3 "4 May 2006" Linux "Linux Key Management Calls"
  11 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
  12 .SH NAME
  13 keyctl_join_session_keyring \- Join a different session keyring
  14 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
  15 .SH SYNOPSIS
  16 .nf
  17 .B #include <keyutils.h>
  18 .sp
  19 .BI "key_serial_t keyctl_join_session_keyring(const char *" name ");"
  20 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
  21 .SH DESCRIPTION
  22 .BR keyctl_join_session_keyring ()
  23 changes the session keyring to which a process is subscribed.
  24 .P
  25 If
  26 .I name
  27 is
  28 .B NULL
  29 then a new anonymous keyring will be created, and the process will be
  30 subscribed to that.
  31 .P
  32 If
  33 .I name
  34 points to a string, then if a keyring of that name is available, the process
  35 will attempt to subscribe to that keyring, giving an error if that is not
  36 permitted; otherwise a new keyring of that name is created and attached as the
  37 session keyring.
  38 .P
  39 To attach to an extant named keyring, the keyring must have
  40 .B search
  41 permission available to the calling process.
  42 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
  43 .SH RETURN VALUE
  44 On success
  45 .BR keyctl_join_session_keyring ()
  46 returns the serial number of the key it found or created.  On error, the value
  47 .B -1
  48 will be returned and errno will have been set to an appropriate error.
  49 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
  50 .SH ERRORS
  51 .TP
  52 .B ENOMEM
  53 Insufficient memory to create a key.
  54 .TP
  55 .B EDQUOT
  56 The key quota for this user would be exceeded by creating this key or linking
  57 it to the keyring.
  58 .TP
  59 .B EACCES
  60 The named keyring exists, but is not
  61 .B searchable
  62 by the calling process.
  63 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
  64 .SH LINKING
  65 This is a library function that can be found in
  66 .IR libkeyutils .
  67 When linking,
  68 .B -lkeyutils
  69 should be specified to the linker.
  70 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
  71 .SH SEE ALSO
  72 .BR keyctl (1),
  73 .br
  74 .BR add_key (2),
  75 .br
  76 .BR keyctl (2),
  77 .br
  78 .BR request_key (2),
  79 .br
  80 .BR keyctl (3),
  81 .br
  82 .BR request-key (8)