.\"
.\" Copyright (C) 2019 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_GRANT_PERMISSION 3 "28 Aug 2019" Linux "Linux Key Management Calls"
.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.SH NAME
keyctl_watch_key \- Watch for changes to a key
.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.SH SYNOPSIS
.nf
.B #include <keyutils.h>
.sp
.BI "long keyctl_watch_key(key_serial_t " key ,
.BI "                      int " watch_queue_fd
.BI "                      int " watch_id ");"
.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.SH DESCRIPTION
.BR keyctl_watch_key ()
sets or removes a watch on
.IR key .
.PP
.I watch_id
specifies the ID for a watch that will be included in notification messages.
It can be between 0 and 255 to add a key; it should be -1 to remove a key.
.PP
.I watch_queue_fd
is a file descriptor attached to a watch_queue device instance.  Multiple
openings of a device provide separate instances.  Each device instance can
only have one watch on any particular key.
.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.SS Notification Record
.PP
Key-specific notification messages that the kernel emits into the buffer have
the following format:
.PP
.in +4n
.EX
struct key_notification {
	struct watch_notification watch;
	__u32	key_id;
	__u32	aux;
};
.EE
.in
.PP
The
.I watch.type
field will be set to
.B WATCH_TYPE_KEY_NOTIFY
and the
.I watch.subtype
field will contain one of the following constants, indicating the event that
occurred and the watch_id passed to keyctl_watch_key() will be placed in
.I watch.info
in the ID field.  The following events are defined:
.TP
.B NOTIFY_KEY_INSTANTIATED
This indicates that a watched key got instantiated or negatively instantiated.
.I key_id
indicates the key that was instantiated and
.I aux
is unused.
.TP
.B NOTIFY_KEY_UPDATED
This indicates that a watched key got updated or instantiated by update.
.I key_id
indicates the key that was updated and
.I aux
is unused.
.TP
.B NOTIFY_KEY_LINKED
This indicates that a key got linked into a watched keyring.
.I key_id
indicates the keyring that was modified
.I aux
indicates the key that was added.
.TP
.B NOTIFY_KEY_UNLINKED
This indicates that a key got unlinked from a watched keyring.
.I key_id
indicates the keyring that was modified
.I aux
indicates the key that was removed.
.TP
.B NOTIFY_KEY_CLEARED
This indicates that a watched keyring got cleared.
.I key_id
indicates the keyring that was cleared and
.I aux
is unused.
.TP
.B NOTIFY_KEY_REVOKED
This indicates that a watched key got revoked.
.I key_id
indicates the key that was revoked and
.I aux
is unused.
.TP
.B NOTIFY_KEY_INVALIDATED
This indicates that a watched key got invalidated.
.I key_id
indicates the key that was invalidated and
.I aux
is unused.
.TP
.B NOTIFY_KEY_SETATTR
This indicates that a watched key had its attributes (owner, group,
permissions, timeout) modified.
.I key_id
indicates the key that was modified and
.I aux
is unused.
.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.SS Removal Notification
When a watched key is garbage collected, all of its watches are automatically
destroyed and a notification is delivered to each watcher.  This will normally
be an extended notification of the form:
.PP
.in +4n
.EX
struct watch_notification_removal {
	struct watch_notification watch;
	__u64	id;
};
.EE
.in
.PP
The
.I watch.type
field will be set to
.B WATCH_TYPE_META
and the
.I watch.subtype
field will contain
.BR WATCH_META_REMOVAL_NOTIFICATION .
If the extended notification is given, then the length will be 2 units,
otherwise it will be 1 and only the header will be present.
.PP
The watch_id passed to
.IR keyctl_watch_key ()
will be placed in
.I watch.info
in the ID field.
.PP
If the extension is present,
.I id
will be set to the ID of the destroyed key.
.PP
.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.SH RETURN VALUE
On success
.BR keyctl_watch_key ()
returns
.B 0 .
On error, the value
.B -1
will be returned and
.I errno
will have been set to an appropriate error.
.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.SH ERRORS
.TP
.B ENOKEY
The specified key does not exist.
.TP
.B EKEYEXPIRED
The specified key has expired.
.TP
.B EKEYREVOKED
The specified key has been revoked.
.TP
.B EACCES
The named key exists, but does not grant
.B view
permission to the calling process.
.TP
.B EBUSY
The specified key already has a watch on it for that device instance (add
only).
.TP
.B EBADSLT
The specified key doesn't have a watch on it (removal only).
.\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.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
.ad l
.nh
.BR keyctl (1),
.BR add_key (2),
.BR keyctl (2),
.BR request_key (2),
.BR keyctl (3),
.BR keyrings (7),
.BR keyutils (7)