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
  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>
  50                 <refname>sd_is_mq</refname>
  51                 <refpurpose>Check the type of a file descriptor</refpurpose>
  52         </refnamediv>
  53
  54         <refsynopsisdiv>
  55                 <funcsynopsis>
  56                         <funcsynopsisinfo>#include &lt;systemd/sd-daemon.h&gt;</funcsynopsisinfo>
  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
  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
  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
 104                 to a FIFO or pipe. If the <parameter>path</parameter>
 105                 parameter is not <constant>NULL</constant>, it is
 106                 checked whether the FIFO is bound to the specified
 107                 file system path.</para>
 108
 109                 <para><function>sd_is_socket()</function> may be
 110                 called to check whether the specified file descriptor
 111                 refers to a socket. If the
 112                 <parameter>family</parameter> parameter is not
 113                 <constant>AF_UNSPEC</constant>, it is checked whether
 114                 the socket is of the specified family (AF_UNIX,
 115                 <constant>AF_INET</constant>, ...). If the
 116                 <parameter>type</parameter> parameter is not 0, it is
 117                 checked whether the socket is of the specified type
 118                 (<constant>SOCK_STREAM</constant>,
 119                 <constant>SOCK_DGRAM</constant>, ...). If the
 120                 <parameter>listening</parameter> parameter is positive,
 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>
 135                 must be passed as either <constant>AF_UNSPEC</constant>, <constant>AF_INET</constant>, or
 136                 <constant>AF_INET6</constant>.</para>
 137
 138                 <para><function>sd_is_socket_unix()</function> is
 139                 similar to <function>sd_is_socket()</function> but
 140                 optionally checks the <constant>AF_UNIX</constant> path the socket is bound
 141                 to, unless the <parameter>path</parameter> parameter
 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
 145                 <parameter>length</parameter> to the size of the
 146                 address, including the initial 0 byte, and set the
 147                 <parameter>path</parameter> to the initial 0 byte of
 148                 the socket address.</para>
 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
 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>
 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
 174                 they implement are simple, and they can easily be
 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
 184                 <para>For details about the algorithms, check the
 185                 liberally licensed reference implementation sources:
 186                 <ulink url="http://cgit.freedesktop.org/systemd/systemd/plain/src/libsystemd-daemon/sd-daemon.c"/>
 187                 and <ulink
 188                 url="http://cgit.freedesktop.org/systemd/systemd/plain/src/systemd/sd-daemon.h"/></para>
 189
 190                 <para><function>sd_is_fifo()</function> and the
 191                 related functions are implemented in the reference
 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
 196                 <constant>libsystemd-daemon</constant> <citerefentry><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 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
 201                 <citerefentry><refentrytitle>sd-daemon</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para>
 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>
 211                         <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 212                         <citerefentry><refentrytitle>sd-daemon</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 213                         <citerefentry><refentrytitle>sd_listen_fds</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 214                         <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 215                         <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry>
 216                 </para>
 217         </refsect1>
 218
 219 </refentry>