sphinx.addnodesdocument)}( rawsourcechildren]( translations LanguagesNode)}(hhh](h pending_xref)}(hhh]docutils.nodesTextChinese (Simplified)}parenthsba attributes}(ids]classes]names]dupnames]backrefs] refdomainstdreftypedoc reftarget(/translations/zh_CN/core-api/watch_queuemodnameN classnameN refexplicitutagnamehhh ubh)}(hhh]hChinese (Traditional)}hh2sbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget(/translations/zh_TW/core-api/watch_queuemodnameN classnameN refexplicituh1hhh ubh)}(hhh]hItalian}hhFsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget(/translations/it_IT/core-api/watch_queuemodnameN classnameN refexplicituh1hhh ubh)}(hhh]hJapanese}hhZsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget(/translations/ja_JP/core-api/watch_queuemodnameN classnameN refexplicituh1hhh ubh)}(hhh]hKorean}hhnsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget(/translations/ko_KR/core-api/watch_queuemodnameN classnameN refexplicituh1hhh ubh)}(hhh]hPortuguese (Brazilian)}hhsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget(/translations/pt_BR/core-api/watch_queuemodnameN classnameN refexplicituh1hhh ubh)}(hhh]hSpanish}hhsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget(/translations/sp_SP/core-api/watch_queuemodnameN classnameN refexplicituh1hhh ubeh}(h]h ]h"]h$]h&]current_languageEnglishuh1h hh _documenthsourceNlineNubhsection)}(hhh](htitle)}(hGeneral notification mechanismh]hGeneral notification mechanism}(hhhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhhhB/var/lib/git/docbuild/linux/Documentation/core-api/watch_queue.rsthKubh paragraph)}(hThe general notification mechanism is built on top of the standard pipe driver whereby it effectively splices notification messages from the kernel into pipes opened by userspace. This can be used in conjunction with::h]hThe general notification mechanism is built on top of the standard pipe driver whereby it effectively splices notification messages from the kernel into pipes opened by userspace. This can be used in conjunction with:}(hhhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhhhhubh literal_block)}(h* Key/keyring notificationsh]h* Key/keyring notifications}hhsbah}(h]h ]h"]h$]h&] xml:spacepreserveuh1hhhhK hhhhubh)}(h,The notifications buffers can be enabled by:h]h,The notifications buffers can be enabled by:}(hhhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK hhhhubh block_quote)}(hB"General setup"/"General notification queue" (CONFIG_WATCH_QUEUE) h]h)}(hA"General setup"/"General notification queue" (CONFIG_WATCH_QUEUE)h]hI“General setup”/”General notification queue” (CONFIG_WATCH_QUEUE)}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhhubah}(h]h ]h"]h$]h&]uh1hhhhKhhhhubh)}(h)This document has the following sections:h]h)This document has the following sections:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhhhhubhtopic)}(hhh]h bullet_list)}(hhh](h list_item)}(hhh]h)}(hhh]h reference)}(hhh]hOverview}(hj7hhhNhNubah}(h]id1ah ]h"]h$]h&]refidoverviewuh1j5hj2ubah}(h]h ]h"]h$]h&]uh1hhj/ubah}(h]h ]h"]h$]h&]uh1j-hj*ubj.)}(hhh]h)}(hhh]j6)}(hhh]hMessage Structure}(hjYhhhNhNubah}(h]id2ah ]h"]h$]h&]refidmessage-structureuh1j5hjVubah}(h]h ]h"]h$]h&]uh1hhjSubah}(h]h ]h"]h$]h&]uh1j-hj*ubj.)}(hhh]h)}(hhh]j6)}(hhh]h$Watch List (Notification Source) API}(hj{hhhNhNubah}(h]id3ah ]h"]h$]h&]refid"watch-list-notification-source-apiuh1j5hjxubah}(h]h ]h"]h$]h&]uh1hhjuubah}(h]h ]h"]h$]h&]uh1j-hj*ubj.)}(hhh]h)}(hhh]j6)}(hhh]h%Watch Queue (Notification Output) API}(hjhhhNhNubah}(h]id4ah ]h"]h$]h&]refid#watch-queue-notification-output-apiuh1j5hjubah}(h]h ]h"]h$]h&]uh1hhjubah}(h]h ]h"]h$]h&]uh1j-hj*ubj.)}(hhh]h)}(hhh]j6)}(hhh]hWatch Subscription API}(hjhhhNhNubah}(h]id5ah ]h"]h$]h&]refidwatch-subscription-apiuh1j5hjubah}(h]h ]h"]h$]h&]uh1hhjubah}(h]h ]h"]h$]h&]uh1j-hj*ubj.)}(hhh]h)}(hhh]j6)}(hhh]hNotification Posting API}(hjhhhNhNubah}(h]id6ah ]h"]h$]h&]refidnotification-posting-apiuh1j5hjubah}(h]h ]h"]h$]h&]uh1hhjubah}(h]h ]h"]h$]h&]uh1j-hj*ubj.)}(hhh]h)}(hhh]j6)}(hhh]h Watch Sources}(hjhhhNhNubah}(h]id7ah ]h"]h$]h&]refid watch-sourcesuh1j5hjubah}(h]h ]h"]h$]h&]uh1hhjubah}(h]h ]h"]h$]h&]uh1j-hj*ubj.)}(hhh]h)}(hhh]j6)}(hhh]hEvent Filtering}(hj%hhhNhNubah}(h]id8ah ]h"]h$]h&]refidevent-filteringuh1j5hj"ubah}(h]h ]h"]h$]h&]uh1hhjubah}(h]h ]h"]h$]h&]uh1j-hj*ubj.)}(hhh]h)}(hhh]j6)}(hhh]hUserspace Code Example}(hjGhhhNhNubah}(h]id9ah ]h"]h$]h&]refiduserspace-code-exampleuh1j5hjDubah}(h]h ]h"]h$]h&]uh1hhjAubah}(h]h ]h"]h$]h&]uh1j-hj*ubeh}(h]h ]h"]h$]h&]uh1j(hj%hhhNhNubah}(h]contentsah ](contentslocaleh"]contentsah$]h&]uh1j#hhhKhhhhubh)}(hhh](h)}(hOverviewh]hOverview}(hjvhhhNhNubah}(h]h ]h"]h$]h&]refidj@uh1hhjshhhhhKubh)}(hXThis facility appears as a pipe that is opened in a special mode. The pipe's internal ring buffer is used to hold messages that are generated by the kernel. These messages are then read out by read(). Splice and similar are disabled on such pipes due to them wanting to, under some circumstances, revert their additions to the ring - which might end up interleaved with notification messages.h]hXThis facility appears as a pipe that is opened in a special mode. The pipe’s internal ring buffer is used to hold messages that are generated by the kernel. These messages are then read out by read(). Splice and similar are disabled on such pipes due to them wanting to, under some circumstances, revert their additions to the ring - which might end up interleaved with notification messages.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjshhubh)}(hXThe owner of the pipe has to tell the kernel which sources it would like to watch through that pipe. Only sources that have been connected to a pipe will insert messages into it. Note that a source may be bound to multiple pipes and insert messages into all of them simultaneously.h]hXThe owner of the pipe has to tell the kernel which sources it would like to watch through that pipe. Only sources that have been connected to a pipe will insert messages into it. Note that a source may be bound to multiple pipes and insert messages into all of them simultaneously.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK hjshhubh)}(h|Filters may also be emplaced on a pipe so that certain source types and subevents can be ignored if they're not of interest.h]h~Filters may also be emplaced on a pipe so that certain source types and subevents can be ignored if they’re not of interest.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK%hjshhubh)}(hX"A message will be discarded if there isn't a slot available in the ring or if no preallocated message buffer is available. In both of these cases, read() will insert a WATCH_META_LOSS_NOTIFICATION message into the output buffer after the last message currently in the buffer has been read.h]hX$A message will be discarded if there isn’t a slot available in the ring or if no preallocated message buffer is available. In both of these cases, read() will insert a WATCH_META_LOSS_NOTIFICATION message into the output buffer after the last message currently in the buffer has been read.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK(hjshhubh)}(hX#Note that when producing a notification, the kernel does not wait for the consumers to collect it, but rather just continues on. This means that notifications can be generated whilst spinlocks are held and also protects the kernel from being held up indefinitely by a userspace malfunction.h]hX#Note that when producing a notification, the kernel does not wait for the consumers to collect it, but rather just continues on. This means that notifications can be generated whilst spinlocks are held and also protects the kernel from being held up indefinitely by a userspace malfunction.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK-hjshhubeh}(h]jFah ]h"]overviewah$]h&]uh1hhhhhhhhKubh)}(hhh](h)}(hMessage Structureh]hMessage Structure}(hjhhhNhNubah}(h]h ]h"]h$]h&]jjbuh1hhjhhhhhK4ubh)}(h1Notification messages begin with a short header::h]h0Notification messages begin with a short header:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK6hjhhubh)}(hhstruct watch_notification { __u32 type:24; __u32 subtype:8; __u32 info; };h]hhstruct watch_notification { __u32 type:24; __u32 subtype:8; __u32 info; };}hjsbah}(h]h ]h"]h$]h&]hhuh1hhhhK8hjhhubh)}(hX*"type" indicates the source of the notification record and "subtype" indicates the type of record from that source (see the Watch Sources section below). The type may also be "WATCH_TYPE_META". This is a special record type generated internally by the watch queue itself. There are two subtypes:h]hX6“type” indicates the source of the notification record and “subtype” indicates the type of record from that source (see the Watch Sources section below). The type may also be “WATCH_TYPE_META”. This is a special record type generated internally by the watch queue itself. There are two subtypes:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK>hjhhubh)}(hA* WATCH_META_REMOVAL_NOTIFICATION * WATCH_META_LOSS_NOTIFICATION h]j))}(hhh](j.)}(hWATCH_META_REMOVAL_NOTIFICATIONh]h)}(hjh]hWATCH_META_REMOVAL_NOTIFICATION}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKChjubah}(h]h ]h"]h$]h&]uh1j-hjubj.)}(hWATCH_META_LOSS_NOTIFICATION h]h)}(hWATCH_META_LOSS_NOTIFICATIONh]hWATCH_META_LOSS_NOTIFICATION}(hj/hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKDhj+ubah}(h]h ]h"]h$]h&]uh1j-hjubeh}(h]h ]h"]h$]h&]bullet*uh1j(hhhKChj ubah}(h]h ]h"]h$]h&]uh1hhhhKChjhhubh)}(hThe first indicates that an object on which a watch was installed was removed or destroyed and the second indicates that some messages have been lost.h]hThe first indicates that an object on which a watch was installed was removed or destroyed and the second indicates that some messages have been lost.}(hjQhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKFhjhhubh)}(h."info" indicates a bunch of things, including:h]h2“info” indicates a bunch of things, including:}(hj_hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKIhjhhubh)}(hXa* The length of the message in bytes, including the header (mask with WATCH_INFO_LENGTH and shift by WATCH_INFO_LENGTH__SHIFT). This indicates the size of the record, which may be between 8 and 127 bytes. * The watch ID (mask with WATCH_INFO_ID and shift by WATCH_INFO_ID__SHIFT). This indicates that caller's ID of the watch, which may be between 0 and 255. Multiple watches may share a queue, and this provides a means to distinguish them. * A type-specific field (WATCH_INFO_TYPE_INFO). This is set by the notification producer to indicate some meaning specific to the type and subtype. h]j))}(hhh](j.)}(hThe length of the message in bytes, including the header (mask with WATCH_INFO_LENGTH and shift by WATCH_INFO_LENGTH__SHIFT). This indicates the size of the record, which may be between 8 and 127 bytes. h]h)}(hThe length of the message in bytes, including the header (mask with WATCH_INFO_LENGTH and shift by WATCH_INFO_LENGTH__SHIFT). This indicates the size of the record, which may be between 8 and 127 bytes.h]hThe length of the message in bytes, including the header (mask with WATCH_INFO_LENGTH and shift by WATCH_INFO_LENGTH__SHIFT). This indicates the size of the record, which may be between 8 and 127 bytes.}(hjxhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKKhjtubah}(h]h ]h"]h$]h&]uh1j-hjqubj.)}(hThe watch ID (mask with WATCH_INFO_ID and shift by WATCH_INFO_ID__SHIFT). This indicates that caller's ID of the watch, which may be between 0 and 255. Multiple watches may share a queue, and this provides a means to distinguish them. h]h)}(hThe watch ID (mask with WATCH_INFO_ID and shift by WATCH_INFO_ID__SHIFT). This indicates that caller's ID of the watch, which may be between 0 and 255. Multiple watches may share a queue, and this provides a means to distinguish them.h]hThe watch ID (mask with WATCH_INFO_ID and shift by WATCH_INFO_ID__SHIFT). This indicates that caller’s ID of the watch, which may be between 0 and 255. Multiple watches may share a queue, and this provides a means to distinguish them.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKOhjubah}(h]h ]h"]h$]h&]uh1j-hjqubj.)}(hA type-specific field (WATCH_INFO_TYPE_INFO). This is set by the notification producer to indicate some meaning specific to the type and subtype. h]h)}(hA type-specific field (WATCH_INFO_TYPE_INFO). This is set by the notification producer to indicate some meaning specific to the type and subtype.h]hA type-specific field (WATCH_INFO_TYPE_INFO). This is set by the notification producer to indicate some meaning specific to the type and subtype.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKThjubah}(h]h ]h"]h$]h&]uh1j-hjqubeh}(h]h ]h"]h$]h&]jIjJuh1j(hhhKKhjmubah}(h]h ]h"]h$]h&]uh1hhhhKKhjhhubh)}(hCEverything in info apart from the length can be used for filtering.h]hCEverything in info apart from the length can be used for filtering.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKXhjhhubh)}(hThe header can be followed by supplementary information. The format of this is at the discretion is defined by the type and subtype.h]hThe header can be followed by supplementary information. The format of this is at the discretion is defined by the type and subtype.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKZhjhhubeh}(h]jhah ]h"]message structureah$]h&]uh1hhhhhhhhK4ubh)}(hhh](h)}(h$Watch List (Notification Source) APIh]h$Watch List (Notification Source) API}(hjhhhNhNubah}(h]h ]h"]h$]h&]jjuh1hhjhhhhhK_ubh)}(hXA "watch list" is a list of watchers that are subscribed to a source of notifications. A list may be attached to an object (say a key or a superblock) or may be global (say for device events). From a userspace perspective, a non-global watch list is typically referred to by reference to the object it belongs to (such as using KEYCTL_NOTIFY and giving it a key serial number to watch that specific key).h]hXA “watch list” is a list of watchers that are subscribed to a source of notifications. A list may be attached to an object (say a key or a superblock) or may be global (say for device events). From a userspace perspective, a non-global watch list is typically referred to by reference to the object it belongs to (such as using KEYCTL_NOTIFY and giving it a key serial number to watch that specific key).}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKahjhhubh)}(h=To manage a watch list, the following functions are provided:h]h=To manage a watch list, the following functions are provided:}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhhjhhubh)}(hX$* :: void init_watch_list(struct watch_list *wlist, void (*release_watch)(struct watch *wlist)); Initialise a watch list. If ``release_watch`` is not NULL, then this indicates a function that should be called when the watch_list object is destroyed to discard any references the watch list holds on the watched object. * ``void remove_watch_list(struct watch_list *wlist);`` This removes all of the watches subscribed to a watch_list and frees them and then destroys the watch_list object itself. h]j))}(hhh](j.)}(hX]:: void init_watch_list(struct watch_list *wlist, void (*release_watch)(struct watch *wlist)); Initialise a watch list. If ``release_watch`` is not NULL, then this indicates a function that should be called when the watch_list object is destroyed to discard any references the watch list holds on the watched object. h](h)}(hpvoid init_watch_list(struct watch_list *wlist, void (*release_watch)(struct watch *wlist));h]hpvoid init_watch_list(struct watch_list *wlist, void (*release_watch)(struct watch *wlist));}hj#sbah}(h]h ]h"]h$]h&]hhuh1hhhhKlhjubh)}(hInitialise a watch list. If ``release_watch`` is not NULL, then this indicates a function that should be called when the watch_list object is destroyed to discard any references the watch list holds on the watched object.h](hInitialise a watch list. If }(hj1hhhNhNubhliteral)}(h``release_watch``h]h release_watch}(hj;hhhNhNubah}(h]h ]h"]h$]h&]uh1j9hj1ubh is not NULL, then this indicates a function that should be called when the watch_list object is destroyed to discard any references the watch list holds on the watched object.}(hj1hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKohjubeh}(h]h ]h"]h$]h&]uh1j-hjubj.)}(h``void remove_watch_list(struct watch_list *wlist);`` This removes all of the watches subscribed to a watch_list and frees them and then destroys the watch_list object itself. h](h)}(h5``void remove_watch_list(struct watch_list *wlist);``h]j:)}(hj_h]h1void remove_watch_list(struct watch_list *wlist);}(hjahhhNhNubah}(h]h ]h"]h$]h&]uh1j9hj]ubah}(h]h ]h"]h$]h&]uh1hhhhKthjYubh)}(hyThis removes all of the watches subscribed to a watch_list and frees them and then destroys the watch_list object itself.h]hyThis removes all of the watches subscribed to a watch_list and frees them and then destroys the watch_list object itself.}(hjthhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKvhjYubeh}(h]h ]h"]h$]h&]uh1j-hjubeh}(h]h ]h"]h$]h&]jIjJuh1j(hhhKjhjubah}(h]h ]h"]h$]h&]uh1hhhhKjhjhhubeh}(h]jah ]h"]$watch list (notification source) apiah$]h&]uh1hhhhhhhhK_ubh)}(hhh](h)}(h%Watch Queue (Notification Output) APIh]h%Watch Queue (Notification Output) API}(hjhhhNhNubah}(h]h ]h"]h$]h&]jjuh1hhjhhhhhK{ubh)}(hXA "watch queue" is the buffer allocated by an application that notification records will be written into. The workings of this are hidden entirely inside of the pipe device driver, but it is necessary to gain a reference to it to set a watch. These can be managed with:h]hXA “watch queue” is the buffer allocated by an application that notification records will be written into. The workings of this are hidden entirely inside of the pipe device driver, but it is necessary to gain a reference to it to set a watch. These can be managed with:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK}hjhhubh)}(hX* ``struct watch_queue *get_watch_queue(int fd);`` Since watch queues are indicated to the kernel by the fd of the pipe that implements the buffer, userspace must hand that fd through a system call. This can be used to look up an opaque pointer to the watch queue from the system call. * ``void put_watch_queue(struct watch_queue *wqueue);`` This discards the reference obtained from ``get_watch_queue()``. h]j))}(hhh](j.)}(hX``struct watch_queue *get_watch_queue(int fd);`` Since watch queues are indicated to the kernel by the fd of the pipe that implements the buffer, userspace must hand that fd through a system call. This can be used to look up an opaque pointer to the watch queue from the system call. h](h)}(h0``struct watch_queue *get_watch_queue(int fd);``h]j:)}(hjh]h,struct watch_queue *get_watch_queue(int fd);}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j9hjubah}(h]h ]h"]h$]h&]uh1hhhhKhjubh)}(hSince watch queues are indicated to the kernel by the fd of the pipe that implements the buffer, userspace must hand that fd through a system call. This can be used to look up an opaque pointer to the watch queue from the system call.h]hSince watch queues are indicated to the kernel by the fd of the pipe that implements the buffer, userspace must hand that fd through a system call. This can be used to look up an opaque pointer to the watch queue from the system call.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjubeh}(h]h ]h"]h$]h&]uh1j-hjubj.)}(hy``void put_watch_queue(struct watch_queue *wqueue);`` This discards the reference obtained from ``get_watch_queue()``. h](h)}(h5``void put_watch_queue(struct watch_queue *wqueue);``h]j:)}(hjh]h1void put_watch_queue(struct watch_queue *wqueue);}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j9hjubah}(h]h ]h"]h$]h&]uh1hhhhKhjubh)}(h@This discards the reference obtained from ``get_watch_queue()``.h](h*This discards the reference obtained from }(hj hhhNhNubj:)}(h``get_watch_queue()``h]hget_watch_queue()}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j9hj ubh.}(hj hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjubeh}(h]h ]h"]h$]h&]uh1j-hjubeh}(h]h ]h"]h$]h&]jIjJuh1j(hhhKhjubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubeh}(h]jah ]h"]%watch queue (notification output) apiah$]h&]uh1hhhhhhhhK{ubh)}(hhh](h)}(hWatch Subscription APIh]hWatch Subscription API}(hjGhhhNhNubah}(h]h ]h"]h$]h&]jjuh1hhjDhhhhhKubh)}(hX(A "watch" is a subscription on a watch list, indicating the watch queue, and thus the buffer, into which notification records should be written. The watch queue object may also carry filtering rules for that object, as set by userspace. Some parts of the watch struct can be set by the driver::h]hX+A “watch” is a subscription on a watch list, indicating the watch queue, and thus the buffer, into which notification records should be written. The watch queue object may also carry filtering rules for that object, as set by userspace. Some parts of the watch struct can be set by the driver:}(hjUhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjDhhubh)}(hXEstruct watch { union { u32 info_id; /* ID to be OR'd in to info field */ ... }; void *private; /* Private data for the watched object */ u64 id; /* Internal identifier */ ... };h]hXEstruct watch { union { u32 info_id; /* ID to be OR'd in to info field */ ... }; void *private; /* Private data for the watched object */ u64 id; /* Internal identifier */ ... };}hjcsbah}(h]h ]h"]h$]h&]hhuh1hhhhKhjDhhubh)}(hX The ``info_id`` value should be an 8-bit number obtained from userspace and shifted by WATCH_INFO_ID__SHIFT. This is OR'd into the WATCH_INFO_ID field of struct watch_notification::info when and if the notification is written into the associated watch queue buffer.h](hThe }(hjqhhhNhNubj:)}(h ``info_id``h]hinfo_id}(hjyhhhNhNubah}(h]h ]h"]h$]h&]uh1j9hjqubh value should be an 8-bit number obtained from userspace and shifted by WATCH_INFO_ID__SHIFT. This is OR’d into the WATCH_INFO_ID field of struct watch_notification::info when and if the notification is written into the associated watch queue buffer.}(hjqhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjDhhubh)}(hThe ``private`` field is the driver's data associated with the watch_list and is cleaned up by the ``watch_list::release_watch()`` method.h](hThe }(hjhhhNhNubj:)}(h ``private``h]hprivate}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j9hjubhV field is the driver’s data associated with the watch_list and is cleaned up by the }(hjhhhNhNubj:)}(h``watch_list::release_watch()``h]hwatch_list::release_watch()}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j9hjubh method.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjDhhubh)}(hdThe ``id`` field is the source's ID. Notifications that are posted with a different ID are ignored.h](hThe }(hjhhhNhNubj:)}(h``id``h]hid}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j9hjubh\ field is the source’s ID. Notifications that are posted with a different ID are ignored.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjDhhubh)}(h7The following functions are provided to manage watches:h]h7The following functions are provided to manage watches:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjDhhubh)}(hX* ``void init_watch(struct watch *watch, struct watch_queue *wqueue);`` Initialise a watch object, setting its pointer to the watch queue, using appropriate barriering to avoid lockdep complaints. * ``int add_watch_to_object(struct watch *watch, struct watch_list *wlist);`` Subscribe a watch to a watch list (notification source). The driver-settable fields in the watch struct must have been set before this is called. * :: int remove_watch_from_object(struct watch_list *wlist, struct watch_queue *wqueue, u64 id, false); Remove a watch from a watch list, where the watch must match the specified watch queue (``wqueue``) and object identifier (``id``). A notification (``WATCH_META_REMOVAL_NOTIFICATION``) is sent to the watch queue to indicate that the watch got removed. * ``int remove_watch_from_object(struct watch_list *wlist, NULL, 0, true);`` Remove all the watches from a watch list. It is expected that this will be called preparatory to destruction and that the watch list will be inaccessible to new watches by this point. A notification (``WATCH_META_REMOVAL_NOTIFICATION``) is sent to the watch queue of each subscribed watch to indicate that the watch got removed. h]j))}(hhh](j.)}(h``void init_watch(struct watch *watch, struct watch_queue *wqueue);`` Initialise a watch object, setting its pointer to the watch queue, using appropriate barriering to avoid lockdep complaints. h](h)}(hE``void init_watch(struct watch *watch, struct watch_queue *wqueue);``h]j:)}(hjh]hAvoid init_watch(struct watch *watch, struct watch_queue *wqueue);}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j9hjubah}(h]h ]h"]h$]h&]uh1hhhhKhjubh)}(h|Initialise a watch object, setting its pointer to the watch queue, using appropriate barriering to avoid lockdep complaints.h]h|Initialise a watch object, setting its pointer to the watch queue, using appropriate barriering to avoid lockdep complaints.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjubeh}(h]h ]h"]h$]h&]uh1j-hjubj.)}(h``int add_watch_to_object(struct watch *watch, struct watch_list *wlist);`` Subscribe a watch to a watch list (notification source). The driver-settable fields in the watch struct must have been set before this is called. h](h)}(hK``int add_watch_to_object(struct watch *watch, struct watch_list *wlist);``h]j:)}(hj-h]hGint add_watch_to_object(struct watch *watch, struct watch_list *wlist);}(hj/hhhNhNubah}(h]h ]h"]h$]h&]uh1j9hj+ubah}(h]h ]h"]h$]h&]uh1hhhhKhj'ubh)}(hSubscribe a watch to a watch list (notification source). The driver-settable fields in the watch struct must have been set before this is called.h]hSubscribe a watch to a watch list (notification source). The driver-settable fields in the watch struct must have been set before this is called.}(hjBhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhj'ubeh}(h]h ]h"]h$]h&]uh1j-hjubj.)}(hX:: int remove_watch_from_object(struct watch_list *wlist, struct watch_queue *wqueue, u64 id, false); Remove a watch from a watch list, where the watch must match the specified watch queue (``wqueue``) and object identifier (``id``). A notification (``WATCH_META_REMOVAL_NOTIFICATION``) is sent to the watch queue to indicate that the watch got removed. h](h)}(hint remove_watch_from_object(struct watch_list *wlist, struct watch_queue *wqueue, u64 id, false);h]hint remove_watch_from_object(struct watch_list *wlist, struct watch_queue *wqueue, u64 id, false);}hjZsbah}(h]h ]h"]h$]h&]hhuh1hhhhKhjVubh)}(hRemove a watch from a watch list, where the watch must match the specified watch queue (``wqueue``) and object identifier (``id``). A notification (``WATCH_META_REMOVAL_NOTIFICATION``) is sent to the watch queue to indicate that the watch got removed.h](hXRemove a watch from a watch list, where the watch must match the specified watch queue (}(hjhhhhNhNubj:)}(h ``wqueue``h]hwqueue}(hjphhhNhNubah}(h]h ]h"]h$]h&]uh1j9hjhubh) and object identifier (}(hjhhhhNhNubj:)}(h``id``h]hid}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j9hjhubh). A notification (}(hjhhhhNhNubj:)}(h#``WATCH_META_REMOVAL_NOTIFICATION``h]hWATCH_META_REMOVAL_NOTIFICATION}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j9hjhubhD) is sent to the watch queue to indicate that the watch got removed.}(hjhhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjVubeh}(h]h ]h"]h$]h&]uh1j-hjubj.)}(hX``int remove_watch_from_object(struct watch_list *wlist, NULL, 0, true);`` Remove all the watches from a watch list. It is expected that this will be called preparatory to destruction and that the watch list will be inaccessible to new watches by this point. A notification (``WATCH_META_REMOVAL_NOTIFICATION``) is sent to the watch queue of each subscribed watch to indicate that the watch got removed. h](h)}(hJ``int remove_watch_from_object(struct watch_list *wlist, NULL, 0, true);``h]j:)}(hjh]hFint remove_watch_from_object(struct watch_list *wlist, NULL, 0, true);}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j9hjubah}(h]h ]h"]h$]h&]uh1hhhhKhjubh)}(hXJRemove all the watches from a watch list. It is expected that this will be called preparatory to destruction and that the watch list will be inaccessible to new watches by this point. A notification (``WATCH_META_REMOVAL_NOTIFICATION``) is sent to the watch queue of each subscribed watch to indicate that the watch got removed.h](hRemove all the watches from a watch list. It is expected that this will be called preparatory to destruction and that the watch list will be inaccessible to new watches by this point. A notification (}(hjhhhNhNubj:)}(h#``WATCH_META_REMOVAL_NOTIFICATION``h]hWATCH_META_REMOVAL_NOTIFICATION}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j9hjubh]) is sent to the watch queue of each subscribed watch to indicate that the watch got removed.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjubeh}(h]h ]h"]h$]h&]uh1j-hjubeh}(h]h ]h"]h$]h&]jIjJuh1j(hhhKhjubah}(h]h ]h"]h$]h&]uh1hhhhKhjDhhubeh}(h]jah ]h"]watch subscription apiah$]h&]uh1hhhhhhhhKubh)}(hhh](h)}(hNotification Posting APIh]hNotification Posting API}(hj hhhNhNubah}(h]h ]h"]h$]h&]jjuh1hhjhhhhhKubh)}(hwTo post a notification to watch list so that the subscribed watches can see it, the following function should be used::h]hvTo post a notification to watch list so that the subscribed watches can see it, the following function should be used:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubh)}(hvoid post_watch_notification(struct watch_list *wlist, struct watch_notification *n, const struct cred *cred, u64 id);h]hvoid post_watch_notification(struct watch_list *wlist, struct watch_notification *n, const struct cred *cred, u64 id);}hj%sbah}(h]h ]h"]h$]h&]hhuh1hhhhKhjhhubh)}(hThe notification should be preformatted and a pointer to the header (``n``) should be passed in. The notification may be larger than this and the size in units of buffer slots is noted in ``n->info & WATCH_INFO_LENGTH``.h](hEThe notification should be preformatted and a pointer to the header (}(hj3hhhNhNubj:)}(h``n``h]hn}(hj;hhhNhNubah}(h]h ]h"]h$]h&]uh1j9hj3ubhs) should be passed in. The notification may be larger than this and the size in units of buffer slots is noted in }(hj3hhhNhNubj:)}(h``n->info & WATCH_INFO_LENGTH``h]hn->info & WATCH_INFO_LENGTH}(hjMhhhNhNubah}(h]h ]h"]h$]h&]uh1j9hj3ubh.}(hj3hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjhhubh)}(hThe ``cred`` struct indicates the credentials of the source (subject) and is passed to the LSMs, such as SELinux, to allow or suppress the recording of the note in each individual queue according to the credentials of that queue (object).h](hThe }(hjehhhNhNubj:)}(h``cred``h]hcred}(hjmhhhNhNubah}(h]h ]h"]h$]h&]uh1j9hjeubh struct indicates the credentials of the source (subject) and is passed to the LSMs, such as SELinux, to allow or suppress the recording of the note in each individual queue according to the credentials of that queue (object).}(hjehhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjhhubh)}(hThe ``id`` is the ID of the source object (such as the serial number on a key). Only watches that have the same ID set in them will see this notification.h](hThe }(hjhhhNhNubj:)}(h``id``h]hid}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j9hjubh is the ID of the source object (such as the serial number on a key). Only watches that have the same ID set in them will see this notification.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjhhubeh}(h]jah ]h"]notification posting apiah$]h&]uh1hhhhhhhhKubh)}(hhh](h)}(h Watch Sourcesh]h Watch Sources}(hjhhhNhNubah}(h]h ]h"]h$]h&]jj uh1hhjhhhhhKubh)}(hIAny particular buffer can be fed from multiple sources. Sources include:h]hIAny particular buffer can be fed from multiple sources. Sources include:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubh)}(h* WATCH_TYPE_KEY_NOTIFY Notifications of this type indicate changes to keys and keyrings, including the changes of keyring contents or the attributes of keys. See Documentation/security/keys/core.rst for more information. h]j))}(hhh]j.)}(hWATCH_TYPE_KEY_NOTIFY Notifications of this type indicate changes to keys and keyrings, including the changes of keyring contents or the attributes of keys. See Documentation/security/keys/core.rst for more information. h](h)}(hWATCH_TYPE_KEY_NOTIFYh]hWATCH_TYPE_KEY_NOTIFY}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjubh)}(hNotifications of this type indicate changes to keys and keyrings, including the changes of keyring contents or the attributes of keys.h]hNotifications of this type indicate changes to keys and keyrings, including the changes of keyring contents or the attributes of keys.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjubh)}(h>See Documentation/security/keys/core.rst for more information.h]h>See Documentation/security/keys/core.rst for more information.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjubeh}(h]h ]h"]h$]h&]uh1j-hjubah}(h]h ]h"]h$]h&]jIjJuh1j(hhhKhjubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubeh}(h]jah ]h"] watch sourcesah$]h&]uh1hhhhhhhhKubh)}(hhh](h)}(hEvent Filteringh]hEvent Filtering}(hjhhhNhNubah}(h]h ]h"]h$]h&]jj.uh1hhjhhhhhKubh)}(hrOnce a watch queue has been created, a set of filters can be applied to limit the events that are received using::h]hqOnce a watch queue has been created, a set of filters can be applied to limit the events that are received using:}(hj*hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubh)}(histruct watch_notification_filter filter = { ... }; ioctl(fd, IOC_WATCH_QUEUE_SET_FILTER, &filter)h]histruct watch_notification_filter filter = { ... }; ioctl(fd, IOC_WATCH_QUEUE_SET_FILTER, &filter)}hj8sbah}(h]h ]h"]h$]h&]hhuh1hhhhKhjhhubh)}(h.The filter description is a variable of type::h]h-The filter description is a variable of type:}(hjFhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubh)}(hstruct watch_notification_filter { __u32 nr_filters; __u32 __reserved; struct watch_notification_type_filter filters[]; };h]hstruct watch_notification_filter { __u32 nr_filters; __u32 __reserved; struct watch_notification_type_filter filters[]; };}hjTsbah}(h]h ]h"]h$]h&]hhuh1hhhhKhjhhubh)}(hWhere "nr_filters" is the number of filters in filters[] and "__reserved" should be 0. The "filters" array has elements of the following type::h]hWhere “nr_filters” is the number of filters in filters[] and “__reserved” should be 0. The “filters” array has elements of the following type:}(hjbhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjhhubh)}(hstruct watch_notification_type_filter { __u32 type; __u32 info_filter; __u32 info_mask; __u32 subtype_filter[8]; };h]hstruct watch_notification_type_filter { __u32 type; __u32 info_filter; __u32 info_mask; __u32 subtype_filter[8]; };}hjpsbah}(h]h ]h"]h$]h&]hhuh1hhhhMhjhhubh)}(hWhere:h]hWhere:}(hj~hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjhhubh)}(hXI* ``type`` is the event type to filter for and should be something like "WATCH_TYPE_KEY_NOTIFY" * ``info_filter`` and ``info_mask`` act as a filter on the info field of the notification record. The notification is only written into the buffer if:: (watch.info & info_mask) == info_filter This could be used, for example, to ignore events that are not exactly on the watched point in a mount tree. * ``subtype_filter`` is a bitmask indicating the subtypes that are of interest. Bit 0 of subtype_filter[0] corresponds to subtype 0, bit 1 to subtype 1, and so on. h]j))}(hhh](j.)}(h^``type`` is the event type to filter for and should be something like "WATCH_TYPE_KEY_NOTIFY" h]h)}(h]``type`` is the event type to filter for and should be something like "WATCH_TYPE_KEY_NOTIFY"h](j:)}(h``type``h]htype}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j9hjubhY is the event type to filter for and should be something like “WATCH_TYPE_KEY_NOTIFY”}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhjubah}(h]h ]h"]h$]h&]uh1j-hjubj.)}(hX2``info_filter`` and ``info_mask`` act as a filter on the info field of the notification record. The notification is only written into the buffer if:: (watch.info & info_mask) == info_filter This could be used, for example, to ignore events that are not exactly on the watched point in a mount tree. h](h)}(h``info_filter`` and ``info_mask`` act as a filter on the info field of the notification record. The notification is only written into the buffer if::h](j:)}(h``info_filter``h]h info_filter}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j9hjubh and }(hjhhhNhNubj:)}(h ``info_mask``h]h info_mask}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1j9hjubht act as a filter on the info field of the notification record. The notification is only written into the buffer if:}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhjubh)}(h'(watch.info & info_mask) == info_filterh]h'(watch.info & info_mask) == info_filter}hjsbah}(h]h ]h"]h$]h&]hhuh1hhhhMhjubh)}(hlThis could be used, for example, to ignore events that are not exactly on the watched point in a mount tree.h]hlThis could be used, for example, to ignore events that are not exactly on the watched point in a mount tree.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjubeh}(h]h ]h"]h$]h&]uh1j-hjubj.)}(h``subtype_filter`` is a bitmask indicating the subtypes that are of interest. Bit 0 of subtype_filter[0] corresponds to subtype 0, bit 1 to subtype 1, and so on. h]h)}(h``subtype_filter`` is a bitmask indicating the subtypes that are of interest. Bit 0 of subtype_filter[0] corresponds to subtype 0, bit 1 to subtype 1, and so on.h](j:)}(h``subtype_filter``h]hsubtype_filter}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1j9hj ubh is a bitmask indicating the subtypes that are of interest. Bit 0 of subtype_filter[0] corresponds to subtype 0, bit 1 to subtype 1, and so on.}(hj hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhj ubah}(h]h ]h"]h$]h&]uh1j-hjubeh}(h]h ]h"]h$]h&]jIjJuh1j(hhhMhjubah}(h]h ]h"]h$]h&]uh1hhhhMhjhhubh)}(hIf the argument to the ioctl() is NULL, then the filters will be removed and all events from the watched sources will come through.h]hIf the argument to the ioctl() is NULL, then the filters will be removed and all events from the watched sources will come through.}(hj? hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjhhubeh}(h]j4ah ]h"]event filteringah$]h&]uh1hhhhhhhhKubh)}(hhh](h)}(hUserspace Code Exampleh]hUserspace Code Example}(hjW hhhNhNubah}(h]h ]h"]h$]h&]jjPuh1hhjT hhhhhM$ubh)}(h7A buffer is created with something like the following::h]h6A buffer is created with something like the following:}(hje hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM&hjT hhubh)}(hDpipe2(fds, O_TMPFILE); ioctl(fds[1], IOC_WATCH_QUEUE_SET_SIZE, 256);h]hDpipe2(fds, O_TMPFILE); ioctl(fds[1], IOC_WATCH_QUEUE_SET_SIZE, 256);}hjs sbah}(h]h ]h"]h$]h&]hhuh1hhhhM(hjT hhubh)}(hstatic void consumer(int rfd, struct watch_queue_buffer *buf) { unsigned char buffer[128]; ssize_t buf_len; while (buf_len = read(rfd, buffer, sizeof(buffer)), buf_len > 0 ) { void *p = buffer; void *end = buffer + buf_len; while (p < end) { union { struct watch_notification n; unsigned char buf1[128]; } n; size_t largest, len; largest = end - p; if (largest > 128) largest = 128; memcpy(&n, p, largest); len = (n->info & WATCH_INFO_LENGTH) >> WATCH_INFO_LENGTH__SHIFT; if (len == 0 || len > largest) return; switch (n.n.type) { case WATCH_TYPE_META: got_meta(&n.n); case WATCH_TYPE_KEY_NOTIFY: saw_key_change(&n.n); break; } p += len; } } }h]hX>static void consumer(int rfd, struct watch_queue_buffer *buf) { unsigned char buffer[128]; ssize_t buf_len; while (buf_len = read(rfd, buffer, sizeof(buffer)), buf_len > 0 ) { void *p = buffer; void *end = buffer + buf_len; while (p < end) { union { struct watch_notification n; unsigned char buf1[128]; } n; size_t largest, len; largest = end - p; if (largest > 128) largest = 128; memcpy(&n, p, largest); len = (n->info & WATCH_INFO_LENGTH) >> WATCH_INFO_LENGTH__SHIFT; if (len == 0 || len > largest) return; switch (n.n.type) { case WATCH_TYPE_META: got_meta(&n.n); case WATCH_TYPE_KEY_NOTIFY: saw_key_change(&n.n); break; } p += len; } } }}hj sbah}(h]h ]h"]h$]h&]hhuh1hhhhM1hjT hhubeh}(h]jVah ]h"]userspace code exampleah$]h&]uh1hhhhhhhhM$ubeh}(h]general-notification-mechanismah ]h"]general notification mechanismah$]h&]uh1hhhhhhhhKubeh}(h]h ]h"]h$]h&]sourcehuh1hcurrent_sourceN current_lineNsettingsdocutils.frontendValues)}(hN generatorN datestampN source_linkN source_urlN toc_backlinksentryfootnote_backlinksK sectnum_xformKstrip_commentsNstrip_elements_with_classesN strip_classesN report_levelK halt_levelKexit_status_levelKdebugNwarning_streamN tracebackinput_encoding utf-8-siginput_encoding_error_handlerstrictoutput_encodingutf-8output_encoding_error_handlerj error_encodingutf-8error_encoding_error_handlerbackslashreplace language_codeenrecord_dependenciesNconfigN id_prefixhauto_id_prefixid dump_settingsNdump_internalsNdump_transformsNdump_pseudo_xmlNexpose_internalsNstrict_visitorN_disable_configN_sourcehʌ _destinationN _config_files]7/var/lib/git/docbuild/linux/Documentation/docutils.confafile_insertion_enabled raw_enabledKline_length_limitM'pep_referencesN pep_base_urlhttps://peps.python.org/pep_file_url_templatepep-%04drfc_referencesN rfc_base_url&https://datatracker.ietf.org/doc/html/ tab_widthKtrim_footnote_reference_spacesyntax_highlightlong smart_quotessmartquotes_locales]character_level_inline_markupdoctitle_xform docinfo_xformKsectsubtitle_xform image_loadinglinkembed_stylesheetcloak_email_addressessection_self_linkenvNubreporterNindirect_targets]substitution_defs}substitution_names}refnames}refids}nameids}(j j jpjkjjFjjhjjjAjjjjjjjjQ j4j jVu nametypes}(j jpjjjjAjjjjQ j uh}(j hjkj%jFjsjhjjjjjjjDjjjjj4jjVjT j@j7jbjYjj{jjjjjjj jj.j%jPjGu footnote_refs} citation_refs} autofootnotes]autofootnote_refs]symbol_footnotes]symbol_footnote_refs] footnotes] citations]autofootnote_startKsymbol_footnote_startK id_counter collectionsCounter}j K sRparse_messages]transform_messages] transformerN include_log] decorationNhhub.