[thirdparty/systemd.git] / man / sd_is_fifo.xml

<?xml version='1.0'?> <!--*-nxml-*-->
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
        "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">

<!--
  This file is part of systemd.

  Copyright 2010 Lennart Poettering

  systemd is free software; you can redistribute it and/or modify it
  under the terms of the GNU Lesser General Public License as published by
  the Free Software Foundation; either version 2.1 of the License, or
  (at your option) any later version.

  systemd is distributed in the hope that it will be useful, but
  WITHOUT ANY WARRANTY; without even the implied warranty of
  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
  Lesser General Public License for more details.

  You should have received a copy of the GNU Lesser General Public License
  along with systemd; If not, see <http://www.gnu.org/licenses/>.
-->

<refentry id="sd_is_fifo">

        <refentryinfo>
                <title>sd_is_fifo</title>
                <productname>systemd</productname>

                <authorgroup>
                        <author>
                                <contrib>Developer</contrib>
                                <firstname>Lennart</firstname>
                                <surname>Poettering</surname>
                                <email>lennart@poettering.net</email>
                        </author>
                </authorgroup>
        </refentryinfo>

        <refmeta>
                <refentrytitle>sd_is_fifo</refentrytitle>
                <manvolnum>3</manvolnum>
        </refmeta>

        <refnamediv>
                <refname>sd_is_fifo</refname>
                <refname>sd_is_socket</refname>
                <refname>sd_is_socket_inet</refname>
                <refname>sd_is_socket_unix</refname>
                <refname>sd_is_mq</refname>
                <refname>sd_is_special</refname>
                <refpurpose>Check the type of a file descriptor</refpurpose>
        </refnamediv>

        <refsynopsisdiv>
                <funcsynopsis>
                        <funcsynopsisinfo>#include &lt;systemd/sd-daemon.h&gt;</funcsynopsisinfo>

                        <funcprototype>
                                <funcdef>int <function>sd_is_fifo</function></funcdef>
                                <paramdef>int <parameter>fd</parameter></paramdef>
                                <paramdef>const char *<parameter>path</parameter></paramdef>
                        </funcprototype>

                        <funcprototype>
                                <funcdef>int <function>sd_is_socket</function></funcdef>
                                <paramdef>int <parameter>fd</parameter></paramdef>
                                <paramdef>int <parameter>family</parameter></paramdef>
                                <paramdef>int <parameter>type</parameter></paramdef>
                                <paramdef>int <parameter>listening</parameter></paramdef>
                        </funcprototype>

                        <funcprototype>
                                <funcdef>int <function>sd_is_socket_inet</function></funcdef>
                                <paramdef>int <parameter>fd</parameter></paramdef>
                                <paramdef>int <parameter>family</parameter></paramdef>
                                <paramdef>int <parameter>type</parameter></paramdef>
                                <paramdef>int <parameter>listening</parameter></paramdef>
                                <paramdef>uint16_t <parameter>port</parameter></paramdef>
                        </funcprototype>

                        <funcprototype>
                                <funcdef>int <function>sd_is_socket_unix</function></funcdef>
                                <paramdef>int <parameter>fd</parameter></paramdef>
                                <paramdef>int <parameter>type</parameter></paramdef>
                                <paramdef>int <parameter>listening</parameter></paramdef>
                                <paramdef>const char* <parameter>path</parameter></paramdef>
                                <paramdef>size_t <parameter>length</parameter></paramdef>
                        </funcprototype>

                        <funcprototype>
                                <funcdef>int <function>sd_is_mq</function></funcdef>
                                <paramdef>int <parameter>fd</parameter></paramdef>
                                <paramdef>const char *<parameter>path</parameter></paramdef>
                        </funcprototype>

                        <funcprototype>
                                <funcdef>int <function>sd_is_special</function></funcdef>
                                <paramdef>int <parameter>fd</parameter></paramdef>
                                <paramdef>const char *<parameter>path</parameter></paramdef>
                        </funcprototype>

                </funcsynopsis>
        </refsynopsisdiv>

        <refsect1>
                <title>Description</title>

                <para><function>sd_is_fifo()</function> may be called
                to check whether the specified file descriptor refers
                to a FIFO or pipe. If the <parameter>path</parameter>
                parameter is not <constant>NULL</constant>, it is
                checked whether the FIFO is bound to the specified
                file system path.</para>

                <para><function>sd_is_socket()</function> may be
                called to check whether the specified file descriptor
                refers to a socket. If the
                <parameter>family</parameter> parameter is not
                <constant>AF_UNSPEC</constant>, it is checked whether
                the socket is of the specified family (AF_UNIX,
                <constant>AF_INET</constant>, ...). If the
                <parameter>type</parameter> parameter is not 0, it is
                checked whether the socket is of the specified type
                (<constant>SOCK_STREAM</constant>,
                <constant>SOCK_DGRAM</constant>, ...). If the
                <parameter>listening</parameter> parameter is positive,
                it is checked whether the socket is in accepting mode,
                i.e. <function>listen()</function> has been called for
                it. If <parameter>listening</parameter> is 0, it is
                checked whether the socket is not in this mode. If the
                parameter is negative, no such check is made. The
                <parameter>listening</parameter> parameter should only
                be used for stream sockets and should be set to a
                negative value otherwise.</para>

                <para><function>sd_is_socket_inet()</function> is
                similar to <function>sd_is_socket()</function>, but
                optionally checks the IPv4 or IPv6 port number the
                socket is bound to, unless <parameter>port</parameter>
                is zero. For this call <parameter>family</parameter>
                must be passed as either <constant>AF_UNSPEC</constant>, <constant>AF_INET</constant>, or
                <constant>AF_INET6</constant>.</para>

                <para><function>sd_is_socket_unix()</function> is
                similar to <function>sd_is_socket()</function> but
                optionally checks the <constant>AF_UNIX</constant> path the socket is bound
                to, unless the <parameter>path</parameter> parameter
                is <constant>NULL</constant>. For normal file system <constant>AF_UNIX</constant> sockets,
                set the <parameter>length</parameter> parameter to 0. For
                Linux abstract namespace sockets, set the
                <parameter>length</parameter> to the size of the
                address, including the initial 0 byte, and set the
                <parameter>path</parameter> to the initial 0 byte of
                the socket address.</para>

                <para><function>sd_is_mq()</function> may be called to
                check whether the specified file descriptor refers to
                a POSIX message queue. If the
                <parameter>path</parameter> parameter is not
                <constant>NULL</constant>, it is checked whether the
                message queue is bound to the specified name.</para>

                <para><function>sd_is_special()</function> may be
                called to check whether the specified file descriptor
                refers to a special file. If the
                <parameter>path</parameter> parameter is not
                <constant>NULL</constant>, it is checked whether the file
                descriptor is bound to the specified file
                name. Special files in this context are character
                device nodes and files in <filename>/proc</filename>
                or <filename>/sys</filename>.</para>
        </refsect1>

        <refsect1>
                <title>Return Value</title>

                <para>On failure, these calls return a negative
                errno-style error code. If the file descriptor is of
                the specified type and bound to the specified address,
                a positive return value is returned, otherwise
                zero.</para>
        </refsect1>

        <refsect1>
                <title>Notes</title>

                <para>These APIs are implemented as a shared library,
                which can be compiled and linked to with the
                <constant>libsystemd</constant> <citerefentry><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry>
                file.</para>

                <para>Internally, these function use a combination of
                <filename>fstat()</filename> and
                <filename>getsockname()</filename> to check the file
                descriptor type and where it is bound to.</para>
        </refsect1>

        <refsect1>
                <title>See Also</title>
                <para>
                        <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
                        <citerefentry><refentrytitle>sd-daemon</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
                        <citerefentry><refentrytitle>sd_listen_fds</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
                        <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
                        <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry>
                </para>
        </refsect1>

</refentry>
Commit	Line	Data
f9378423 LP	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
5430f7f2 LP	11	under the terms of the GNU Lesser General Public License as published by
5430f7f2 LP	12	the Free Software Foundation; either version 2.1 of the License, or
f9378423 LP	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
5430f7f2	18	Lesser General Public License for more details.
f9378423	19
5430f7f2	20	You should have received a copy of the GNU Lesser General Public License
f9378423 LP	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>
916abb21	50	<refname>sd_is_mq</refname>
fa57130d	51	<refname>sd_is_special</refname>
f9378423 LP	52	<refpurpose>Check the type of a file descriptor</refpurpose>
	53	</refnamediv>
	54
	55	<refsynopsisdiv>
	56	<funcsynopsis>
a822cbfa	57	<funcsynopsisinfo>#include <systemd/sd-daemon.h></funcsynopsisinfo>
f9378423 LP	58
	59	<funcprototype>
	60	<funcdef>int <function>sd_is_fifo</function></funcdef>
	61	<paramdef>int <parameter>fd</parameter></paramdef>
	62	<paramdef>const char *<parameter>path</parameter></paramdef>
	63	</funcprototype>
	64
	65	<funcprototype>
	66	<funcdef>int <function>sd_is_socket</function></funcdef>
	67	<paramdef>int <parameter>fd</parameter></paramdef>
	68	<paramdef>int <parameter>family</parameter></paramdef>
	69	<paramdef>int <parameter>type</parameter></paramdef>
	70	<paramdef>int <parameter>listening</parameter></paramdef>
	71	</funcprototype>
	72
	73	<funcprototype>
	74	<funcdef>int <function>sd_is_socket_inet</function></funcdef>
	75	<paramdef>int <parameter>fd</parameter></paramdef>
	76	<paramdef>int <parameter>family</parameter></paramdef>
	77	<paramdef>int <parameter>type</parameter></paramdef>
	78	<paramdef>int <parameter>listening</parameter></paramdef>
	79	<paramdef>uint16_t <parameter>port</parameter></paramdef>
	80	</funcprototype>
	81
	82	<funcprototype>
	83	<funcdef>int <function>sd_is_socket_unix</function></funcdef>
	84	<paramdef>int <parameter>fd</parameter></paramdef>
	85	<paramdef>int <parameter>type</parameter></paramdef>
	86	<paramdef>int <parameter>listening</parameter></paramdef>
	87	<paramdef>const char* <parameter>path</parameter></paramdef>
	88	<paramdef>size_t <parameter>length</parameter></paramdef>
	89	</funcprototype>
	90
916abb21 LP	91	<funcprototype>
	92	<funcdef>int <function>sd_is_mq</function></funcdef>
	93	<paramdef>int <parameter>fd</parameter></paramdef>
	94	<paramdef>const char *<parameter>path</parameter></paramdef>
	95	</funcprototype>
	96
fa57130d LP	97	<funcprototype>
	98	<funcdef>int <function>sd_is_special</function></funcdef>
	99	<paramdef>int <parameter>fd</parameter></paramdef>
	100	<paramdef>const char *<parameter>path</parameter></paramdef>
	101	</funcprototype>
	102
f9378423 LP	103	</funcsynopsis>
	104	</refsynopsisdiv>
	105
	106	<refsect1>
	107	<title>Description</title>
	108
	109	<para><function>sd_is_fifo()</function> may be called
	110	to check whether the specified file descriptor refers
af62c704	111	to a FIFO or pipe. If the <parameter>path</parameter>
05cc7267 ZJS	112	parameter is not <constant>NULL</constant>, it is
	113	checked whether the FIFO is bound to the specified
	114	file system path.</para>
f9378423 LP	115
	116	<para><function>sd_is_socket()</function> may be
	117	called to check whether the specified file descriptor
bb31a4ac	118	refers to a socket. If the
f9378423	119	<parameter>family</parameter> parameter is not
e9dd9f95	120	<constant>AF_UNSPEC</constant>, it is checked whether
74d00578 ZJS	121	the socket is of the specified family (AF_UNIX,
74d00578 ZJS	122	<constant>AF_INET</constant>, ...). If the
e9dd9f95	123	<parameter>type</parameter> parameter is not 0, it is
f9378423	124	checked whether the socket is of the specified type
74d00578 ZJS	125	(<constant>SOCK_STREAM</constant>,
74d00578 ZJS	126	<constant>SOCK_DGRAM</constant>, ...). If the
e9dd9f95	127	<parameter>listening</parameter> parameter is positive,
f9378423 LP	128	it is checked whether the socket is in accepting mode,
	129	i.e. <function>listen()</function> has been called for
	130	it. If <parameter>listening</parameter> is 0, it is
	131	checked whether the socket is not in this mode. If the
	132	parameter is negative, no such check is made. The
	133	<parameter>listening</parameter> parameter should only
	134	be used for stream sockets and should be set to a
	135	negative value otherwise.</para>
	136
	137	<para><function>sd_is_socket_inet()</function> is
	138	similar to <function>sd_is_socket()</function>, but
	139	optionally checks the IPv4 or IPv6 port number the
	140	socket is bound to, unless <parameter>port</parameter>
	141	is zero. For this call <parameter>family</parameter>
74d00578 ZJS	142	must be passed as either <constant>AF_UNSPEC</constant>, <constant>AF_INET</constant>, or
74d00578 ZJS	143	<constant>AF_INET6</constant>.</para>
f9378423 LP	144
f9378423 LP	145	<para><function>sd_is_socket_unix()</function> is
e9dd9f95	146	similar to <function>sd_is_socket()</function> but
74d00578	147	optionally checks the <constant>AF_UNIX</constant> path the socket is bound
f9378423	148	to, unless the <parameter>path</parameter> parameter
e9dd9f95 JSJ	149	is <constant>NULL</constant>. For normal file system <constant>AF_UNIX</constant> sockets,
	150	set the <parameter>length</parameter> parameter to 0. For
	151	Linux abstract namespace sockets, set the
f9378423	152	<parameter>length</parameter> to the size of the
e9dd9f95	153	address, including the initial 0 byte, and set the
f9378423 LP	154	<parameter>path</parameter> to the initial 0 byte of
f9378423 LP	155	the socket address.</para>
916abb21 LP	156
	157	<para><function>sd_is_mq()</function> may be called to
	158	check whether the specified file descriptor refers to
	159	a POSIX message queue. If the
05cc7267 ZJS	160	<parameter>path</parameter> parameter is not
	161	<constant>NULL</constant>, it is checked whether the
	162	message queue is bound to the specified name.</para>
fa57130d LP	163
	164	<para><function>sd_is_special()</function> may be
	165	called to check whether the specified file descriptor
	166	refers to a special file. If the
	167	<parameter>path</parameter> parameter is not
e0e009c0	168	<constant>NULL</constant>, it is checked whether the file
fa57130d LP	169	descriptor is bound to the specified file
	170	name. Special files in this context are character
	171	device nodes and files in <filename>/proc</filename>
	172	or <filename>/sys</filename>.</para>
f9378423 LP	173	</refsect1>
	174
	175	<refsect1>
	176	<title>Return Value</title>
	177
	178	<para>On failure, these calls return a negative
	179	errno-style error code. If the file descriptor is of
79640424	180	the specified type and bound to the specified address,
f9378423 LP	181	a positive return value is returned, otherwise
	182	zero.</para>
	183	</refsect1>
	184
	185	<refsect1>
	186	<title>Notes</title>
	187
26e3ff59 LP	188	<para>These APIs are implemented as a shared library,
	189	which can be compiled and linked to with the
	190	<constant>libsystemd</constant> <citerefentry><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry>
	191	file.</para>
f9378423 LP	192
	193	<para>Internally, these function use a combination of
	194	<filename>fstat()</filename> and
	195	<filename>getsockname()</filename> to check the file
	196	descriptor type and where it is bound to.</para>
f9378423 LP	197	</refsect1>
	198
	199	<refsect1>
	200	<title>See Also</title>
	201	<para>
160cd5c9	202	<citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
cb07866b	203	<citerefentry><refentrytitle>sd-daemon</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
f9378423	204	<citerefentry><refentrytitle>sd_listen_fds</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
f9378423 LP	205	<citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
f9378423 LP	206	<citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry>
af62c704	207	</para>
f9378423 LP	208	</refsect1>
	209
	210	</refentry>