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                 <refname>sd_is_special</refname>
  52                 <refpurpose>Check the type of a file descriptor</refpurpose>
  53         </refnamediv>
  54
  55         <refsynopsisdiv>
  56                 <funcsynopsis>
  57                         <funcsynopsisinfo>#include &lt;systemd/sd-daemon.h&gt;</funcsynopsisinfo>
  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
  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
  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
 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
 111                 to a FIFO or pipe. If the <parameter>path</parameter>
 112                 parameter is not <constant>NULL</constant>, it is
 113                 checked whether the FIFO is bound to the specified
 114                 file system path.</para>
 115
 116                 <para><function>sd_is_socket()</function> may be
 117                 called to check whether the specified file descriptor
 118                 refers to a socket. If the
 119                 <parameter>family</parameter> parameter is not
 120                 <constant>AF_UNSPEC</constant>, it is checked whether
 121                 the socket is of the specified family (AF_UNIX,
 122                 <constant>AF_INET</constant>, ...). If the
 123                 <parameter>type</parameter> parameter is not 0, it is
 124                 checked whether the socket is of the specified type
 125                 (<constant>SOCK_STREAM</constant>,
 126                 <constant>SOCK_DGRAM</constant>, ...). If the
 127                 <parameter>listening</parameter> parameter is positive,
 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>
 142                 must be passed as either <constant>AF_UNSPEC</constant>, <constant>AF_INET</constant>, or
 143                 <constant>AF_INET6</constant>.</para>
 144
 145                 <para><function>sd_is_socket_unix()</function> is
 146                 similar to <function>sd_is_socket()</function> but
 147                 optionally checks the <constant>AF_UNIX</constant> path the socket is bound
 148                 to, unless the <parameter>path</parameter> parameter
 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
 152                 <parameter>length</parameter> to the size of the
 153                 address, including the initial 0 byte, and set the
 154                 <parameter>path</parameter> to the initial 0 byte of
 155                 the socket address.</para>
 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
 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>
 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
 168                 <constant>NULL</constant>, it is checked whether file
 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>
 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
 180                 the specified type and bound to the specified address,
 181                 a positive return value is returned, otherwise
 182                 zero.</para>
 183         </refsect1>
 184
 185         <refsect1>
 186                 <title>Notes</title>
 187
 188                 <para>These functions are provided by the reference
 189                 implementation of APIs for new-style daemons and
 190                 distributed with the systemd package. The algorithms
 191                 they implement are simple, and they can easily be
 192                 reimplemented in daemons if it is important to support
 193                 this interface without using the reference
 194                 implementation.</para>
 195
 196                 <para>Internally, these function use a combination of
 197                 <filename>fstat()</filename> and
 198                 <filename>getsockname()</filename> to check the file
 199                 descriptor type and where it is bound to.</para>
 200
 201                 <para>For details about the algorithms, check the
 202                 liberally licensed reference implementation sources:
 203                 <ulink url="http://cgit.freedesktop.org/systemd/systemd/plain/src/libsystemd-daemon/sd-daemon.c"/>
 204                 and <ulink
 205                 url="http://cgit.freedesktop.org/systemd/systemd/plain/src/systemd/sd-daemon.h"/></para>
 206
 207                 <para><function>sd_is_fifo()</function> and the
 208                 related functions are implemented in the reference
 209                 implementation's <filename>sd-daemon.c</filename> and
 210                 <filename>sd-daemon.h</filename> files. These
 211                 interfaces are available as shared library, which can
 212                 be compiled and linked to with the
 213                 <constant>libsystemd-daemon</constant> <citerefentry><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 214                 file. Alternatively, applications consuming these APIs
 215                 may copy the implementation into their source
 216                 tree. For more details about the reference
 217                 implementation see
 218                 <citerefentry><refentrytitle>sd-daemon</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para>
 219
 220                 <para>These functions continue to work as described,
 221                 even if -DDISABLE_SYSTEMD is set during
 222                 compilation.</para>
 223         </refsect1>
 224
 225         <refsect1>
 226                 <title>See Also</title>
 227                 <para>
 228                         <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 229                         <citerefentry><refentrytitle>sd-daemon</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 230                         <citerefentry><refentrytitle>sd_listen_fds</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 231                         <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 232                         <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry>
 233                 </para>
 234         </refsect1>
 235
 236 </refentry>