man/sd_is_fifo.xml

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