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 NULL, it is checked whether the FIFO
 106                 is bound to the specified file system path.</para>
 107
 108                 <para><function>sd_is_socket()</function> may be
 109                 called to check whether the specified file descriptor
 110                 refers to a socket. It the
 111                 <parameter>family</parameter> parameter is not
 112                 AF_UNSPEC it is checked whether the socket is of the
 113                 specified family (AF_UNIX, AF_INET, ...). If the
 114                 <parameter>type</parameter> parameter is not 0 it is
 115                 checked whether the socket is of the specified type
 116                 (SOCK_STREAM, SOCK_DGRAM, ...). If the
 117                 <parameter>listening</parameter> parameter is positive
 118                 it is checked whether the socket is in accepting mode,
 119                 i.e. <function>listen()</function> has been called for
 120                 it. If <parameter>listening</parameter> is 0, it is
 121                 checked whether the socket is not in this mode. If the
 122                 parameter is negative, no such check is made. The
 123                 <parameter>listening</parameter> parameter should only
 124                 be used for stream sockets and should be set to a
 125                 negative value otherwise.</para>
 126
 127                 <para><function>sd_is_socket_inet()</function> is
 128                 similar to <function>sd_is_socket()</function>, but
 129                 optionally checks the IPv4 or IPv6 port number the
 130                 socket is bound to, unless <parameter>port</parameter>
 131                 is zero. For this call <parameter>family</parameter>
 132                 must be passed as either AF_UNSPEC, AF_INET or
 133                 AF_INET6.</para>
 134
 135                 <para><function>sd_is_socket_unix()</function> is
 136                 similar to <function>sd_is_socket()</function>, but
 137                 optionally checks the AF_UNIX path the socket is bound
 138                 to, unless the <parameter>path</parameter> parameter
 139                 is NULL. For normal file system AF_UNIX sockets set
 140                 the <parameter>length</parameter> parameter to 0. For
 141                 Linux abstract namespace sockets set the
 142                 <parameter>length</parameter> to the size of the
 143                 address, including the initial 0 byte and set
 144                 <parameter>path</parameter> to the initial 0 byte of
 145                 the socket address.</para>
 146
 147                 <para><function>sd_is_mq()</function> may be called to
 148                 check whether the specified file descriptor refers to
 149                 a POSIX message queue. If the
 150                 <parameter>path</parameter> parameter is not NULL, it
 151                 is checked whether the message queue is bound to the
 152                 specified name.</para>
 153         </refsect1>
 154
 155         <refsect1>
 156                 <title>Return Value</title>
 157
 158                 <para>On failure, these calls return a negative
 159                 errno-style error code. If the file descriptor is of
 160                 the specified type and bound to the specified address
 161                 a positive return value is returned, otherwise
 162                 zero.</para>
 163         </refsect1>
 164
 165         <refsect1>
 166                 <title>Notes</title>
 167
 168                 <para>These functions are provided by the reference
 169                 implementation of APIs for new-style daemons and
 170                 distributed with the systemd package. The algorithms
 171                 they implement are simple, and can easily be
 172                 reimplemented in daemons if it is important to support
 173                 this interface without using the reference
 174                 implementation.</para>
 175
 176                 <para>Internally, these function use a combination of
 177                 <filename>fstat()</filename> and
 178                 <filename>getsockname()</filename> to check the file
 179                 descriptor type and where it is bound to.</para>
 180
 181                 <para>For details about the algorithms check the
 182                 liberally licensed reference implementation sources:
 183                 <ulink url="http://cgit.freedesktop.org/systemd/systemd/plain/src/sd-daemon.c"/>
 184                 resp. <ulink
 185                 url="http://cgit.freedesktop.org/systemd/systemd/plain/src/systemd/sd-daemon.h"/></para>
 186
 187                 <para><function>sd_is_fifo()</function> and the
 188                 related functions are implemented in the reference
 189                 implementation's <filename>sd-daemon.c</filename> and
 190                 <filename>sd-daemon.h</filename> files. These
 191                 interfaces are available as shared library, which can
 192                 be compiled and linked to with the
 193                 <literal>libsystemd-daemon</literal>
 194                 <citerefentry><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 195                 file. Alternatively, applications consuming these APIs
 196                 may copy the implementation into their source
 197                 tree. For more details about the reference
 198                 implementation see
 199                 <citerefentry><refentrytitle>sd_daemon</refentrytitle><manvolnum>7</manvolnum></citerefentry>.</para>
 200
 201                 <para>These functions continue to work as described,
 202                 even if -DDISABLE_SYSTEMD is set during
 203                 compilation.</para>
 204         </refsect1>
 205
 206         <refsect1>
 207                 <title>See Also</title>
 208                 <para>
 209                         <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 210                         <citerefentry><refentrytitle>sd-daemon</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
 211                         <citerefentry><refentrytitle>sd_listen_fds</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 212                         <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 213                         <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry>
 214                 </para>
 215         </refsect1>
 216
 217 </refentry>