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