chiark / gitweb /
unit: trim cgroups when going down
[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 General Public License as published by
12   the Free Software Foundation; either version 2 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   General Public License for more details.
19
20   You should have received a copy of the GNU 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                 <refpurpose>Check the type of a file descriptor</refpurpose>
51         </refnamediv>
52
53         <refsynopsisdiv>
54                 <funcsynopsis>
55                         <funcsynopsisinfo>#include "sd-daemon.h"</funcsynopsisinfo>
56
57                         <funcprototype>
58                                 <funcdef>int <function>sd_is_fifo</function></funcdef>
59                                 <paramdef>int <parameter>fd</parameter></paramdef>
60                                 <paramdef>const char *<parameter>path</parameter></paramdef>
61                         </funcprototype>
62
63                         <funcprototype>
64                                 <funcdef>int <function>sd_is_socket</function></funcdef>
65                                 <paramdef>int <parameter>fd</parameter></paramdef>
66                                 <paramdef>int <parameter>family</parameter></paramdef>
67                                 <paramdef>int <parameter>type</parameter></paramdef>
68                                 <paramdef>int <parameter>listening</parameter></paramdef>
69                         </funcprototype>
70
71                         <funcprototype>
72                                 <funcdef>int <function>sd_is_socket_inet</function></funcdef>
73                                 <paramdef>int <parameter>fd</parameter></paramdef>
74                                 <paramdef>int <parameter>family</parameter></paramdef>
75                                 <paramdef>int <parameter>type</parameter></paramdef>
76                                 <paramdef>int <parameter>listening</parameter></paramdef>
77                                 <paramdef>uint16_t <parameter>port</parameter></paramdef>
78                         </funcprototype>
79
80                         <funcprototype>
81                                 <funcdef>int <function>sd_is_socket_unix</function></funcdef>
82                                 <paramdef>int <parameter>fd</parameter></paramdef>
83                                 <paramdef>int <parameter>type</parameter></paramdef>
84                                 <paramdef>int <parameter>listening</parameter></paramdef>
85                                 <paramdef>const char* <parameter>path</parameter></paramdef>
86                                 <paramdef>size_t <parameter>length</parameter></paramdef>
87                         </funcprototype>
88
89                 </funcsynopsis>
90         </refsynopsisdiv>
91
92         <refsect1>
93                 <title>Description</title>
94
95                 <para><function>sd_is_fifo()</function> may be called
96                 to check whether the specified file descriptor refers
97                 to a FIFO or pipe. If the <parameter>path</parameter>
98                 parameter is not NULL, it is checked whether the FIFO
99                 is bound to the specified file system path.</para>
100
101                 <para><function>sd_is_socket()</function> may be
102                 called to check whether the specified file descriptor
103                 refers to a socket. It the
104                 <parameter>family</parameter> parameter is not
105                 AF_UNSPEC it is checked whether the socket is of the
106                 specified family (AF_UNIX, AF_INET, ...). If the
107                 <parameter>type</parameter> parameter is not 0 it is
108                 checked whether the socket is of the specified type
109                 (SOCK_STREAM, SOCK_DGRAM, ...). If the
110                 <parameter>listening</parameter> parameter is positive
111                 it is checked whether the socket is in accepting mode,
112                 i.e. <function>listen()</function> has been called for
113                 it. If <parameter>listening</parameter> is 0, it is
114                 checked whether the socket is not in this mode. If the
115                 parameter is negative, no such check is made. The
116                 <parameter>listening</parameter> parameter should only
117                 be used for stream sockets and should be set to a
118                 negative value otherwise.</para>
119
120                 <para><function>sd_is_socket_inet()</function> is
121                 similar to <function>sd_is_socket()</function>, but
122                 optionally checks the IPv4 or IPv6 port number the
123                 socket is bound to, unless <parameter>port</parameter>
124                 is zero. For this call <parameter>family</parameter>
125                 must be passed as either AF_UNSPEC, AF_INET or
126                 AF_INET6.</para>
127
128                 <para><function>sd_is_socket_unix()</function> is
129                 similar to <function>sd_is_socket()</function>, but
130                 optionally checks the AF_UNIX path the socket is bound
131                 to, unless the <parameter>path</parameter> parameter
132                 is NULL. For normal file system AF_UNIX sockets set
133                 the <parameter>length</parameter> parameter to 0. For
134                 Linux abstract namespace sockets set the
135                 <parameter>length</parameter> to the size of the
136                 address, including the initial 0 byte and set
137                 <parameter>path</parameter> to the initial 0 byte of
138                 the socket address.</para>
139         </refsect1>
140
141         <refsect1>
142                 <title>Return Value</title>
143
144                 <para>On failure, these calls return a negative
145                 errno-style error code. If the file descriptor is of
146                 the specified type and bound to the specified address
147                 a positive return value is returned, otherwise
148                 zero.</para>
149         </refsect1>
150
151         <refsect1>
152                 <title>Notes</title>
153
154                 <para>These functions are provided by the reference
155                 implementation of APIs for new-style daemons and
156                 distributed with the systemd package. The algorithms
157                 they implement are simple, and can easily be
158                 reimplemented in daemons if it is important to support
159                 this interface without using the reference
160                 implementation.</para>
161
162                 <para>Internally, these function use a combination of
163                 <filename>fstat()</filename> and
164                 <filename>getsockname()</filename> to check the file
165                 descriptor type and where it is bound to.</para>
166
167                 <para>For details about the algorithm check the
168                 liberally licensed reference implementation sources:
169                 <ulink url="http://cgit.freedesktop.org/systemd/tree/src/sd-daemon.c"/>
170                 resp. <ulink
171                 url="http://cgit.freedesktop.org/systemd/tree/src/sd-daemon.h"/></para>
172
173                 <para><function>sd_is_fifo()</function> and the
174                 related functions are implemented in the reference
175                 implementation's drop-in
176                 <filename>sd-daemon.c</filename> and
177                 <filename>sd-daemon.h</filename> files. It is
178                 recommended that applications consuming these APIs
179                 copy the implementation into their source tree. For
180                 more details about the reference implementation see
181                 <citerefentry><refentrytitle>sd_daemon</refentrytitle><manvolnum>7</manvolnum></citerefentry></para>
182
183                 <para>These functions continue to work as described,
184                 even if -DDISABLE_SYSTEMD is set during
185                 compilation.</para>
186         </refsect1>
187
188         <refsect1>
189                 <title>See Also</title>
190                 <para>
191                         <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
192                         <citerefentry><refentrytitle>sd-daemon</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
193                         <citerefentry><refentrytitle>sd_listen_fds</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
194                         <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
195                         <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry>
196                 </para>
197         </refsect1>
198
199 </refentry>