man/sd_bus_process.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 2016 Julian Orth
  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_process">
  27
  28   <refentryinfo>
  29     <title>sd_bus_process</title>
  30     <productname>systemd</productname>
  31
  32     <authorgroup>
  33       <author>
  34         <firstname>Julian</firstname>
  35         <surname>Orth</surname>
  36         <email>ju.orth@gmail.com</email>
  37       </author>
  38     </authorgroup>
  39   </refentryinfo>
  40
  41   <refmeta>
  42     <refentrytitle>sd_bus_process</refentrytitle>
  43     <manvolnum>3</manvolnum>
  44   </refmeta>
  45
  46   <refnamediv>
  47     <refname>sd_bus_process</refname>
  48
  49     <refpurpose>Drive the connection</refpurpose>
  50   </refnamediv>
  51
  52   <refsynopsisdiv>
  53     <funcsynopsis>
  54       <funcsynopsisinfo>#include &lt;systemd/sd-bus.h&gt;</funcsynopsisinfo>
  55
  56       <funcprototype>
  57         <funcdef>int <function>sd_bus_process</function></funcdef>
  58         <paramdef>sd_bus *<parameter>bus</parameter></paramdef>
  59         <paramdef>sd_bus_message **<parameter>r</parameter></paramdef>
  60       </funcprototype>
  61     </funcsynopsis>
  62   </refsynopsisdiv>
  63
  64   <refsect1>
  65     <title>Description</title>
  66
  67     <para>
  68       <function>sd_bus_process()</function> drives the connection between the
  69       message bus and the client. That is, it handles connecting,
  70       authentication, and message processing. It should be called in a loop
  71       until no further progress can be made or an error occurs.
  72     </para>
  73
  74     <para>
  75       Once no further progress can be made,
  76       <citerefentry><refentrytitle>sd_bus_wait</refentrytitle><manvolnum>3</manvolnum></citerefentry>
  77       should be called. Alternatively the user can wait for incoming data on
  78       the file descriptor returned by
  79       <citerefentry><refentrytitle>sd_bus_get_fd</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
  80     </para>
  81
  82     <para>
  83       <function>sd_bus_process</function> processes at most one incoming
  84       message per call.  If the parameter <parameter>r</parameter> is not NULL
  85       and the call processed a message, <code>*r</code> is set to this message.
  86       The caller owns a reference to this message and should call
  87       <citerefentry><refentrytitle>sd_bus_message_unref</refentrytitle><manvolnum>3</manvolnum></citerefentry>
  88       when the message is no longer needed. If <parameter>r</parameter> is not
  89       NULL, progress was made, but no message was processed, <code>*r</code> is
  90       set to NULL.
  91     </para>
  92   </refsect1>
  93
  94   <refsect1>
  95     <title>Return Value</title>
  96
  97     <para>
  98       If progress was made, a positive integer is returned. If no progress was
  99       made, 0 is returned. If an error occurs, a negative errno-style error code
 100       is returned.
 101     </para>
 102   </refsect1>
 103
 104   <refsect1>
 105     <title>See Also</title>
 106
 107     <para>
 108       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 109       <citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 110     </para>
 111   </refsect1>
 112
 113 </refentry>