[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"
        xmlns:xi="http://www.w3.org/2001/XInclude">

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

                <xi:include href="libsystemd-pkgconfig.xml" xpointer="pkgconfig-text"/>

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