[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>
                <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>

                </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>
        </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 functions are provided by the reference
                implementation of APIs for new-style daemons and
                distributed with the systemd package. The algorithms
                they implement are simple, and they can easily be
                reimplemented in daemons if it is important to support
                this interface without using the reference
                implementation.</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>

                <para>For details about the algorithms, check the
                liberally licensed reference implementation sources:
                <ulink url="http://cgit.freedesktop.org/systemd/systemd/plain/src/libsystemd-daemon/sd-daemon.c"/>
                and <ulink
                url="http://cgit.freedesktop.org/systemd/systemd/plain/src/systemd/sd-daemon.h"/></para>

                <para><function>sd_is_fifo()</function> and the
                related functions are implemented in the reference
                implementation's <filename>sd-daemon.c</filename> and
                <filename>sd-daemon.h</filename> files. These
                interfaces are available as shared library, which can
                be compiled and linked to with the
                <constant>libsystemd-daemon</constant> <citerefentry><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry>
                file. Alternatively, applications consuming these APIs
                may copy the implementation into their source
                tree. For more details about the reference
                implementation see
                <citerefentry><refentrytitle>sd-daemon</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para>

                <para>These functions continue to work as described,
                even if -DDISABLE_SYSTEMD is set during
                compilation.</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>
f9378423 LP	51	<refpurpose>Check the type of a file descriptor</refpurpose>
	52	</refnamediv>
	53
	54	<refsynopsisdiv>
	55	<funcsynopsis>
a822cbfa	56	<funcsynopsisinfo>#include <systemd/sd-daemon.h></funcsynopsisinfo>
f9378423 LP	57
	58	<funcprototype>
	59	<funcdef>int <function>sd_is_fifo</function></funcdef>
	60	<paramdef>int <parameter>fd</parameter></paramdef>
	61	<paramdef>const char *<parameter>path</parameter></paramdef>
	62	</funcprototype>
	63
	64	<funcprototype>
	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>
	70	</funcprototype>
	71
	72	<funcprototype>
	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>
	79	</funcprototype>
	80
	81	<funcprototype>
	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>
	88	</funcprototype>
	89
916abb21 LP	90	<funcprototype>
	91	<funcdef>int <function>sd_is_mq</function></funcdef>
	92	<paramdef>int <parameter>fd</parameter></paramdef>
	93	<paramdef>const char *<parameter>path</parameter></paramdef>
	94	</funcprototype>
	95
f9378423 LP	96	</funcsynopsis>
	97	</refsynopsisdiv>
	98
	99	<refsect1>
	100	<title>Description</title>
	101
	102	<para><function>sd_is_fifo()</function> may be called
	103	to check whether the specified file descriptor refers
af62c704	104	to a FIFO or pipe. If the <parameter>path</parameter>
05cc7267 ZJS	105	parameter is not <constant>NULL</constant>, it is
	106	checked whether the FIFO is bound to the specified
	107	file system path.</para>
f9378423 LP	108
	109	<para><function>sd_is_socket()</function> may be
	110	called to check whether the specified file descriptor
bb31a4ac	111	refers to a socket. If the
f9378423	112	<parameter>family</parameter> parameter is not
e9dd9f95	113	<constant>AF_UNSPEC</constant>, it is checked whether
74d00578 ZJS	114	the socket is of the specified family (AF_UNIX,
74d00578 ZJS	115	<constant>AF_INET</constant>, ...). If the
e9dd9f95	116	<parameter>type</parameter> parameter is not 0, it is
f9378423	117	checked whether the socket is of the specified type
74d00578 ZJS	118	(<constant>SOCK_STREAM</constant>,
74d00578 ZJS	119	<constant>SOCK_DGRAM</constant>, ...). If the
e9dd9f95	120	<parameter>listening</parameter> parameter is positive,
f9378423 LP	121	it is checked whether the socket is in accepting mode,
	122	i.e. <function>listen()</function> has been called for
	123	it. If <parameter>listening</parameter> is 0, it is
	124	checked whether the socket is not in this mode. If the
	125	parameter is negative, no such check is made. The
	126	<parameter>listening</parameter> parameter should only
	127	be used for stream sockets and should be set to a
	128	negative value otherwise.</para>
	129
	130	<para><function>sd_is_socket_inet()</function> is
	131	similar to <function>sd_is_socket()</function>, but
	132	optionally checks the IPv4 or IPv6 port number the
	133	socket is bound to, unless <parameter>port</parameter>
	134	is zero. For this call <parameter>family</parameter>
74d00578 ZJS	135	must be passed as either <constant>AF_UNSPEC</constant>, <constant>AF_INET</constant>, or
74d00578 ZJS	136	<constant>AF_INET6</constant>.</para>
f9378423 LP	137
f9378423 LP	138	<para><function>sd_is_socket_unix()</function> is
e9dd9f95	139	similar to <function>sd_is_socket()</function> but
74d00578	140	optionally checks the <constant>AF_UNIX</constant> path the socket is bound
f9378423	141	to, unless the <parameter>path</parameter> parameter
e9dd9f95 JSJ	142	is <constant>NULL</constant>. For normal file system <constant>AF_UNIX</constant> sockets,
	143	set the <parameter>length</parameter> parameter to 0. For
	144	Linux abstract namespace sockets, set the
f9378423	145	<parameter>length</parameter> to the size of the
e9dd9f95	146	address, including the initial 0 byte, and set the
f9378423 LP	147	<parameter>path</parameter> to the initial 0 byte of
f9378423 LP	148	the socket address.</para>
916abb21 LP	149
	150	<para><function>sd_is_mq()</function> may be called to
	151	check whether the specified file descriptor refers to
	152	a POSIX message queue. If the
05cc7267 ZJS	153	<parameter>path</parameter> parameter is not
	154	<constant>NULL</constant>, it is checked whether the
	155	message queue is bound to the specified name.</para>
f9378423 LP	156	</refsect1>
	157
	158	<refsect1>
	159	<title>Return Value</title>
	160
	161	<para>On failure, these calls return a negative
	162	errno-style error code. If the file descriptor is of
	163	the specified type and bound to the specified address
	164	a positive return value is returned, otherwise
	165	zero.</para>
	166	</refsect1>
	167
	168	<refsect1>
	169	<title>Notes</title>
	170
	171	<para>These functions are provided by the reference
	172	implementation of APIs for new-style daemons and
	173	distributed with the systemd package. The algorithms
e9dd9f95	174	they implement are simple, and they can easily be
f9378423 LP	175	reimplemented in daemons if it is important to support
	176	this interface without using the reference
	177	implementation.</para>
	178
	179	<para>Internally, these function use a combination of
	180	<filename>fstat()</filename> and
	181	<filename>getsockname()</filename> to check the file
	182	descriptor type and where it is bound to.</para>
	183
e9dd9f95	184	<para>For details about the algorithms, check the
f9378423	185	liberally licensed reference implementation sources:
0675cc4a	186	<ulink url="http://cgit.freedesktop.org/systemd/systemd/plain/src/libsystemd-daemon/sd-daemon.c"/>
16dad32e	187	and <ulink
a26c9cc6	188	url="http://cgit.freedesktop.org/systemd/systemd/plain/src/systemd/sd-daemon.h"/></para>
f9378423 LP	189
	190	<para><function>sd_is_fifo()</function> and the
	191	related functions are implemented in the reference
71e6c1cf LP	192	implementation's <filename>sd-daemon.c</filename> and
	193	<filename>sd-daemon.h</filename> files. These
	194	interfaces are available as shared library, which can
	195	be compiled and linked to with the
1e158d27	196	<constant>libsystemd-daemon</constant> <citerefentry><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry>
71e6c1cf LP	197	file. Alternatively, applications consuming these APIs
	198	may copy the implementation into their source
	199	tree. For more details about the reference
	200	implementation see
cb07866b	201	<citerefentry><refentrytitle>sd-daemon</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para>
f9378423 LP	202
	203	<para>These functions continue to work as described,
	204	even if -DDISABLE_SYSTEMD is set during
	205	compilation.</para>
	206	</refsect1>
	207
	208	<refsect1>
	209	<title>See Also</title>
	210	<para>
160cd5c9	211	<citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
cb07866b	212	<citerefentry><refentrytitle>sd-daemon</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
f9378423	213	<citerefentry><refentrytitle>sd_listen_fds</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
f9378423 LP	214	<citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
f9378423 LP	215	<citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry>
af62c704	216	</para>
f9378423 LP	217	</refsect1>
	218
	219	</refentry>