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 <systemd/sd-event.h></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.</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></listitem> 187 </varlistentry> 188 189 <varlistentry> 190 <term><constant>-ENOSYS</constant></term> 191 192 <listitem><para><function>sd_event_add_inotify_fd()</function> was called without 193 <filename>/proc/</filename> mounted.</para></listitem> 194 </varlistentry> 195 196 </variablelist> 197 </refsect2> 198 </refsect1> 199 200 <refsect1> 201 <title>Examples</title> 202 203 <example> 204 <title>A simple program that uses inotify to monitor one or two directories</title> 205 206 <programlisting><xi:include href="inotify-watch-tmp.c" parse="text" /></programlisting> 207 </example> 208 </refsect1> 209 210 <xi:include href="libsystemd-pkgconfig.xml" /> 211 212 <refsect1> 213 <title>See Also</title> 214 215 <para> 216 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, 217 <citerefentry><refentrytitle>sd-event</refentrytitle><manvolnum>3</manvolnum></citerefentry>, 218 <citerefentry><refentrytitle>sd_event_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>, 219 <citerefentry><refentrytitle>sd_event_now</refentrytitle><manvolnum>3</manvolnum></citerefentry>, 220 <citerefentry><refentrytitle>sd_event_add_io</refentrytitle><manvolnum>3</manvolnum></citerefentry>, 221 <citerefentry><refentrytitle>sd_event_add_time</refentrytitle><manvolnum>3</manvolnum></citerefentry>, 222 <citerefentry><refentrytitle>sd_event_add_signal</refentrytitle><manvolnum>3</manvolnum></citerefentry>, 223 <citerefentry><refentrytitle>sd_event_add_defer</refentrytitle><manvolnum>3</manvolnum></citerefentry>, 224 <citerefentry><refentrytitle>sd_event_add_child</refentrytitle><manvolnum>3</manvolnum></citerefentry>, 225 <citerefentry><refentrytitle>sd_event_source_set_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>, 226 <citerefentry><refentrytitle>sd_event_source_set_priority</refentrytitle><manvolnum>3</manvolnum></citerefentry>, 227 <citerefentry><refentrytitle>sd_event_source_set_userdata</refentrytitle><manvolnum>3</manvolnum></citerefentry>, 228 <citerefentry><refentrytitle>sd_event_source_set_description</refentrytitle><manvolnum>3</manvolnum></citerefentry>, 229 <citerefentry><refentrytitle>sd_event_source_set_floating</refentrytitle><manvolnum>3</manvolnum></citerefentry>, 230 <citerefentry project='man-pages'><refentrytitle>waitid</refentrytitle><manvolnum>2</manvolnum></citerefentry> 231 </para> 232 </refsect1> 233 234</refentry> 235