keyctl_update.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_UPDATE 3 "4 May 2006" Linux "Linux Key Management Calls"
  11 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
  12 .SH NAME
  13 keyctl_update \- Update a key
  14 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
  15 .SH SYNOPSIS
  16 .nf
  17 .B #include <keyutils.h>
  18 .sp
  19 .BI "long keyctl_update(key_serial_t " key ", const void *" payload ,
  20 .BI "size_t " plen ");"
  21 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
  22 .SH DESCRIPTION
  23 .BR keyctl_update ()
  24 updates the payload of a key if the key type permits it.
  25 .P
  26 The caller must have
  27 .B write
  28 permission on a key to be able update it.
  29 .P
  30 .I payload
  31 and
  32 .I plen
  33 specify the data for the new payload.
  34 .I payload
  35 may be NULL and
  36 .I plen
  37 may be zero if the key type permits that.  The key type may reject the data if
  38 it's in the wrong format or in some other way invalid.
  39 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
  40 .SH RETURN VALUE
  41 On success
  42 .BR keyctl_update ()
  43 returns
  44 .BR 0 .
  45 On error, the value
  46 .B -1
  47 will be returned and errno will have been set to an appropriate error.
  48 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
  49 .SH ERRORS
  50 .TP
  51 .B ENOKEY
  52 The key specified is invalid.
  53 .TP
  54 .B EKEYEXPIRED
  55 The key specified has expired.
  56 .TP
  57 .B EKEYREVOKED
  58 The key specified had been revoked.
  59 .TP
  60 .B EINVAL
  61 The payload data was invalid.
  62 .TP
  63 .B ENOMEM
  64 Insufficient memory to store the new payload.
  65 .TP
  66 .B EDQUOT
  67 The key quota for this user would be exceeded by increasing the size of the
  68 key to accommodate the new payload.
  69 .TP
  70 .B EACCES
  71 The key exists, but is not
  72 .B writable
  73 by the calling process.
  74 .TP
  75 .B EOPNOTSUPP
  76 The key type does not support the update operation on its keys.
  77 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
  78 .SH LINKING
  79 This is a library function that can be found in
  80 .IR libkeyutils .
  81 When linking,
  82 .B -lkeyutils
  83 should be specified to the linker.
  84 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
  85 .SH SEE ALSO
  86 .BR keyctl (1),
  87 .br
  88 .BR add_key (2),
  89 .br
  90 .BR keyctl (2),
  91 .br
  92 .BR request_key (2),
  93 .br
  94 .BR keyctl (3),
  95 .br
  96 .BR request-key (8)