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)