KEYCTL\_GRANT\_PERMISSION(3) Linux Key Management Calls KEYCTL\_GRANT\_PERMISSION(3) # [NAME](#NAME) keyctl\_watch\_key - Watch for changes to a key # [SYNOPSIS](#SYNOPSIS) ``` #include long keyctl_watch_key(key_serial_t key, int watch_queue_fd int watch_id); ``` # [DESCRIPTION](#DESCRIPTION) **keyctl\_watch\_key**() sets or removes a watch on *key*. *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. *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. ## [Notification Record](#Notification_Record) Key-specific notification messages that the kernel emits into the buffer have the following format: ``` struct key_notification { struct watch_notification watch; __u32 key_id; __u32 aux; }; ``` The *watch.type* field will be set to **WATCH\_TYPE\_KEY\_NOTIFY** and the *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 *watch.info* in the ID field. The following events are defined: [**NOTIFY\_KEY\_INSTANTIATED**](#NOTIFY_KEY_INSTANTIATED) This indicates that a watched key got instantiated or negatively instantiated. *key\_id* indicates the key that was instantiated and *aux* is unused. [**NOTIFY\_KEY\_UPDATED**](#NOTIFY_KEY_UPDATED) This indicates that a watched key got updated or instantiated by update. *key\_id* indicates the key that was updated and *aux* is unused. [**NOTIFY\_KEY\_LINKED**](#NOTIFY_KEY_LINKED) This indicates that a key got linked into a watched keyring. *key\_id* indicates the keyring that was modified *aux* indicates the key that was added. [**NOTIFY\_KEY\_UNLINKED**](#NOTIFY_KEY_UNLINKED) This indicates that a key got unlinked from a watched keyring. *key\_id* indicates the keyring that was modified *aux* indicates the key that was removed. [**NOTIFY\_KEY\_CLEARED**](#NOTIFY_KEY_CLEARED) This indicates that a watched keyring got cleared. *key\_id* indicates the keyring that was cleared and *aux* is unused. [**NOTIFY\_KEY\_REVOKED**](#NOTIFY_KEY_REVOKED) This indicates that a watched key got revoked. *key\_id* indicates the key that was revoked and *aux* is unused. [**NOTIFY\_KEY\_INVALIDATED**](#NOTIFY_KEY_INVALIDATED) This indicates that a watched key got invalidated. *key\_id* indicates the key that was invalidated and *aux* is unused. [**NOTIFY\_KEY\_SETATTR**](#NOTIFY_KEY_SETATTR) This indicates that a watched key had its attributes (owner, group, permissions, timeout) modified. *key\_id* indicates the key that was modified and *aux* is unused. ## [Removal Notification](#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: ``` struct watch_notification_removal { struct watch_notification watch; __u64 id; }; ``` The *watch.type* field will be set to **WATCH\_TYPE\_META** and the *watch.subtype* field will contain **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. The watch\_id passed to *keyctl\_watch\_key*() will be placed in *watch.info* in the ID field. If the extension is present, *id* will be set to the ID of the destroyed key. # [RETURN VALUE](#RETURN_VALUE) On success **keyctl\_watch\_key**() returns **0 .** On error, the value **-1** will be returned and *errno* will have been set to an appropriate error. # [ERRORS](#ERRORS) [**ENOKEY**](#ENOKEY) The specified key does not exist. [**EKEYEXPIRED**](#EKEYEXPIRED) The specified key has expired. [**EKEYREVOKED**](#EKEYREVOKED) The specified key has been revoked. [**EACCES**](#EACCES) The named key exists, but does not grant **view** permission to the calling process. [**EBUSY**](#EBUSY) The specified key already has a watch on it for that device instance (add only). [**EBADSLT**](#EBADSLT) The specified key doesn't have a watch on it (removal only). # [LINKING](#LINKING) This is a library function that can be found in *libkeyutils*. When linking, **-lkeyutils** should be specified to the linker. # [SEE ALSO](#SEE_ALSO) [**keyctl**(1)](/man/os/keyutils/keyctl.1), [**add\_key**(2)](/man/os/keyutils/add_key.2), [**keyctl**(2)](/man/os/keyutils/keyctl.2), [**request\_key**(2)](/man/os/keyutils/request_key.2), [**keyctl**(3)](/man/os/keyutils/keyctl.3), [**keyrings**(7)](/man/os/keyutils/keyrings.7), [**keyutils**(7)](/man/os/keyutils/keyutils.7) 28 Aug 2019 Linux --- Document: keyctl_watch_key(3) from keyutils 1.6.3-r40 (Chainguard OS) Source: https://kernel.googlesource.com/pub/scm/linux/kernel/git/dhowells/keyutils.git