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 General Public License as published by
  12   the Free Software Foundation; either version 2 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   General Public License for more details.
  19
  20   You should have received a copy of the GNU 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                 <refpurpose>Check the type of a file descriptor</refpurpose>
  51         </refnamediv>
  52
  53         <refsynopsisdiv>
  54                 <funcsynopsis>
  55                         <funcsynopsisinfo>#include "sd-daemon.h"</funcsynopsisinfo>
  56
  57                         <funcprototype>
  58                                 <funcdef>int <function>sd_is_fifo</function></funcdef>
  59                                 <paramdef>int <parameter>fd</parameter></paramdef>
  60                                 <paramdef>const char *<parameter>path</parameter></paramdef>
  61                         </funcprototype>
  62
  63                         <funcprototype>
  64                                 <funcdef>int <function>sd_is_socket</function></funcdef>
  65                                 <paramdef>int <parameter>fd</parameter></paramdef>
  66                                 <paramdef>int <parameter>family</parameter></paramdef>
  67                                 <paramdef>int <parameter>type</parameter></paramdef>
  68                                 <paramdef>int <parameter>listening</parameter></paramdef>
  69                         </funcprototype>
  70
  71                         <funcprototype>
  72                                 <funcdef>int <function>sd_is_socket_inet</function></funcdef>
  73                                 <paramdef>int <parameter>fd</parameter></paramdef>
  74                                 <paramdef>int <parameter>family</parameter></paramdef>
  75                                 <paramdef>int <parameter>type</parameter></paramdef>
  76                                 <paramdef>int <parameter>listening</parameter></paramdef>
  77                                 <paramdef>uint16_t <parameter>port</parameter></paramdef>
  78                         </funcprototype>
  79
  80                         <funcprototype>
  81                                 <funcdef>int <function>sd_is_socket_unix</function></funcdef>
  82                                 <paramdef>int <parameter>fd</parameter></paramdef>
  83                                 <paramdef>int <parameter>type</parameter></paramdef>
  84                                 <paramdef>int <parameter>listening</parameter></paramdef>
  85                                 <paramdef>const char* <parameter>path</parameter></paramdef>
  86                                 <paramdef>size_t <parameter>length</parameter></paramdef>
  87                         </funcprototype>
  88
  89                 </funcsynopsis>
  90         </refsynopsisdiv>
  91
  92         <refsect1>
  93                 <title>Description</title>
  94
  95                 <para><function>sd_is_fifo()</function> may be called
  96                 to check whether the specified file descriptor refers
  97                 to a FIFO or pipe. If the <parameter>path</parameter>
  98                 parameter is not NULL, it is checked whether the FIFO
  99                 is bound to the specified file system path.</para>
 100
 101                 <para><function>sd_is_socket()</function> may be
 102                 called to check whether the specified file descriptor
 103                 refers to a socket. It the
 104                 <parameter>family</parameter> parameter is not
 105                 AF_UNSPEC it is checked whether the socket is of the
 106                 specified family (AF_UNIX, AF_INET, ...). If the
 107                 <parameter>type</parameter> parameter is not 0 it is
 108                 checked whether the socket is of the specified type
 109                 (SOCK_STREAM, SOCK_DGRAM, ...). If the
 110                 <parameter>listening</parameter> parameter is positive
 111                 it is checked whether the socket is in accepting mode,
 112                 i.e. <function>listen()</function> has been called for
 113                 it. If <parameter>listening</parameter> is 0, it is
 114                 checked whether the socket is not in this mode. If the
 115                 parameter is negative, no such check is made. The
 116                 <parameter>listening</parameter> parameter should only
 117                 be used for stream sockets and should be set to a
 118                 negative value otherwise.</para>
 119
 120                 <para><function>sd_is_socket_inet()</function> is
 121                 similar to <function>sd_is_socket()</function>, but
 122                 optionally checks the IPv4 or IPv6 port number the
 123                 socket is bound to, unless <parameter>port</parameter>
 124                 is zero. For this call <parameter>family</parameter>
 125                 must be passed as either AF_UNSPEC, AF_INET or
 126                 AF_INET6.</para>
 127
 128                 <para><function>sd_is_socket_unix()</function> is
 129                 similar to <function>sd_is_socket()</function>, but
 130                 optionally checks the AF_UNIX path the socket is bound
 131                 to, unless the <parameter>path</parameter> parameter
 132                 is NULL. For normal file system AF_UNIX sockets set
 133                 the <parameter>length</parameter> parameter to 0. For
 134                 Linux abstract namespace sockets set the
 135                 <parameter>length</parameter> to the size of the
 136                 address, including the initial 0 byte and set
 137                 <parameter>path</parameter> to the initial 0 byte of
 138                 the socket address.</para>
 139         </refsect1>
 140
 141         <refsect1>
 142                 <title>Return Value</title>
 143
 144                 <para>On failure, these calls return a negative
 145                 errno-style error code. If the file descriptor is of
 146                 the specified type and bound to the specified address
 147                 a positive return value is returned, otherwise
 148                 zero.</para>
 149         </refsect1>
 150
 151         <refsect1>
 152                 <title>Notes</title>
 153
 154                 <para>These functions are provided by the reference
 155                 implementation of APIs for new-style daemons and
 156                 distributed with the systemd package. The algorithms
 157                 they implement are simple, and can easily be
 158                 reimplemented in daemons if it is important to support
 159                 this interface without using the reference
 160                 implementation.</para>
 161
 162                 <para>Internally, these function use a combination of
 163                 <filename>fstat()</filename> and
 164                 <filename>getsockname()</filename> to check the file
 165                 descriptor type and where it is bound to.</para>
 166
 167                 <para>For details about the algorithm check the
 168                 liberally licensed reference implementation sources:
 169                 <ulink url="http://cgit.freedesktop.org/systemd/tree/src/sd-daemon.c"/>
 170                 resp. <ulink
 171                 url="http://cgit.freedesktop.org/systemd/tree/src/sd-daemon.h"/></para>
 172
 173                 <para><function>sd_is_fifo()</function> and the
 174                 related functions are implemented in the reference
 175                 implementation's drop-in
 176                 <filename>sd-daemon.c</filename> and
 177                 <filename>sd-daemon.h</filename> files. It is
 178                 recommended that applications consuming these APIs
 179                 copy the implementation into their source tree. For
 180                 more details about the reference implementation see
 181                 <citerefentry><refentrytitle>sd_daemon</refentrytitle><manvolnum>7</manvolnum></citerefentry></para>
 182
 183                 <para>These functions continue to work as described,
 184                 even if -DDISABLE_SYSTEMD is set during
 185                 compilation.</para>
 186         </refsect1>
 187
 188         <refsect1>
 189                 <title>See Also</title>
 190                 <para>
 191                         <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 192                         <citerefentry><refentrytitle>sd-daemon</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
 193                         <citerefentry><refentrytitle>sd_listen_fds</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 194                         <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 195                         <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry>
 196                 </para>
 197         </refsect1>
 198
 199 </refentry>