mirrors/systemd
0
0
Fork 0
mirror of https://github.com/systemd/systemd.git synced 2024-12-14 20:54:02 +08:00
Code Issues Packages Projects Releases Wiki Activity
d3e85c9c81
systemd/man/sd_event_add_inotify.xml

235 lines
12 KiB
XML
Raw Normal View History

man: drop mode line in file headers This is already included in .dir-locals, so we don't need it in the files themselves.
2018-07-03 05:15:39 +08:00
<?xml version='1.0'?>
man: use same header for all files The "include" files had type "book" for some raeason. I don't think this is meaningful. Let's just use the same everywhere. $ perl -i -0pe 's^..DOCTYPE (book|refentry) PUBLIC "-//OASIS//DTD DocBook XML V4.[25]//EN"\s+"http^<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"\n "http^gms' man/*.xml
2019-03-14 21:40:58 +08:00
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
license: LGPL-2.1+ -> LGPL-2.1-or-later
2020-11-09 12:23:58 +08:00
<!-- SPDX-License-Identifier: LGPL-2.1-or-later -->
man: document the new sd_event_add_inotify() call
2018-05-29 21:59:26 +08:00
<refentry id="sd_event_add_inotify" xmlns:xi="http://www.w3.org/2001/XInclude">
<refentryinfo>
<title>sd_event_add_inotify</title>
<productname>systemd</productname>
</refentryinfo>
<refmeta>
<refentrytitle>sd_event_add_inotify</refentrytitle>
<manvolnum>3</manvolnum>
</refmeta>
<refnamediv>
<refname>sd_event_add_inotify</refname>
sd-event: add sd_event_add_inotify_fd() call sd_event_add_inotify_fd() is like sd_event_add_inotify(), but takes an fd to an inode instead of a path, and is hence a ton nicer.
2021-11-09 07:10:58 +08:00
<refname>sd_event_add_inotify_fd</refname>
man: document the new sd_event_add_inotify() call
2018-05-29 21:59:26 +08:00
<refname>sd_event_source_get_inotify_mask</refname>
<refname>sd_event_inotify_handler_t</refname>
<refpurpose>Add an "inotify" file system inode event source to an event loop</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis>
<funcsynopsisinfo>#include &lt;systemd/sd-event.h&gt;</funcsynopsisinfo>
<funcsynopsisinfo><token>typedef</token> struct sd_event_source sd_event_source;</funcsynopsisinfo>
<funcprototype>
<funcdef>typedef int (*<function>sd_event_inotify_handler_t</function>)</funcdef>
<paramdef>sd_event_source *<parameter>s</parameter></paramdef>
<paramdef>const struct inotify_event *<parameter>event</parameter></paramdef>
<paramdef>void *<parameter>userdata</parameter></paramdef>
</funcprototype>
<funcprototype>
<funcdef>int <function>sd_event_add_inotify</function></funcdef>
<paramdef>sd_event *<parameter>event</parameter></paramdef>
<paramdef>sd_event_source **<parameter>source</parameter></paramdef>
<paramdef>const char *<parameter>path</parameter></paramdef>
<paramdef>uint32_t <parameter>mask</parameter></paramdef>
<paramdef>sd_event_inotify_handler_t <parameter>handler</parameter></paramdef>
<paramdef>void *<parameter>userdata</parameter></paramdef>
</funcprototype>
sd-event: add sd_event_add_inotify_fd() call sd_event_add_inotify_fd() is like sd_event_add_inotify(), but takes an fd to an inode instead of a path, and is hence a ton nicer.
2021-11-09 07:10:58 +08:00
<funcprototype>
<funcdef>int <function>sd_event_add_inotify_fd</function></funcdef>
<paramdef>sd_event *<parameter>event</parameter></paramdef>
<paramdef>sd_event_source **<parameter>source</parameter></paramdef>
<paramdef>int <parameter>fd</parameter></paramdef>
<paramdef>uint32_t <parameter>mask</parameter></paramdef>
<paramdef>sd_event_inotify_handler_t <parameter>handler</parameter></paramdef>
<paramdef>void *<parameter>userdata</parameter></paramdef>
</funcprototype>
man: document the new sd_event_add_inotify() call
2018-05-29 21:59:26 +08:00
<funcprototype>
<funcdef>int <function>sd_event_source_get_inotify_mask</function></funcdef>
<paramdef>sd_event_source *<parameter>source</parameter></paramdef>
<paramdef>uint32_t *<parameter>mask</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Description</title>
<para><function>sd_event_add_inotify()</function> adds a new <citerefentry
man: add better descriptions of what event handlers do The meaning of the return value, the default handlers, and loop exiting are now described.
2022-01-05 21:00:59 +08:00
project='man-pages'><refentrytitle>inotify</refentrytitle><manvolnum>7</manvolnum></citerefentry> file
system inode event source to an event loop. The event loop object is specified in the
<parameter>event</parameter> parameter, the event source object is returned in the
<parameter>source</parameter> parameter. The <parameter>path</parameter> parameter specifies the path of
the file system inode to watch. The <parameter>mask</parameter> parameter specifies which types of inode
events to watch specifically. It must contain an OR-ed combination of <constant>IN_ACCESS</constant>,
<constant>IN_ATTRIB</constant>, <constant>IN_CLOSE_WRITE</constant>, … flags. See <citerefentry
project='man-pages'><refentrytitle>inotify</refentrytitle><manvolnum>7</manvolnum></citerefentry> for
man: document the new sd_event_add_inotify() call
2018-05-29 21:59:26 +08:00
further information.</para>
man: add better descriptions of what event handlers do The meaning of the return value, the default handlers, and loop exiting are now described.
2022-01-05 21:00:59 +08:00
<para>The <parameter>handler</parameter> must reference a function to call when the inode changes or
tree-wide: fix typo
2022-01-06 21:20:11 +08:00
<constant>NULL</constant>. The handler function will be passed the <parameter>userdata</parameter> pointer,
man: add better descriptions of what event handlers do The meaning of the return value, the default handlers, and loop exiting are now described.
2022-01-05 21:00:59 +08:00
which may be chosen freely by the caller. The handler also receives a pointer to a <structname>struct
inotify_event</structname> structure containing information about the inode event. The handler may return
negative to signal an error (see below), other return values are ignored. If
<parameter>handler</parameter> is <constant>NULL</constant>, a default handler that calls
<citerefentry><refentrytitle>sd_event_exit</refentrytitle><manvolnum>3</manvolnum></citerefentry> will be
used.</para>
sd-event: add sd_event_add_inotify_fd() call sd_event_add_inotify_fd() is like sd_event_add_inotify(), but takes an fd to an inode instead of a path, and is hence a ton nicer.
2021-11-09 07:10:58 +08:00
<para><function>sd_event_add_inotify_fd()</function> is identical to
<function>sd_event_add_inotify()</function>, except that it takes a file descriptor to an inode (possibly
man: add better descriptions of what event handlers do The meaning of the return value, the default handlers, and loop exiting are now described.
2022-01-05 21:00:59 +08:00
an <constant>O_PATH</constant> one, but any other will do too) instead of a path in the file system.
</para>
sd-event: add sd_event_add_inotify_fd() call sd_event_add_inotify_fd() is like sd_event_add_inotify(), but takes an fd to an inode instead of a path, and is hence a ton nicer.
2021-11-09 07:10:58 +08:00
man: document the new sd_event_add_inotify() call
2018-05-29 21:59:26 +08:00
<para>If multiple event sources are installed for the same inode the backing inotify watch descriptor is
automatically shared. The mask parameter may contain any flag defined by the inotify API, with the exception of
<constant>IN_MASK_ADD</constant>.</para>
<para>The handler is enabled continuously (<constant>SD_EVENT_ON</constant>), but this may be changed with
man: add better descriptions of what event handlers do The meaning of the return value, the default handlers, and loop exiting are now described.
2022-01-05 21:00:59 +08:00
<citerefentry><refentrytitle>sd_event_source_set_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
Alternatively, the <constant>IN_ONESHOT</constant> mask flag may be used to request
<constant>SD_EVENT_ONESHOT</constant> mode. If the handler function returns a negative error code, it
will be disabled after the invocation, even if the <constant>SD_EVENT_ON</constant> mode was requested
before.</para>
man: document the new sd_event_add_inotify() call
2018-05-29 21:59:26 +08:00
<para>As a special limitation the priority of inotify event sources may only be altered (see
<citerefentry><refentrytitle>sd_event_source_set_priority</refentrytitle><manvolnum>3</manvolnum></citerefentry>)
in the time between creation of the event source object with <function>sd_event_add_inotify()</function> and the
beginning of the next event loop iteration. Attempts of changing the priority any later will be refused. Consider
freeing and allocating a new inotify event source to change the priority at that point.</para>
<para>To destroy an event source object use
<citerefentry><refentrytitle>sd_event_source_unref</refentrytitle><manvolnum>3</manvolnum></citerefentry>, but note
that the event source is only removed from the event loop when all references to the event source are dropped. To
make sure an event source does not fire anymore, even when there's still a reference to it kept, consider disabling
it with
<citerefentry><refentrytitle>sd_event_source_set_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para>
sd-event: support callback=NULL in IO/child/inotify/defer event sources, too Also, document this functionality more prominently, including with a reference from sd_event_exit(). This is mostly to make things complete, as previously we supported NULL callbacks only in _add_time() and _add_signal(). However, I think this makes snese for IO event sources too (think: when some fd such as a pipe end sees SIGHUP or so, exit), as well as defer or post event sources (i.e. exit once we got nothing else to do). This also adds support for inotify event sources, simply to complete things (I can't see the immediate use, but maybe someone else comes up with it). The only event source type that doesn't allow callback=NULL now are exit callbacks, but for them they make little sense, as the event loop is exiting then anyway.
2020-10-02 15:51:36 +08:00
<para>If the second parameter of <function>sd_event_add_inotify()</function> is passed as
<constant>NULL</constant> no reference to the event source object is returned. In this case the event
source is considered "floating", and will be destroyed implicitly when the event loop itself is
destroyed.</para>
<para>If the <parameter>handler</parameter> parameter to <function>sd_event_add_inotify()</function> is
<constant>NULL</constant>, and the event source fires, this will be considered a request to exit the
event loop. In this case, the <parameter>userdata</parameter> parameter, cast to an integer, is passed as
the exit code parameter to
<citerefentry><refentrytitle>sd_event_exit</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para>
man: document the new sd_event_add_inotify() call
2018-05-29 21:59:26 +08:00
<para><function>sd_event_source_get_inotify_mask()</function> retrieves the configured inotify watch mask of an
event source created previously with <function>sd_event_add_inotify()</function>. It takes the event source object
as the <parameter>source</parameter> parameter and a pointer to a <type>uint32_t</type> variable to return the mask
in.</para>
</refsect1>
<refsect1>
<title>Return Value</title>
<para>On success, these functions return 0 or a positive integer. On failure, they return a negative errno-style
error code.</para>
man: make separate "Errors" sections subsection of "Return value" Logically, this is better, because we're describing a subset of possible return values. Visually this also looks quite good because groff renders refsect2 much less prominently. Also rewrap things, add <constant> in various places, fix some typos.
2019-03-21 21:53:00 +08:00
<refsect2>
<title>Errors</title>
man: document the new sd_event_add_inotify() call
2018-05-29 21:59:26 +08:00
man: make separate "Errors" sections subsection of "Return value" Logically, this is better, because we're describing a subset of possible return values. Visually this also looks quite good because groff renders refsect2 much less prominently. Also rewrap things, add <constant> in various places, fix some typos.
2019-03-21 21:53:00 +08:00
<para>Returned errors may indicate the following problems:</para>
man: document the new sd_event_add_inotify() call
2018-05-29 21:59:26 +08:00
man: make separate "Errors" sections subsection of "Return value" Logically, this is better, because we're describing a subset of possible return values. Visually this also looks quite good because groff renders refsect2 much less prominently. Also rewrap things, add <constant> in various places, fix some typos.
2019-03-21 21:53:00 +08:00
<variablelist>
<varlistentry>
<term><constant>-ENOMEM</constant></term>
man: document the new sd_event_add_inotify() call
2018-05-29 21:59:26 +08:00
man: make separate "Errors" sections subsection of "Return value" Logically, this is better, because we're describing a subset of possible return values. Visually this also looks quite good because groff renders refsect2 much less prominently. Also rewrap things, add <constant> in various places, fix some typos.
2019-03-21 21:53:00 +08:00
<listitem><para>Not enough memory to allocate an object.</para></listitem>
</varlistentry>
man: document the new sd_event_add_inotify() call
2018-05-29 21:59:26 +08:00
man: make separate "Errors" sections subsection of "Return value" Logically, this is better, because we're describing a subset of possible return values. Visually this also looks quite good because groff renders refsect2 much less prominently. Also rewrap things, add <constant> in various places, fix some typos.
2019-03-21 21:53:00 +08:00
<varlistentry>
<term><constant>-EINVAL</constant></term>
man: document the new sd_event_add_inotify() call
2018-05-29 21:59:26 +08:00
man: make separate "Errors" sections subsection of "Return value" Logically, this is better, because we're describing a subset of possible return values. Visually this also looks quite good because groff renders refsect2 much less prominently. Also rewrap things, add <constant> in various places, fix some typos.
2019-03-21 21:53:00 +08:00
<listitem><para>An invalid argument has been passed. This includes specifying a mask with
<constant>IN_MASK_ADD</constant> set.</para></listitem>
</varlistentry>
man: document the new sd_event_add_inotify() call
2018-05-29 21:59:26 +08:00
man: make separate "Errors" sections subsection of "Return value" Logically, this is better, because we're describing a subset of possible return values. Visually this also looks quite good because groff renders refsect2 much less prominently. Also rewrap things, add <constant> in various places, fix some typos.
2019-03-21 21:53:00 +08:00
<varlistentry>
<term><constant>-ESTALE</constant></term>
man: document the new sd_event_add_inotify() call
2018-05-29 21:59:26 +08:00
man: make separate "Errors" sections subsection of "Return value" Logically, this is better, because we're describing a subset of possible return values. Visually this also looks quite good because groff renders refsect2 much less prominently. Also rewrap things, add <constant> in various places, fix some typos.
2019-03-21 21:53:00 +08:00
<listitem><para>The event loop is already terminated.</para></listitem>
man: document the new sd_event_add_inotify() call
2018-05-29 21:59:26 +08:00
man: make separate "Errors" sections subsection of "Return value" Logically, this is better, because we're describing a subset of possible return values. Visually this also looks quite good because groff renders refsect2 much less prominently. Also rewrap things, add <constant> in various places, fix some typos.
2019-03-21 21:53:00 +08:00
</varlistentry>
man: document the new sd_event_add_inotify() call
2018-05-29 21:59:26 +08:00
man: make separate "Errors" sections subsection of "Return value" Logically, this is better, because we're describing a subset of possible return values. Visually this also looks quite good because groff renders refsect2 much less prominently. Also rewrap things, add <constant> in various places, fix some typos.
2019-03-21 21:53:00 +08:00
<varlistentry>
<term><constant>-ECHILD</constant></term>
man: document the new sd_event_add_inotify() call
2018-05-29 21:59:26 +08:00
man: make separate "Errors" sections subsection of "Return value" Logically, this is better, because we're describing a subset of possible return values. Visually this also looks quite good because groff renders refsect2 much less prominently. Also rewrap things, add <constant> in various places, fix some typos.
2019-03-21 21:53:00 +08:00
<listitem><para>The event loop has been created in a different process.</para></listitem>
man: document the new sd_event_add_inotify() call
2018-05-29 21:59:26 +08:00
man: make separate "Errors" sections subsection of "Return value" Logically, this is better, because we're describing a subset of possible return values. Visually this also looks quite good because groff renders refsect2 much less prominently. Also rewrap things, add <constant> in various places, fix some typos.
2019-03-21 21:53:00 +08:00
</varlistentry>
man: document the new sd_event_add_inotify() call
2018-05-29 21:59:26 +08:00
man: make separate "Errors" sections subsection of "Return value" Logically, this is better, because we're describing a subset of possible return values. Visually this also looks quite good because groff renders refsect2 much less prominently. Also rewrap things, add <constant> in various places, fix some typos.
2019-03-21 21:53:00 +08:00
<varlistentry>
<term><constant>-EDOM</constant></term>
man: document the new sd_event_add_inotify() call
2018-05-29 21:59:26 +08:00
man: make separate "Errors" sections subsection of "Return value" Logically, this is better, because we're describing a subset of possible return values. Visually this also looks quite good because groff renders refsect2 much less prominently. Also rewrap things, add <constant> in various places, fix some typos.
2019-03-21 21:53:00 +08:00
<listitem><para>The passed event source is not an inotify process event source.</para></listitem>
</varlistentry>
man: document the new sd_event_add_inotify() call
2018-05-29 21:59:26 +08:00
sd-event: add sd_event_add_inotify_fd() call sd_event_add_inotify_fd() is like sd_event_add_inotify(), but takes an fd to an inode instead of a path, and is hence a ton nicer.
2021-11-09 07:10:58 +08:00
<varlistentry>
<term><constant>-EBADF</constant></term>
<listitem><para>The passed file descriptor is not valid.</para></listitem>
</varlistentry>
<varlistentry>
<term><constant>-ENOSYS</constant></term>
<listitem><para><function>sd_event_add_inotify_fd()</function> was called without
<filename>/proc/</filename> mounted.</para></listitem>
</varlistentry>
man: make separate "Errors" sections subsection of "Return value" Logically, this is better, because we're describing a subset of possible return values. Visually this also looks quite good because groff renders refsect2 much less prominently. Also rewrap things, add <constant> in various places, fix some typos.
2019-03-21 21:53:00 +08:00
</variablelist>
</refsect2>
man: document the new sd_event_add_inotify() call
2018-05-29 21:59:26 +08:00
</refsect1>
man: add example for sd_event_add_inotify
2018-06-05 18:52:21 +08:00
<refsect1>
<title>Examples</title>
<example>
<title>A simple program that uses inotify to monitor one or two directories</title>
<programlisting><xi:include href="inotify-watch-tmp.c" parse="text" /></programlisting>
</example>
</refsect1>
man: document the new sd_event_add_inotify() call
2018-05-29 21:59:26 +08:00
<xi:include href="libsystemd-pkgconfig.xml" />
<refsect1>
<title>See Also</title>
<para>
<citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd-event</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_event_new</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_event_now</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_event_add_io</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_event_add_time</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_event_add_signal</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_event_add_defer</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_event_add_child</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_event_source_set_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_event_source_set_priority</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_event_source_set_userdata</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sd_event_source_set_description</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
man: document sd_event_source_set_floating() Let's make sure we get back to 100% man page documentation coverage of our sd-event APIs. We are bad enough at the others, let's get these ones right at least.
2019-11-28 00:11:44 +08:00
<citerefentry><refentrytitle>sd_event_source_set_floating</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
man: document the new sd_event_add_inotify() call
2018-05-29 21:59:26 +08:00
<citerefentry project='man-pages'><refentrytitle>waitid</refentrytitle><manvolnum>2</manvolnum></citerefentry>
</para>
</refsect1>
</refentry>
Reference in New Issue Copy Permalink