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   xmlns:xi="http://www.w3.org/2001/XInclude">
  26
  27   <refentryinfo>
  28     <title>sd_is_fifo</title>
  29     <productname>systemd</productname>
  30
  31     <authorgroup>
  32       <author>
  33         <contrib>Developer</contrib>
  34         <firstname>Lennart</firstname>
  35         <surname>Poettering</surname>
  36         <email>lennart@poettering.net</email>
  37       </author>
  38     </authorgroup>
  39   </refentryinfo>
  40
  41   <refmeta>
  42     <refentrytitle>sd_is_fifo</refentrytitle>
  43     <manvolnum>3</manvolnum>
  44   </refmeta>
  45
  46   <refnamediv>
  47     <refname>sd_is_fifo</refname>
  48     <refname>sd_is_socket</refname>
  49     <refname>sd_is_socket_inet</refname>
  50     <refname>sd_is_socket_unix</refname>
  51     <refname>sd_is_socket_sockaddr</refname>
  52     <refname>sd_is_mq</refname>
  53     <refname>sd_is_special</refname>
  54     <refpurpose>Check the type of a file descriptor</refpurpose>
  55   </refnamediv>
  56
  57   <refsynopsisdiv>
  58     <funcsynopsis>
  59       <funcsynopsisinfo>#include &lt;systemd/sd-daemon.h&gt;</funcsynopsisinfo>
  60
  61       <funcprototype>
  62         <funcdef>int <function>sd_is_fifo</function></funcdef>
  63         <paramdef>int <parameter>fd</parameter></paramdef>
  64         <paramdef>const char *<parameter>path</parameter></paramdef>
  65       </funcprototype>
  66
  67       <funcprototype>
  68         <funcdef>int <function>sd_is_socket</function></funcdef>
  69         <paramdef>int <parameter>fd</parameter></paramdef>
  70         <paramdef>int <parameter>family</parameter></paramdef>
  71         <paramdef>int <parameter>type</parameter></paramdef>
  72         <paramdef>int <parameter>listening</parameter></paramdef>
  73       </funcprototype>
  74
  75       <funcprototype>
  76         <funcdef>int <function>sd_is_socket_inet</function></funcdef>
  77         <paramdef>int <parameter>fd</parameter></paramdef>
  78         <paramdef>int <parameter>family</parameter></paramdef>
  79         <paramdef>int <parameter>type</parameter></paramdef>
  80         <paramdef>int <parameter>listening</parameter></paramdef>
  81         <paramdef>uint16_t <parameter>port</parameter></paramdef>
  82       </funcprototype>
  83
  84       <funcprototype>
  85         <funcdef>int <function>sd_is_socket_sockaddr</function></funcdef>
  86         <paramdef>int <parameter>fd</parameter></paramdef>
  87         <paramdef>int <parameter>type</parameter></paramdef>
  88         <paramdef>const struct sockaddr *<parameter>addr</parameter></paramdef>
  89         <paramdef>unsigned <parameter>addr_len</parameter></paramdef>
  90         <paramdef>int <parameter>listening</parameter></paramdef>
  91       </funcprototype>
  92
  93       <funcprototype>
  94         <funcdef>int <function>sd_is_socket_unix</function></funcdef>
  95         <paramdef>int <parameter>fd</parameter></paramdef>
  96         <paramdef>int <parameter>type</parameter></paramdef>
  97         <paramdef>int <parameter>listening</parameter></paramdef>
  98         <paramdef>const char *<parameter>path</parameter></paramdef>
  99         <paramdef>size_t <parameter>length</parameter></paramdef>
 100       </funcprototype>
 101
 102       <funcprototype>
 103         <funcdef>int <function>sd_is_mq</function></funcdef>
 104         <paramdef>int <parameter>fd</parameter></paramdef>
 105         <paramdef>const char *<parameter>path</parameter></paramdef>
 106       </funcprototype>
 107
 108       <funcprototype>
 109         <funcdef>int <function>sd_is_special</function></funcdef>
 110         <paramdef>int <parameter>fd</parameter></paramdef>
 111         <paramdef>const char *<parameter>path</parameter></paramdef>
 112       </funcprototype>
 113
 114     </funcsynopsis>
 115   </refsynopsisdiv>
 116
 117   <refsect1>
 118     <title>Description</title>
 119
 120     <para><function>sd_is_fifo()</function> may be called to check
 121     whether the specified file descriptor refers to a FIFO or pipe. If
 122     the <parameter>path</parameter> parameter is not
 123     <constant>NULL</constant>, it is checked whether the FIFO is bound
 124     to the specified file system path.</para>
 125
 126     <para><function>sd_is_socket()</function> may be called to check
 127     whether the specified file descriptor refers to a socket. If the
 128     <parameter>family</parameter> parameter is not
 129     <constant>AF_UNSPEC</constant>, it is checked whether the socket
 130     is of the specified family (<constant>AF_UNIX</constant>,
 131     <constant>AF_INET</constant>, …). If the <parameter>type</parameter>
 132     parameter is not 0, it is checked whether the socket is of the
 133     specified type (<constant>SOCK_STREAM</constant>,
 134     <constant>SOCK_DGRAM</constant>, …). If the
 135     <parameter>listening</parameter> parameter is positive, it is
 136     checked whether the socket is in accepting mode, i.e.
 137     <function>listen()</function> has been called for it. If
 138     <parameter>listening</parameter> is 0, it is checked whether the
 139     socket is not in this mode. If the parameter is negative, no such
 140     check is made. The <parameter>listening</parameter> parameter
 141     should only be used for stream sockets and should be set to a
 142     negative value otherwise.</para>
 143
 144     <para><function>sd_is_socket_inet()</function> is similar to
 145     <function>sd_is_socket()</function>, but optionally checks the
 146     IPv4 or IPv6 port number the socket is bound to, unless
 147     <parameter>port</parameter> is zero. For this call
 148     <parameter>family</parameter> must be passed as either
 149     <constant>AF_UNSPEC</constant>, <constant>AF_INET</constant>, or
 150     <constant>AF_INET6</constant>.</para>
 151
 152     <para><function>sd_is_socket_sockaddr()</function> is similar to
 153     <function>sd_is_socket_inet()</function>, but checks if the socket is bound to the
 154     address specified by <parameter>addr</parameter>. The
 155     <structfield>family</structfield> specified by <parameter>addr</parameter> must be
 156     either <constant>AF_INET</constant> or <constant>AF_INET6</constant> and
 157     <parameter>addr_len</parameter> must be large enough for that family. If
 158     <parameter>addr</parameter> specifies a non-zero port, it is also checked if the
 159     socket is bound to this port. In addition, for IPv6, if <parameter>addr</parameter>
 160     specifies non-zero <structfield>sin6_flowinfo</structfield> or
 161     <structfield>sin6_scope_id</structfield>, it is checked if the socket has the same
 162     values.</para>
 163
 164     <para><function>sd_is_socket_unix()</function> is similar to
 165     <function>sd_is_socket()</function> but optionally checks the
 166     <constant>AF_UNIX</constant> path the socket is bound to, unless
 167     the <parameter>path</parameter> parameter is
 168     <constant>NULL</constant>. For normal file system
 169     <constant>AF_UNIX</constant> sockets, set the
 170     <parameter>length</parameter> parameter to 0. For Linux abstract
 171     namespace sockets, set the <parameter>length</parameter> to the
 172     size of the address, including the initial 0 byte, and set the
 173     <parameter>path</parameter> to the initial 0 byte of the socket
 174     address.</para>
 175
 176     <para><function>sd_is_mq()</function> may be called to check
 177     whether the specified file descriptor refers to a POSIX message
 178     queue. If the <parameter>path</parameter> parameter is not
 179     <constant>NULL</constant>, it is checked whether the message queue
 180     is bound to the specified name.</para>
 181
 182     <para><function>sd_is_special()</function> may be called to check
 183     whether the specified file descriptor refers to a special file. If
 184     the <parameter>path</parameter> parameter is not
 185     <constant>NULL</constant>, it is checked whether the file
 186     descriptor is bound to the specified filename. Special files in
 187     this context are character device nodes and files in
 188     <filename>/proc</filename> or <filename>/sys</filename>.</para>
 189   </refsect1>
 190
 191   <refsect1>
 192     <title>Return Value</title>
 193
 194     <para>On failure, these calls return a negative errno-style error
 195     code. If the file descriptor is of the specified type and bound to
 196     the specified address, a positive return value is returned,
 197     otherwise zero.</para>
 198   </refsect1>
 199
 200   <refsect1>
 201     <title>Notes</title>
 202
 203     <xi:include href="libsystemd-pkgconfig.xml" xpointer="pkgconfig-text"/>
 204
 205     <para>Internally, these function use a combination of
 206     <filename>fstat()</filename> and
 207     <filename>getsockname()</filename> to check the file descriptor
 208     type and where it is bound to.</para>
 209   </refsect1>
 210
 211   <refsect1>
 212     <title>See Also</title>
 213     <para>
 214       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 215       <citerefentry><refentrytitle>sd-daemon</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 216       <citerefentry><refentrytitle>sd_listen_fds</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 217       <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 218       <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 219       <citerefentry project='man-pages'><refentrytitle>ip</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
 220       <citerefentry project='man-pages'><refentrytitle>ipv6</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
 221       <citerefentry project='man-pages'><refentrytitle>unix</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
 222       <citerefentry project='man-pages'><refentrytitle>fifo</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
 223       <citerefentry project='man-pages'><refentrytitle>mq_overview</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
 224       <citerefentry project='man-pages'><refentrytitle>socket</refentrytitle><manvolnum>7</manvolnum></citerefentry>.
 225     </para>
 226   </refsect1>
 227
 228 </refentry>