man/sd_bus_message_skip.xml

   1 <?xml version='1.0'?>
   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+ -->
   5
   6 <refentry id="sd_bus_message_skip" xmlns:xi="http://www.w3.org/2001/XInclude">
   7   <refentryinfo>
   8     <title>sd_bus_message_skip</title>
   9     <productname>systemd</productname>
  10   </refentryinfo>
  11
  12   <refmeta>
  13     <refentrytitle>sd_bus_message_skip</refentrytitle>
  14     <manvolnum>3</manvolnum>
  15   </refmeta>
  16
  17   <refnamediv>
  18     <refname>sd_bus_message_skip</refname>
  19
  20     <refpurpose>Skip elements in a bus message</refpurpose>
  21   </refnamediv>
  22
  23   <refsynopsisdiv>
  24     <funcsynopsis>
  25       <funcsynopsisinfo>#include &lt;systemd/sd-bus.h&gt;</funcsynopsisinfo>
  26
  27       <funcprototype>
  28         <funcdef>int <function>sd_bus_message_skip</function></funcdef>
  29         <paramdef>sd_bus_message *<parameter>m</parameter></paramdef>
  30         <paramdef>const char* <parameter>types</parameter></paramdef>
  31       </funcprototype>
  32     </funcsynopsis>
  33   </refsynopsisdiv>
  34
  35   <refsect1>
  36     <title>Description</title>
  37
  38     <para><function>sd_bus_message_skip()</function> is somewhat similar to
  39     <citerefentry><refentrytitle>sd_bus_message_read</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
  40     but instead of reading the contents of the message, it only moves the "read pointer". Subsequent
  41     read operations will read the elements that are after the elements that were skipped.</para>
  42
  43     <para>The <parameter>types</parameter> argument has the same meaning as in
  44     <function>sd_bus_message_read()</function>. It may also be <constant>NULL</constant>, to skip a
  45     single element of any type.</para>
  46   </refsect1>
  47
  48   <refsect1>
  49     <title>Return Value</title>
  50
  51     <para>On success, <function>sd_bus_message_skip()</function> returns 0 or a positive integer. On
  52     failure, it returns a negative errno-style error code.</para>
  53
  54     <refsect2>
  55       <title>Errors</title>
  56
  57       <para>Returned errors may indicate the following problems:</para>
  58
  59       <variablelist>
  60         <varlistentry>
  61           <term><constant>-EINVAL</constant></term>
  62
  63           <listitem><para>The <parameter>m</parameter> parameter is
  64           <constant>NULL</constant>.</para></listitem>
  65         </varlistentry>
  66
  67         <varlistentry>
  68           <term><constant>-EBADMSG</constant></term>
  69
  70           <listitem><para>The message cannot be parsed.</para></listitem>
  71         </varlistentry>
  72
  73         <varlistentry>
  74           <term><constant>-EPERM</constant></term>
  75
  76           <listitem><para>The message is not sealed.</para></listitem>
  77         </varlistentry>
  78
  79         <varlistentry>
  80           <term><constant>-ENXIO</constant></term>
  81
  82           <listitem><para>The message end has been reached and the requested elements cannot be read.
  83           </para></listitem>
  84         </varlistentry>
  85
  86         <varlistentry>
  87           <term><constant>-ENOMEM</constant></term>
  88
  89           <listitem><para>Memory allocation failed.</para></listitem>
  90         </varlistentry>
  91       </variablelist>
  92     </refsect2>
  93   </refsect1>
  94
  95   <xi:include href="libsystemd-pkgconfig.xml" />
  96
  97   <refsect1>
  98     <title>See Also</title>
  99
 100     <para>
 101       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 102       <citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 103       <citerefentry><refentrytitle>sd_bus_message_read</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 104       <citerefentry><refentrytitle>sd_bus_message_read_basic</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 105     </para>
 106   </refsect1>
 107
 108 </refentry>