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