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