man/sd_bus_get_n_queued_read.xml

   1 <?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*-->
   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 2018 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_bus_get_n_queued_read">
  27
  28   <refentryinfo>
  29     <title>sd_bus_get_fd</title>
  30     <productname>systemd</productname>
  31
  32     <authorgroup>
  33       <author>
  34         <contrib>Developer</contrib>
  35         <firstname>Lennart</firstname>
  36         <surname>Poettering</surname>
  37         <email>lennart@poettering.net</email>
  38       </author>
  39     </authorgroup>
  40   </refentryinfo>
  41
  42   <refmeta>
  43     <refentrytitle>sd_bus_get_n_queued_read</refentrytitle>
  44     <manvolnum>3</manvolnum>
  45   </refmeta>
  46
  47   <refnamediv>
  48     <refname>sd_bus_get_n_queued_read</refname>
  49     <refname>sd_bus_get_n_queued_write</refname>
  50
  51     <refpurpose>Get the number of pending bus messages in the read and write queues of a bus connection object</refpurpose>
  52   </refnamediv>
  53
  54   <refsynopsisdiv>
  55     <funcsynopsis>
  56       <funcsynopsisinfo>#include &lt;systemd/sd-bus.h&gt;</funcsynopsisinfo>
  57
  58       <funcprototype>
  59         <funcdef>int <function>sd_bus_get_n_queued_read</function></funcdef>
  60         <paramdef>sd_bus *<parameter>bus</parameter></paramdef>
  61         <paramdef>uint64_t *<parameter>ret</parameter></paramdef>
  62       </funcprototype>
  63
  64       <funcprototype>
  65         <funcdef>int <function>sd_bus_get_n_queued_write</function></funcdef>
  66         <paramdef>sd_bus *<parameter>bus</parameter></paramdef>
  67         <paramdef>uint64_t *<parameter>ret</parameter></paramdef>
  68       </funcprototype>
  69     </funcsynopsis>
  70   </refsynopsisdiv>
  71
  72   <refsect1>
  73     <title>Description</title>
  74
  75     <para>
  76       <function>sd_bus_get_n_queued_read()</function> may be used to query the number of bus messages in the read queue
  77       of a bus connection object. The read queue contains all messages read from the transport medium (e.g. network
  78       socket) but not yet processed locally. The function expects two arguments: the bus object to query, and a pointer
  79       to a 64bit counter variable to write the current queue size to. Use <function>sd_bus_process()</function> in
  80       order to process queued messages, i.e. to reduce the size of the read queue (as well as, in fact, the write
  81       queue, see below).
  82     </para>
  83
  84     <para>
  85       Similarly, <function>sd_bus_get_n_queued_write()</function> may be used to query the number of currently pending
  86       bus messages in the write queue of a bus connection object. The write queue contains all messages enqueued into
  87       the connection with a call such as <function>sd_bus_send()</function> but not yet written to the transport
  88       medium. The expected arguments are similar to <function>sd_bus_get_n_queued_read()</function>. Here too, use
  89       <function>sd_bus_process()</function> to reduce the size of the write queue. Alternatively, use
  90       <function>sd_bus_flush()</function> to synchronously write out any pending bus messages until the write queue is
  91       empty.
  92     </para>
  93   </refsect1>
  94
  95   <refsect1>
  96     <title>Return Value</title>
  97
  98     <para>On success, these functions return 0 or a positive integer. On failure, they return a negative errno-style
  99     error code.</para>
 100   </refsect1>
 101
 102   <refsect1>
 103     <title>Errors</title>
 104
 105     <para>Returned errors may indicate the following problems:</para>
 106
 107     <variablelist>
 108       <varlistentry>
 109         <term><constant>-ECHILD</constant></term>
 110
 111         <listitem><para>The bus connection was created in a different process.</para></listitem>
 112       </varlistentry>
 113
 114     </variablelist>
 115   </refsect1>
 116
 117   <refsect1>
 118     <title>See Also</title>
 119
 120     <para>
 121       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 122       <citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 123       <citerefentry><refentrytitle>sd_bus_process</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 124       <citerefentry><refentrytitle>sd_bus_send</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 125       <citerefentry><refentrytitle>sd_bus_flush</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 126     </para>
 127   </refsect1>
 128
 129 </refentry>