man/sd_event_add_inotify.xml

   1 <?xml version='1.0'?>
   2 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
   3   "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
   4 <!-- SPDX-License-Identifier: LGPL-2.1-or-later -->
   5
   6 <refentry id="sd_event_add_inotify" xmlns:xi="http://www.w3.org/2001/XInclude">
   7
   8   <refentryinfo>
   9     <title>sd_event_add_inotify</title>
  10     <productname>systemd</productname>
  11   </refentryinfo>
  12
  13   <refmeta>
  14     <refentrytitle>sd_event_add_inotify</refentrytitle>
  15     <manvolnum>3</manvolnum>
  16   </refmeta>
  17
  18   <refnamediv>
  19     <refname>sd_event_add_inotify</refname>
  20     <refname>sd_event_add_inotify_fd</refname>
  21     <refname>sd_event_source_get_inotify_mask</refname>
  22     <refname>sd_event_inotify_handler_t</refname>
  23
  24     <refpurpose>Add an "inotify" file system inode event source to an event loop</refpurpose>
  25   </refnamediv>
  26
  27   <refsynopsisdiv>
  28     <funcsynopsis>
  29       <funcsynopsisinfo>#include &lt;systemd/sd-event.h&gt;</funcsynopsisinfo>
  30
  31       <funcsynopsisinfo><token>typedef</token> struct sd_event_source sd_event_source;</funcsynopsisinfo>
  32
  33       <funcprototype>
  34         <funcdef>typedef int (*<function>sd_event_inotify_handler_t</function>)</funcdef>
  35         <paramdef>sd_event_source *<parameter>s</parameter></paramdef>
  36         <paramdef>const struct inotify_event *<parameter>event</parameter></paramdef>
  37         <paramdef>void *<parameter>userdata</parameter></paramdef>
  38       </funcprototype>
  39
  40       <funcprototype>
  41         <funcdef>int <function>sd_event_add_inotify</function></funcdef>
  42         <paramdef>sd_event *<parameter>event</parameter></paramdef>
  43         <paramdef>sd_event_source **<parameter>source</parameter></paramdef>
  44         <paramdef>const char *<parameter>path</parameter></paramdef>
  45         <paramdef>uint32_t <parameter>mask</parameter></paramdef>
  46         <paramdef>sd_event_inotify_handler_t <parameter>handler</parameter></paramdef>
  47         <paramdef>void *<parameter>userdata</parameter></paramdef>
  48       </funcprototype>
  49
  50       <funcprototype>
  51         <funcdef>int <function>sd_event_add_inotify_fd</function></funcdef>
  52         <paramdef>sd_event *<parameter>event</parameter></paramdef>
  53         <paramdef>sd_event_source **<parameter>source</parameter></paramdef>
  54         <paramdef>int <parameter>fd</parameter></paramdef>
  55         <paramdef>uint32_t <parameter>mask</parameter></paramdef>
  56         <paramdef>sd_event_inotify_handler_t <parameter>handler</parameter></paramdef>
  57         <paramdef>void *<parameter>userdata</parameter></paramdef>
  58       </funcprototype>
  59
  60       <funcprototype>
  61         <funcdef>int <function>sd_event_source_get_inotify_mask</function></funcdef>
  62         <paramdef>sd_event_source *<parameter>source</parameter></paramdef>
  63         <paramdef>uint32_t *<parameter>mask</parameter></paramdef>
  64       </funcprototype>
  65
  66     </funcsynopsis>
  67   </refsynopsisdiv>
  68
  69   <refsect1>
  70     <title>Description</title>
  71
  72     <para><function>sd_event_add_inotify()</function> adds a new <citerefentry
  73     project='man-pages'><refentrytitle>inotify</refentrytitle><manvolnum>7</manvolnum></citerefentry> file
  74     system inode event source to an event loop. The event loop object is specified in the
  75     <parameter>event</parameter> parameter, the event source object is returned in the
  76     <parameter>source</parameter> parameter. The <parameter>path</parameter> parameter specifies the path of
  77     the file system inode to watch. The <parameter>mask</parameter> parameter specifies which types of inode
  78     events to watch specifically. It must contain an OR-ed combination of <constant>IN_ACCESS</constant>,
  79     <constant>IN_ATTRIB</constant>, <constant>IN_CLOSE_WRITE</constant>, … flags. See <citerefentry
  80     project='man-pages'><refentrytitle>inotify</refentrytitle><manvolnum>7</manvolnum></citerefentry> for
  81     further information.</para>
  82
  83     <para>The <parameter>handler</parameter> must reference a function to call when the inode changes or
  84     <constant>NULL</constant>. The handler function will be passed the <parameter>userdata</parameter> pointer,
  85     which may be chosen freely by the caller. The handler also receives a pointer to a <structname>struct
  86     inotify_event</structname> structure containing information about the inode event. The handler may return
  87     negative to signal an error (see below), other return values are ignored. If
  88     <parameter>handler</parameter> is <constant>NULL</constant>, a default handler that calls
  89     <citerefentry><refentrytitle>sd_event_exit</refentrytitle><manvolnum>3</manvolnum></citerefentry> will be
  90     used.</para>
  91
  92     <para><function>sd_event_add_inotify_fd()</function> is identical to
  93     <function>sd_event_add_inotify()</function>, except that it takes a file descriptor to an inode (possibly
  94     an <constant>O_PATH</constant> one, but any other will do too) instead of a path in the file system.
  95     </para>
  96
  97     <para>If multiple event sources are installed for the same inode the backing inotify watch descriptor is
  98     automatically shared. The mask parameter may contain any flag defined by the inotify API, with the exception of
  99     <constant>IN_MASK_ADD</constant>.</para>
 100
 101     <para>The handler is enabled continuously (<constant>SD_EVENT_ON</constant>), but this may be changed with
 102     <citerefentry><refentrytitle>sd_event_source_set_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
 103     Alternatively, the <constant>IN_ONESHOT</constant> mask flag may be used to request
 104     <constant>SD_EVENT_ONESHOT</constant> mode. If the handler function returns a negative error code, it
 105     will be disabled after the invocation, even if the <constant>SD_EVENT_ON</constant> mode was requested
 106     before.</para>
 107
 108     <para>As a special limitation the priority of inotify event sources may only be altered (see
 109     <citerefentry><refentrytitle>sd_event_source_set_priority</refentrytitle><manvolnum>3</manvolnum></citerefentry>)
 110     in the time between creation of the event source object with <function>sd_event_add_inotify()</function> and the
 111     beginning of the next event loop iteration. Attempts of changing the priority any later will be refused. Consider
 112     freeing and allocating a new inotify event source to change the priority at that point.</para>
 113
 114     <para>To destroy an event source object use
 115     <citerefentry><refentrytitle>sd_event_source_unref</refentrytitle><manvolnum>3</manvolnum></citerefentry>, but note
 116     that the event source is only removed from the event loop when all references to the event source are dropped. To
 117     make sure an event source does not fire anymore, even when there's still a reference to it kept, consider disabling
 118     it with
 119     <citerefentry><refentrytitle>sd_event_source_set_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para>
 120
 121     <para>If the second parameter of <function>sd_event_add_inotify()</function> is passed as
 122     <constant>NULL</constant> no reference to the event source object is returned. In this case the event
 123     source is considered "floating", and will be destroyed implicitly when the event loop itself is
 124     destroyed.</para>
 125
 126     <para>If the <parameter>handler</parameter> parameter to <function>sd_event_add_inotify()</function> is
 127     <constant>NULL</constant>, and the event source fires, this will be considered a request to exit the
 128     event loop. In this case, the <parameter>userdata</parameter> parameter, cast to an integer, is passed as
 129     the exit code parameter to
 130     <citerefentry><refentrytitle>sd_event_exit</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para>
 131
 132     <para><function>sd_event_source_get_inotify_mask()</function> retrieves the configured inotify watch mask of an
 133     event source created previously with <function>sd_event_add_inotify()</function>. It takes the event source object
 134     as the <parameter>source</parameter> parameter and a pointer to a <type>uint32_t</type> variable to return the mask
 135     in.</para>
 136   </refsect1>
 137
 138   <refsect1>
 139     <title>Return Value</title>
 140
 141     <para>On success, these functions return 0 or a positive integer. On failure, they return a negative errno-style
 142     error code.</para>
 143
 144     <refsect2>
 145       <title>Errors</title>
 146
 147       <para>Returned errors may indicate the following problems:</para>
 148
 149       <variablelist>
 150         <varlistentry>
 151           <term><constant>-ENOMEM</constant></term>
 152
 153           <listitem><para>Not enough memory to allocate an object.</para></listitem>
 154         </varlistentry>
 155
 156         <varlistentry>
 157           <term><constant>-EINVAL</constant></term>
 158
 159           <listitem><para>An invalid argument has been passed. This includes specifying a mask with
 160           <constant>IN_MASK_ADD</constant> set.</para></listitem>
 161         </varlistentry>
 162
 163         <varlistentry>
 164           <term><constant>-ESTALE</constant></term>
 165
 166           <listitem><para>The event loop is already terminated.</para></listitem>
 167
 168         </varlistentry>
 169
 170         <varlistentry>
 171           <term><constant>-ECHILD</constant></term>
 172
 173           <listitem><para>The event loop has been created in a different process, library or module instance.</para></listitem>
 174
 175         </varlistentry>
 176
 177         <varlistentry>
 178           <term><constant>-EDOM</constant></term>
 179
 180           <listitem><para>The passed event source is not an inotify process event source.</para></listitem>
 181         </varlistentry>
 182
 183         <varlistentry>
 184           <term><constant>-EBADF</constant></term>
 185
 186           <listitem><para>The passed file descriptor is not valid.</para>
 187
 188           <xi:include href="version-info.xml" xpointer="v250"/></listitem>
 189         </varlistentry>
 190
 191         <varlistentry>
 192           <term><constant>-ENOSYS</constant></term>
 193
 194           <listitem><para><function>sd_event_add_inotify_fd()</function> was called without
 195           <filename>/proc/</filename> mounted.</para>
 196
 197           <xi:include href="version-info.xml" xpointer="v250"/></listitem>
 198         </varlistentry>
 199
 200       </variablelist>
 201     </refsect2>
 202   </refsect1>
 203
 204   <refsect1>
 205     <title>Examples</title>
 206
 207     <example>
 208       <title>A simple program that uses inotify to monitor one or two directories</title>
 209
 210       <programlisting><xi:include href="inotify-watch-tmp.c" parse="text" /></programlisting>
 211     </example>
 212   </refsect1>
 213
 214   <xi:include href="libsystemd-pkgconfig.xml" />
 215
 216   <refsect1>
 217     <title>History</title>
 218     <para><function>sd_event_inotify_handler_t()</function>,
 219     <function>sd_event_add_inotify()</function>, and
 220     <function>sd_event_source_get_inotify_mask()</function> were added in version 239.</para>
 221     <para><function>sd_event_add_inotify_fd()</function> was added in version 250.</para>
 222   </refsect1>
 223
 224   <refsect1>
 225     <title>See Also</title>
 226
 227     <para>
 228       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 229       <citerefentry><refentrytitle>sd-event</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 230       <citerefentry><refentrytitle>sd_event_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 231       <citerefentry><refentrytitle>sd_event_now</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 232       <citerefentry><refentrytitle>sd_event_add_io</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 233       <citerefentry><refentrytitle>sd_event_add_time</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 234       <citerefentry><refentrytitle>sd_event_add_signal</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 235       <citerefentry><refentrytitle>sd_event_add_defer</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 236       <citerefentry><refentrytitle>sd_event_add_child</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 237       <citerefentry><refentrytitle>sd_event_source_set_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 238       <citerefentry><refentrytitle>sd_event_source_set_priority</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 239       <citerefentry><refentrytitle>sd_event_source_set_userdata</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 240       <citerefentry><refentrytitle>sd_event_source_set_description</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 241       <citerefentry><refentrytitle>sd_event_source_set_floating</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 242       <citerefentry project='man-pages'><refentrytitle>waitid</refentrytitle><manvolnum>2</manvolnum></citerefentry>
 243     </para>
 244   </refsect1>
 245
 246 </refentry>