chiark / gitweb /
core: allow setting RemainAfterExit= for transient services
[elogind.git] / man / sd_is_fifo.xml
1 <?xml version='1.0'?> <!--*-nxml-*-->
2 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
3         "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
4
5 <!--
6   This file is part of systemd.
7
8   Copyright 2010 Lennart Poettering
9
10   systemd is free software; you can redistribute it and/or modify it
11   under the terms of the GNU Lesser General Public License as published by
12   the Free Software Foundation; either version 2.1 of the License, or
13   (at your option) any later version.
14
15   systemd is distributed in the hope that it will be useful, but
16   WITHOUT ANY WARRANTY; without even the implied warranty of
17   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
18   Lesser General Public License for more details.
19
20   You should have received a copy of the GNU Lesser General Public License
21   along with systemd; If not, see <http://www.gnu.org/licenses/>.
22 -->
23
24 <refentry id="sd_is_fifo">
25
26         <refentryinfo>
27                 <title>sd_is_fifo</title>
28                 <productname>systemd</productname>
29
30                 <authorgroup>
31                         <author>
32                                 <contrib>Developer</contrib>
33                                 <firstname>Lennart</firstname>
34                                 <surname>Poettering</surname>
35                                 <email>lennart@poettering.net</email>
36                         </author>
37                 </authorgroup>
38         </refentryinfo>
39
40         <refmeta>
41                 <refentrytitle>sd_is_fifo</refentrytitle>
42                 <manvolnum>3</manvolnum>
43         </refmeta>
44
45         <refnamediv>
46                 <refname>sd_is_fifo</refname>
47                 <refname>sd_is_socket</refname>
48                 <refname>sd_is_socket_inet</refname>
49                 <refname>sd_is_socket_unix</refname>
50                 <refname>sd_is_mq</refname>
51                 <refpurpose>Check the type of a file descriptor</refpurpose>
52         </refnamediv>
53
54         <refsynopsisdiv>
55                 <funcsynopsis>
56                         <funcsynopsisinfo>#include &lt;systemd/sd-daemon.h&gt;</funcsynopsisinfo>
57
58                         <funcprototype>
59                                 <funcdef>int <function>sd_is_fifo</function></funcdef>
60                                 <paramdef>int <parameter>fd</parameter></paramdef>
61                                 <paramdef>const char *<parameter>path</parameter></paramdef>
62                         </funcprototype>
63
64                         <funcprototype>
65                                 <funcdef>int <function>sd_is_socket</function></funcdef>
66                                 <paramdef>int <parameter>fd</parameter></paramdef>
67                                 <paramdef>int <parameter>family</parameter></paramdef>
68                                 <paramdef>int <parameter>type</parameter></paramdef>
69                                 <paramdef>int <parameter>listening</parameter></paramdef>
70                         </funcprototype>
71
72                         <funcprototype>
73                                 <funcdef>int <function>sd_is_socket_inet</function></funcdef>
74                                 <paramdef>int <parameter>fd</parameter></paramdef>
75                                 <paramdef>int <parameter>family</parameter></paramdef>
76                                 <paramdef>int <parameter>type</parameter></paramdef>
77                                 <paramdef>int <parameter>listening</parameter></paramdef>
78                                 <paramdef>uint16_t <parameter>port</parameter></paramdef>
79                         </funcprototype>
80
81                         <funcprototype>
82                                 <funcdef>int <function>sd_is_socket_unix</function></funcdef>
83                                 <paramdef>int <parameter>fd</parameter></paramdef>
84                                 <paramdef>int <parameter>type</parameter></paramdef>
85                                 <paramdef>int <parameter>listening</parameter></paramdef>
86                                 <paramdef>const char* <parameter>path</parameter></paramdef>
87                                 <paramdef>size_t <parameter>length</parameter></paramdef>
88                         </funcprototype>
89
90                         <funcprototype>
91                                 <funcdef>int <function>sd_is_mq</function></funcdef>
92                                 <paramdef>int <parameter>fd</parameter></paramdef>
93                                 <paramdef>const char *<parameter>path</parameter></paramdef>
94                         </funcprototype>
95
96                 </funcsynopsis>
97         </refsynopsisdiv>
98
99         <refsect1>
100                 <title>Description</title>
101
102                 <para><function>sd_is_fifo()</function> may be called
103                 to check whether the specified file descriptor refers
104                 to a FIFO or pipe. If the <parameter>path</parameter>
105                 parameter is not <constant>NULL</constant>, it is
106                 checked whether the FIFO is bound to the specified
107                 file system path.</para>
108
109                 <para><function>sd_is_socket()</function> may be
110                 called to check whether the specified file descriptor
111                 refers to a socket. If the
112                 <parameter>family</parameter> parameter is not
113                 <constant>AF_UNSPEC</constant>, it is checked whether
114                 the socket is of the specified family (AF_UNIX,
115                 <constant>AF_INET</constant>, ...). If the
116                 <parameter>type</parameter> parameter is not 0, it is
117                 checked whether the socket is of the specified type
118                 (<constant>SOCK_STREAM</constant>,
119                 <constant>SOCK_DGRAM</constant>, ...). If the
120                 <parameter>listening</parameter> parameter is positive,
121                 it is checked whether the socket is in accepting mode,
122                 i.e. <function>listen()</function> has been called for
123                 it. If <parameter>listening</parameter> is 0, it is
124                 checked whether the socket is not in this mode. If the
125                 parameter is negative, no such check is made. The
126                 <parameter>listening</parameter> parameter should only
127                 be used for stream sockets and should be set to a
128                 negative value otherwise.</para>
129
130                 <para><function>sd_is_socket_inet()</function> is
131                 similar to <function>sd_is_socket()</function>, but
132                 optionally checks the IPv4 or IPv6 port number the
133                 socket is bound to, unless <parameter>port</parameter>
134                 is zero. For this call <parameter>family</parameter>
135                 must be passed as either <constant>AF_UNSPEC</constant>, <constant>AF_INET</constant>, or
136                 <constant>AF_INET6</constant>.</para>
137
138                 <para><function>sd_is_socket_unix()</function> is
139                 similar to <function>sd_is_socket()</function> but
140                 optionally checks the <constant>AF_UNIX</constant> path the socket is bound
141                 to, unless the <parameter>path</parameter> parameter
142                 is <constant>NULL</constant>. For normal file system <constant>AF_UNIX</constant> sockets,
143                 set the <parameter>length</parameter> parameter to 0. For
144                 Linux abstract namespace sockets, set the
145                 <parameter>length</parameter> to the size of the
146                 address, including the initial 0 byte, and set the
147                 <parameter>path</parameter> to the initial 0 byte of
148                 the socket address.</para>
149
150                 <para><function>sd_is_mq()</function> may be called to
151                 check whether the specified file descriptor refers to
152                 a POSIX message queue. If the
153                 <parameter>path</parameter> parameter is not
154                 <constant>NULL</constant>, it is checked whether the
155                 message queue is bound to the specified name.</para>
156         </refsect1>
157
158         <refsect1>
159                 <title>Return Value</title>
160
161                 <para>On failure, these calls return a negative
162                 errno-style error code. If the file descriptor is of
163                 the specified type and bound to the specified address
164                 a positive return value is returned, otherwise
165                 zero.</para>
166         </refsect1>
167
168         <refsect1>
169                 <title>Notes</title>
170
171                 <para>These functions are provided by the reference
172                 implementation of APIs for new-style daemons and
173                 distributed with the systemd package. The algorithms
174                 they implement are simple, and they can easily be
175                 reimplemented in daemons if it is important to support
176                 this interface without using the reference
177                 implementation.</para>
178
179                 <para>Internally, these function use a combination of
180                 <filename>fstat()</filename> and
181                 <filename>getsockname()</filename> to check the file
182                 descriptor type and where it is bound to.</para>
183
184                 <para>For details about the algorithms, check the
185                 liberally licensed reference implementation sources:
186                 <ulink url="http://cgit.freedesktop.org/systemd/systemd/plain/src/libsystemd-daemon/sd-daemon.c"/>
187                 and <ulink
188                 url="http://cgit.freedesktop.org/systemd/systemd/plain/src/systemd/sd-daemon.h"/></para>
189
190                 <para><function>sd_is_fifo()</function> and the
191                 related functions are implemented in the reference
192                 implementation's <filename>sd-daemon.c</filename> and
193                 <filename>sd-daemon.h</filename> files. These
194                 interfaces are available as shared library, which can
195                 be compiled and linked to with the
196                 <constant>libsystemd-daemon</constant> <citerefentry><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry>
197                 file. Alternatively, applications consuming these APIs
198                 may copy the implementation into their source
199                 tree. For more details about the reference
200                 implementation see
201                 <citerefentry><refentrytitle>sd-daemon</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para>
202
203                 <para>These functions continue to work as described,
204                 even if -DDISABLE_SYSTEMD is set during
205                 compilation.</para>
206         </refsect1>
207
208         <refsect1>
209                 <title>See Also</title>
210                 <para>
211                         <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
212                         <citerefentry><refentrytitle>sd-daemon</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
213                         <citerefentry><refentrytitle>sd_listen_fds</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
214                         <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
215                         <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry>
216                 </para>
217         </refsect1>
218
219 </refentry>