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">
6 This file is part of systemd.
8 Copyright 2010 Lennart Poettering
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.
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.
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/>.
24 <refentry id="sd_is_fifo">
27 <title>sd_is_fifo</title>
28 <productname>systemd</productname>
32 <contrib>Developer</contrib>
33 <firstname>Lennart</firstname>
34 <surname>Poettering</surname>
35 <email>lennart@poettering.net</email>
41 <refentrytitle>sd_is_fifo</refentrytitle>
42 <manvolnum>3</manvolnum>
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>
56 <funcsynopsisinfo>#include <systemd/sd-daemon.h></funcsynopsisinfo>
59 <funcdef>int <function>sd_is_fifo</function></funcdef>
60 <paramdef>int <parameter>fd</parameter></paramdef>
61 <paramdef>const char *<parameter>path</parameter></paramdef>
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>
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>
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>
91 <funcdef>int <function>sd_is_mq</function></funcdef>
92 <paramdef>int <parameter>fd</parameter></paramdef>
93 <paramdef>const char *<parameter>path</parameter></paramdef>
100 <title>Description</title>
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 NULL, it is checked whether the FIFO
106 is bound to the specified file system path.</para>
108 <para><function>sd_is_socket()</function> may be
109 called to check whether the specified file descriptor
110 refers to a socket. If the
111 <parameter>family</parameter> parameter is not
112 <constant>AF_UNSPEC</constant> it is checked whether
113 the socket is of the specified family (AF_UNIX,
114 <constant>AF_INET</constant>, ...). If the
115 <parameter>type</parameter> parameter is not 0 it is
116 checked whether the socket is of the specified type
117 (<constant>SOCK_STREAM</constant>,
118 <constant>SOCK_DGRAM</constant>, ...). If the
119 <parameter>listening</parameter> parameter is positive
120 it is checked whether the socket is in accepting mode,
121 i.e. <function>listen()</function> has been called for
122 it. If <parameter>listening</parameter> is 0, it is
123 checked whether the socket is not in this mode. If the
124 parameter is negative, no such check is made. The
125 <parameter>listening</parameter> parameter should only
126 be used for stream sockets and should be set to a
127 negative value otherwise.</para>
129 <para><function>sd_is_socket_inet()</function> is
130 similar to <function>sd_is_socket()</function>, but
131 optionally checks the IPv4 or IPv6 port number the
132 socket is bound to, unless <parameter>port</parameter>
133 is zero. For this call <parameter>family</parameter>
134 must be passed as either <constant>AF_UNSPEC</constant>, <constant>AF_INET</constant>, or
135 <constant>AF_INET6</constant>.</para>
137 <para><function>sd_is_socket_unix()</function> is
138 similar to <function>sd_is_socket()</function>, but
139 optionally checks the <constant>AF_UNIX</constant> path the socket is bound
140 to, unless the <parameter>path</parameter> parameter
141 is <constant>NULL</constant>. For normal file system <constant>AF_UNIX</constant> sockets set
142 the <parameter>length</parameter> parameter to 0. For
143 Linux abstract namespace sockets set the
144 <parameter>length</parameter> to the size of the
145 address, including the initial 0 byte and set
146 <parameter>path</parameter> to the initial 0 byte of
147 the socket address.</para>
149 <para><function>sd_is_mq()</function> may be called to
150 check whether the specified file descriptor refers to
151 a POSIX message queue. If the
152 <parameter>path</parameter> parameter is not NULL, it
153 is checked whether the message queue is bound to the
154 specified name.</para>
158 <title>Return Value</title>
160 <para>On failure, these calls return a negative
161 errno-style error code. If the file descriptor is of
162 the specified type and bound to the specified address
163 a positive return value is returned, otherwise
170 <para>These functions are provided by the reference
171 implementation of APIs for new-style daemons and
172 distributed with the systemd package. The algorithms
173 they implement are simple, and can easily be
174 reimplemented in daemons if it is important to support
175 this interface without using the reference
176 implementation.</para>
178 <para>Internally, these function use a combination of
179 <filename>fstat()</filename> and
180 <filename>getsockname()</filename> to check the file
181 descriptor type and where it is bound to.</para>
183 <para>For details about the algorithms check the
184 liberally licensed reference implementation sources:
185 <ulink url="http://cgit.freedesktop.org/systemd/systemd/plain/src/libsystemd-daemon/sd-daemon.c"/>
187 url="http://cgit.freedesktop.org/systemd/systemd/plain/src/systemd/sd-daemon.h"/></para>
189 <para><function>sd_is_fifo()</function> and the
190 related functions are implemented in the reference
191 implementation's <filename>sd-daemon.c</filename> and
192 <filename>sd-daemon.h</filename> files. These
193 interfaces are available as shared library, which can
194 be compiled and linked to with the
195 <constant>libsystemd-daemon</constant>
196 <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
201 <citerefentry><refentrytitle>sd-daemon</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para>
203 <para>These functions continue to work as described,
204 even if -DDISABLE_SYSTEMD is set during
209 <title>See Also</title>
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>