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 5<!-- 6 SPDX-License-Identifier: LGPL-2.1-or-later 7 8 Copyright © 2016 Julian Orth 9--> 10 11<refentry id="sd_bus_message_read_basic"> 12 13 <refentryinfo> 14 <title>sd_bus_message_read_basic</title> 15 <productname>systemd</productname> 16 </refentryinfo> 17 18 <refmeta> 19 <refentrytitle>sd_bus_message_read_basic</refentrytitle> 20 <manvolnum>3</manvolnum> 21 </refmeta> 22 23 <refnamediv> 24 <refname>sd_bus_message_read_basic</refname> 25 26 <refpurpose>Read a basic type from a message</refpurpose> 27 </refnamediv> 28 29 <refsynopsisdiv> 30 <funcsynopsis> 31 <funcsynopsisinfo>#include <systemd/sd-bus.h></funcsynopsisinfo> 32 33 <funcprototype> 34 <funcdef>int <function>sd_bus_message_read_basic</function></funcdef> 35 <paramdef>sd_bus_message *<parameter>m</parameter></paramdef> 36 <paramdef>char <parameter>type</parameter></paramdef> 37 <paramdef>void *<parameter>p</parameter></paramdef> 38 </funcprototype> 39 </funcsynopsis> 40 </refsynopsisdiv> 41 42 <refsect1> 43 <title>Description</title> 44 45 <para> 46 <function>sd_bus_message_read_basic()</function> reads a basic type from a 47 message and advances the read position in the message. The set of basic 48 types and their ascii codes passed in <parameter>type</parameter> are 49 described in the <ulink 50 url="https://dbus.freedesktop.org/doc/dbus-specification.html">D-Bus 51 Specification</ulink>. 52 </para> 53 54 <para> 55 If <parameter>p</parameter> is not <constant>NULL</constant>, it should contain a pointer to an 56 appropriate object. For example, if <parameter>type</parameter> is <constant>'y'</constant>, the object 57 passed in <parameter>p</parameter> should have type <type>uint8_t *</type>. If 58 <parameter>type</parameter> is <constant>'s'</constant>, the object passed in <parameter>p</parameter> 59 should have type <type>const char **</type>. Note that, if the basic type is a pointer (e.g., 60 <type>const char *</type> in the case of a string), the pointer is only borrowed and the contents must 61 be copied if they are to be used after the end of the message's lifetime. Similarly, during the 62 lifetime of such a pointer, the message must not be modified. If <parameter>type</parameter> is 63 <constant>'h'</constant> (UNIX file descriptor), the descriptor is not duplicated by this call and the 64 returned descriptor remains in possession of the message object, and needs to be duplicated by the 65 caller in order to keep an open reference to it after the message object is freed (for example by 66 calling <literal>fcntl(fd, FD_DUPFD_CLOEXEC, 3)</literal>). See the table below for a complete list of 67 allowed types. 68 </para> 69 70 <table id='format-specifiers'> 71 <title>Item type specifiers</title> 72 73 <tgroup cols='4'> 74 <colspec colname='specifier' /> 75 <colspec colname='constant' /> 76 <colspec colname='description' /> 77 <colspec colname='ctype' /> 78 <thead> 79 <row> 80 <entry>Specifier</entry> 81 <entry>Constant</entry> 82 <entry>Description</entry> 83 <entry>Expected C Type</entry> 84 </row> 85 </thead> 86 <tbody> 87 <row> 88 <entry><literal>y</literal></entry> 89 <entry><constant>SD_BUS_TYPE_BYTE</constant></entry> 90 <entry>8bit unsigned integer</entry> 91 <entry><type>uint8_t *</type></entry> 92 </row> 93 94 <row> 95 <entry><literal>b</literal></entry> 96 <entry><constant>SD_BUS_TYPE_BOOLEAN</constant></entry> 97 <entry>boolean</entry> 98 <entry><type>int *</type> (NB: not <type>bool *</type>)</entry> 99 </row> 100 101 <row> 102 <entry><literal>n</literal></entry> 103 <entry><constant>SD_BUS_TYPE_INT16</constant></entry> 104 <entry>16bit signed integer</entry> 105 <entry><type>int16_t *</type></entry> 106 </row> 107 108 <row> 109 <entry><literal>q</literal></entry> 110 <entry><constant>SD_BUS_TYPE_UINT16</constant></entry> 111 <entry>16bit unsigned integer</entry> 112 <entry><type>uint16_t *</type></entry> 113 </row> 114 115 <row> 116 <entry><literal>i</literal></entry> 117 <entry><constant>SD_BUS_TYPE_INT32</constant></entry> 118 <entry>32bit signed integer</entry> 119 <entry><type>int32_t *</type></entry> 120 </row> 121 122 <row> 123 <entry><literal>u</literal></entry> 124 <entry><constant>SD_BUS_TYPE_UINT32</constant></entry> 125 <entry>32bit unsigned integer</entry> 126 <entry><type>uint32_t *</type></entry> 127 </row> 128 129 <row> 130 <entry><literal>x</literal></entry> 131 <entry><constant>SD_BUS_TYPE_INT64</constant></entry> 132 <entry>64bit signed integer</entry> 133 <entry><type>int64_t *</type></entry> 134 </row> 135 136 <row> 137 <entry><literal>t</literal></entry> 138 <entry><constant>SD_BUS_TYPE_UINT64</constant></entry> 139 <entry>64bit unsigned integer</entry> 140 <entry><type>uint64_t *</type></entry> 141 </row> 142 143 <row> 144 <entry><literal>d</literal></entry> 145 <entry><constant>SD_BUS_TYPE_DOUBLE</constant></entry> 146 <entry>IEEE 754 double precision floating-point</entry> 147 <entry><type>double *</type></entry> 148 </row> 149 150 <row> 151 <entry><literal>s</literal></entry> 152 <entry><constant>SD_BUS_TYPE_STRING</constant></entry> 153 <entry>UTF-8 string</entry> 154 <entry><type>const char **</type></entry> 155 </row> 156 157 <row> 158 <entry><literal>o</literal></entry> 159 <entry><constant>SD_BUS_TYPE_OBJECT_PATH</constant></entry> 160 <entry>D-Bus object path string</entry> 161 <entry><type>const char **</type></entry> 162 </row> 163 164 <row> 165 <entry><literal>g</literal></entry> 166 <entry><constant>SD_BUS_TYPE_SIGNATURE</constant></entry> 167 <entry>D-Bus signature string</entry> 168 <entry><type>const char **</type></entry> 169 </row> 170 171 <row> 172 <entry><literal>h</literal></entry> 173 <entry><constant>SD_BUS_TYPE_UNIX_FD</constant></entry> 174 <entry>UNIX file descriptor</entry> 175 <entry><type>int *</type></entry> 176 </row> 177 </tbody> 178 </tgroup> 179 </table> 180 181 <para> 182 If there is no object of the specified type at the current position in the 183 message, an error is returned. 184 </para> 185 </refsect1> 186 187 <refsect1> 188 <title>Return Value</title> 189 190 <para> 191 On success, <function>sd_bus_message_read_basic()</function> returns a positive integer. 192 If the end of the currently opened array has been reached, it returns 0. 193 On failure, it returns a negative errno-style error code. 194 </para> 195 196 <refsect2 id='errors'> 197 <title>Errors</title> 198 199 <para>Returned errors may indicate the following problems:</para> 200 201 <variablelist> 202 <varlistentry id="errors-einval"> 203 <term><constant>-EINVAL</constant></term> 204 205 <listitem><para>Specified type string is invalid or the message parameter is 206 <constant>NULL</constant>.</para></listitem> 207 </varlistentry> 208 209 <varlistentry id="errors-enxio"> 210 <term><constant>-ENXIO</constant></term> 211 212 <listitem><para>The message does not contain the specified type at current position. 213 </para></listitem> 214 </varlistentry> 215 216 <varlistentry id="errors-ebadmsg"> 217 <term><constant>-EBADMSG</constant></term> 218 219 <listitem><para>The message cannot be parsed.</para></listitem> 220 </varlistentry> 221 </variablelist> 222 </refsect2> 223 </refsect1> 224 225 <refsect1> 226 <title>See Also</title> 227 228 <para> 229 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, 230 <citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>, 231 <citerefentry><refentrytitle>sd_bus_message_append_basic</refentrytitle><manvolnum>3</manvolnum></citerefentry>, 232 <citerefentry><refentrytitle>sd_bus_message_skip</refentrytitle><manvolnum>3</manvolnum></citerefentry>, 233 <citerefentry><refentrytitle>sd_bus_message_read</refentrytitle><manvolnum>3</manvolnum></citerefentry> 234 </para> 235 </refsect1> 236 237</refentry> 238