1<?xml version='1.0'?> <!--*-nxml-*-->
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_is_fifo"
7  xmlns:xi="http://www.w3.org/2001/XInclude">
8
9  <refentryinfo>
10    <title>sd_is_fifo</title>
11    <productname>systemd</productname>
12  </refentryinfo>
13
14  <refmeta>
15    <refentrytitle>sd_is_fifo</refentrytitle>
16    <manvolnum>3</manvolnum>
17  </refmeta>
18
19  <refnamediv>
20    <refname>sd_is_fifo</refname>
21    <refname>sd_is_socket</refname>
22    <refname>sd_is_socket_inet</refname>
23    <refname>sd_is_socket_unix</refname>
24    <refname>sd_is_socket_sockaddr</refname>
25    <refname>sd_is_mq</refname>
26    <refname>sd_is_special</refname>
27    <refpurpose>Check the type of a file descriptor</refpurpose>
28  </refnamediv>
29
30  <refsynopsisdiv>
31    <funcsynopsis>
32      <funcsynopsisinfo>#include &lt;systemd/sd-daemon.h&gt;</funcsynopsisinfo>
33
34      <funcprototype>
35        <funcdef>int <function>sd_is_fifo</function></funcdef>
36        <paramdef>int <parameter>fd</parameter></paramdef>
37        <paramdef>const char *<parameter>path</parameter></paramdef>
38      </funcprototype>
39
40      <funcprototype>
41        <funcdef>int <function>sd_is_socket</function></funcdef>
42        <paramdef>int <parameter>fd</parameter></paramdef>
43        <paramdef>int <parameter>family</parameter></paramdef>
44        <paramdef>int <parameter>type</parameter></paramdef>
45        <paramdef>int <parameter>listening</parameter></paramdef>
46      </funcprototype>
47
48      <funcprototype>
49        <funcdef>int <function>sd_is_socket_inet</function></funcdef>
50        <paramdef>int <parameter>fd</parameter></paramdef>
51        <paramdef>int <parameter>family</parameter></paramdef>
52        <paramdef>int <parameter>type</parameter></paramdef>
53        <paramdef>int <parameter>listening</parameter></paramdef>
54        <paramdef>uint16_t <parameter>port</parameter></paramdef>
55      </funcprototype>
56
57      <funcprototype>
58        <funcdef>int <function>sd_is_socket_sockaddr</function></funcdef>
59        <paramdef>int <parameter>fd</parameter></paramdef>
60        <paramdef>int <parameter>type</parameter></paramdef>
61        <paramdef>const struct sockaddr *<parameter>addr</parameter></paramdef>
62        <paramdef>unsigned <parameter>addr_len</parameter></paramdef>
63        <paramdef>int <parameter>listening</parameter></paramdef>
64      </funcprototype>
65
66      <funcprototype>
67        <funcdef>int <function>sd_is_socket_unix</function></funcdef>
68        <paramdef>int <parameter>fd</parameter></paramdef>
69        <paramdef>int <parameter>type</parameter></paramdef>
70        <paramdef>int <parameter>listening</parameter></paramdef>
71        <paramdef>const char *<parameter>path</parameter></paramdef>
72        <paramdef>size_t <parameter>length</parameter></paramdef>
73      </funcprototype>
74
75      <funcprototype>
76        <funcdef>int <function>sd_is_mq</function></funcdef>
77        <paramdef>int <parameter>fd</parameter></paramdef>
78        <paramdef>const char *<parameter>path</parameter></paramdef>
79      </funcprototype>
80
81      <funcprototype>
82        <funcdef>int <function>sd_is_special</function></funcdef>
83        <paramdef>int <parameter>fd</parameter></paramdef>
84        <paramdef>const char *<parameter>path</parameter></paramdef>
85      </funcprototype>
86
87    </funcsynopsis>
88  </refsynopsisdiv>
89
90  <refsect1>
91    <title>Description</title>
92
93    <para><function>sd_is_fifo()</function> may be called to check
94    whether the specified file descriptor refers to a FIFO or pipe. If
95    the <parameter>path</parameter> parameter is not
96    <constant>NULL</constant>, it is checked whether the FIFO is bound
97    to the specified file system path.</para>
98
99    <para><function>sd_is_socket()</function> may be called to check
100    whether the specified file descriptor refers to a socket. If the
101    <parameter>family</parameter> parameter is not
102    <constant>AF_UNSPEC</constant>, it is checked whether the socket
103    is of the specified family (<constant>AF_UNIX</constant>,
104    <constant>AF_INET</constant>, …). If the <parameter>type</parameter>
105    parameter is not 0, it is checked whether the socket is of the
106    specified type (<constant>SOCK_STREAM</constant>,
107    <constant>SOCK_DGRAM</constant>, …). If the
108    <parameter>listening</parameter> parameter is positive, it is
109    checked whether the socket is in accepting mode, i.e.
110    <function>listen()</function> has been called for it. If
111    <parameter>listening</parameter> is 0, it is checked whether the
112    socket is not in this mode. If the parameter is negative, no such
113    check is made. The <parameter>listening</parameter> parameter
114    should only be used for stream sockets and should be set to a
115    negative value otherwise.</para>
116
117    <para><function>sd_is_socket_inet()</function> is similar to
118    <function>sd_is_socket()</function>, but optionally checks the
119    IPv4 or IPv6 port number the socket is bound to, unless
120    <parameter>port</parameter> is zero. For this call
121    <parameter>family</parameter> must be passed as either
122    <constant>AF_UNSPEC</constant>, <constant>AF_INET</constant>, or
123    <constant>AF_INET6</constant>.</para>
124
125    <para><function>sd_is_socket_sockaddr()</function> is similar to
126    <function>sd_is_socket_inet()</function>, but checks if the socket is bound to the
127    address specified by <parameter>addr</parameter>. The
128    <structfield>family</structfield> specified by <parameter>addr</parameter> must be
129    either <constant>AF_INET</constant> or <constant>AF_INET6</constant> and
130    <parameter>addr_len</parameter> must be large enough for that family. If
131    <parameter>addr</parameter> specifies a non-zero port, it is also checked if the
132    socket is bound to this port. In addition, for IPv6, if <parameter>addr</parameter>
133    specifies non-zero <structfield>sin6_flowinfo</structfield> or
134    <structfield>sin6_scope_id</structfield>, it is checked if the socket has the same
135    values.</para>
136
137    <para><function>sd_is_socket_unix()</function> is similar to
138    <function>sd_is_socket()</function> but optionally checks the
139    <constant>AF_UNIX</constant> path the socket is bound to, unless
140    the <parameter>path</parameter> parameter is
141    <constant>NULL</constant>. For normal file system
142    <constant>AF_UNIX</constant> sockets, set the
143    <parameter>length</parameter> parameter to 0. For Linux abstract
144    namespace sockets, set the <parameter>length</parameter> to the
145    size of the address, including the initial 0 byte, and set the
146    <parameter>path</parameter> to the initial 0 byte of the socket
147    address.</para>
148
149    <para><function>sd_is_mq()</function> may be called to check
150    whether the specified file descriptor refers to a POSIX message
151    queue. If the <parameter>path</parameter> parameter is not
152    <constant>NULL</constant>, it is checked whether the message queue
153    is bound to the specified name.</para>
154
155    <para><function>sd_is_special()</function> may be called to check
156    whether the specified file descriptor refers to a special file. If
157    the <parameter>path</parameter> parameter is not
158    <constant>NULL</constant>, it is checked whether the file
159    descriptor is bound to the specified filename. Special files in
160    this context are character device nodes and files in
161    <filename>/proc/</filename> or <filename>/sys/</filename>.</para>
162  </refsect1>
163
164  <refsect1>
165    <title>Return Value</title>
166
167    <para>On failure, these calls return a negative errno-style error
168    code. If the file descriptor is of the specified type and bound to
169    the specified address, a positive return value is returned,
170    otherwise zero.</para>
171  </refsect1>
172
173  <refsect1>
174    <title>Notes</title>
175
176    <xi:include href="libsystemd-pkgconfig.xml" xpointer="pkgconfig-text"/>
177
178    <para>Internally, these function use a combination of
179    <filename>fstat()</filename> and
180    <filename>getsockname()</filename> to check the file descriptor
181    type and where it is bound to.</para>
182  </refsect1>
183
184  <refsect1>
185    <title>See Also</title>
186    <para>
187      <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
188      <citerefentry><refentrytitle>sd-daemon</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
189      <citerefentry><refentrytitle>sd_listen_fds</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
190      <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
191      <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
192      <citerefentry project='man-pages'><refentrytitle>ip</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
193      <citerefentry project='man-pages'><refentrytitle>ipv6</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
194      <citerefentry project='man-pages'><refentrytitle>unix</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
195      <citerefentry project='man-pages'><refentrytitle>fifo</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
196      <citerefentry project='man-pages'><refentrytitle>mq_overview</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
197      <citerefentry project='man-pages'><refentrytitle>socket</refentrytitle><manvolnum>7</manvolnum></citerefentry>.
198    </para>
199  </refsect1>
200
201</refentry>
202