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.

SEE ALSO

       keyctl(1), add_key(2), keyctl(2), request_key(2), keyctl(3), keyrings(7), keyutils(7)