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