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 the 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 APIs are implemented as a shared library,
 189                 which can be compiled and linked to with the
 190                 <constant>libsystemd</constant> <citerefentry><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 191                 file.</para>
 192
 193                 <para>Internally, these function use a combination of
 194                 <filename>fstat()</filename> and
 195                 <filename>getsockname()</filename> to check the file
 196                 descriptor type and where it is bound to.</para>
 197         </refsect1>
 198
 199         <refsect1>
 200                 <title>See Also</title>
 201                 <para>
 202                         <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 203                         <citerefentry><refentrytitle>sd-daemon</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 204                         <citerefentry><refentrytitle>sd_listen_fds</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 205                         <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 206                         <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry>
 207                 </para>
 208         </refsect1>
 209
 210 </refentry>