# keyctl_watch_key

## NAME



           keyctl_watch_key - Watch for changes to a key
    


## SYNOPSIS



           **#include <keyutils.h>**
    
           **long keyctl_watch_key(key_serial_t** _key_**,**
                                 **int** _watch_queue_fd_
                                 **int** _watch_id_**);**
    


## 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**
           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**
                  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**
                  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**
                  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**
                  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**
                  This indicates that a watched keyring got cleared.  _key_id_
                  indicates the keyring that was cleared and _aux_ is unused.
    
           **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**
                  This indicates that a watched key got invalidated.  _key_id_
                  indicates the key that was invalidated and _aux_ is unused.
    
           **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**
           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



           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



           **ENOKEY** The specified key does not exist.
    
           **EKEYEXPIRED**
                  The specified key has expired.
    
           **EKEYREVOKED**
                  The specified key has been revoked.
    
           **EACCES** The named key exists, but does not grant **view** permission to
                  the calling process.
    
           **EBUSY** The specified key already has a watch on it for that device
                  instance (add only).
    
           **EBADSLT**
                  The specified key doesn't have a watch on it (removal
                  only).
    


## LINKING



           This is a library function that can be found in _libkeyutils_.  When
           linking, **-lkeyutils** should be specified to the linker.
    


* * *