picnoir
/
Systemd
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

Merge pull request #14685 from poettering/sd-bus-bool-as-int 

sd-bus documentation: highlight bool vs. int situation
This commit is contained in:
Lennart Poettering 2020-01-28 17:57:30 +01:00 committed by GitHub
parent b940fb1f4f e0db55a643
commit 7d20404816
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
3 changed files with 46 additions and 34 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

18
man/sd_bus_message_read.xml
View File

@ -60,13 +60,13 @@
<para>For each type specified in the type string, one or more arguments need to be specified
after the <parameter>types</parameter> parameter, in the same order. The arguments must be
pointers to appropriate types (a pointer to <code>int8_t</code> for a <literal>y</literal> in
the type string, a pointer to <code>int32_t</code> for an <literal>i</literal>, a pointer to
<code>const char*</code> for an <literal>s</literal>, ...) which are set based on the values in
pointers to appropriate types (a pointer to <type>int8_t</type> for a <literal>y</literal> in
the type string, a pointer to <type>int32_t</type> for an <literal>i</literal>, a pointer to
<type>const char*</type> for an <literal>s</literal>, ...) which are set based on the values in
the message. As an exception, in case or array and variant types, the first argument is an
"input" argument that further specifies how the message should be read. See the table below for
a complete list of allowed arguments and their types. Note that, if the basic type is a pointer
(e.g., <code>const char *</code> in the case of a string), the argument is a pointer to a
(e.g., <type>const char *</type> in the case of a string), the argument is a pointer to a
pointer, and also the pointer value that is written is only borrowed and the contents must be
copied if they are to be used after the end of the messages lifetime.</para>
@ -99,7 +99,7 @@
<entry><literal>a</literal></entry>
<entry><constant>SD_BUS_TYPE_ARRAY</constant></entry>
<entry>array</entry>
<entry>int, which specifies the expected length <parameter>n</parameter> of the array</entry>
<entry><type>int</type>, which specifies the expected length <parameter>n</parameter> of the array</entry>
<entry><parameter>n</parameter> sets of arguments appropriate for the array element type</entry>
</row>
@ -174,6 +174,14 @@ int64_t x;
sd_bus_message_read(m, "x", &amp;x);</programlisting>
<para>Read a boolean value:</para>
<programlisting>sd_bus_message *m;
int x; /* Do not use C99 'bool' type here, it's typically smaller
in memory and would cause memory corruption */
sd_bus_message_read(m, "b", &amp;x);</programlisting>
<para>Read all types of integers:</para>
<programlisting>uint8_t y;

8
man/sd_bus_message_read_array.xml
View File

@ -48,6 +48,10 @@
appropriate for the data type. The data is part of the message — it may not be modified and is
valid only as long as the message is referenced. After this function returns, the "read pointer"
points at the next element after the array.</para>
<para>Note that this function only supports arrays of trivial types, i.e. arrays of booleans, the various
integer types, as well as floating point numbers. In particular it may not be used for arrays of strings,
structures or similar.</para>
</refsect1>
<refsect1>
@ -68,8 +72,8 @@
<varlistentry>
<term><constant>-EINVAL</constant></term>
<listitem><para>Specified type is invalid or the message parameter or one of the output
parameters are <constant>NULL</constant>.</para></listitem>
<listitem><para>Specified type is invalid or not a trivial type (see above), or the message
parameter or one of the output parameters are <constant>NULL</constant>.</para></listitem>
</varlistentry>
<varlistentry>

54
man/sd_bus_message_read_basic.xml
View File

@ -55,10 +55,10 @@
If <parameter>p</parameter> is not <constant>NULL</constant>, it should contain
a pointer to an appropriate object. For example, if <parameter>type</parameter>
is <constant>'y'</constant>, the object passed in <parameter>p</parameter>
should have type <code>uint8_t *</code>. If <parameter>type</parameter> is
should have type <type>uint8_t *</type>. If <parameter>type</parameter> is
<constant>'s'</constant>, the object passed in <parameter>p</parameter> should
have type <code>const char **</code>. Note that, if the basic type is a pointer
(e.g., <code>const char *</code> in the case of a string), the pointer is only
have type <type>const char **</type>. Note that, if the basic type is a pointer
(e.g., <type>const char *</type> in the case of a string), the pointer is only
borrowed and the contents must be copied if they are to be used after the end
of the messages lifetime. Similarly, during the lifetime of such a pointer, the
message must not be modified. See the table below for a complete list of allowed
@ -85,92 +85,92 @@
<row>
<entry><literal>y</literal></entry>
<entry><constant>SD_BUS_TYPE_BYTE</constant></entry>
<entry>unsigned integer</entry>
<entry>uint8_t *</entry>
<entry>8bit unsigned integer</entry>
<entry><type>uint8_t *</type></entry>
</row>
<row>
<entry><literal>b</literal></entry>
<entry><constant>SD_BUS_TYPE_BOOLEAN</constant></entry>
<entry>boolean</entry>
<entry>int *</entry>
<entry><type>int *</type> (NB: not <type>bool *</type>)</entry>
</row>
<row>
<entry><literal>n</literal></entry>
<entry><constant>SD_BUS_TYPE_INT16</constant></entry>
<entry>signed integer</entry>
<entry>int16_t *</entry>
<entry>16bit signed integer</entry>
<entry><type>int16_t *</type></entry>
</row>
<row>
<entry><literal>q</literal></entry>
<entry><constant>SD_BUS_TYPE_UINT16</constant></entry>
<entry>unsigned integer</entry>
<entry>uint16_t *</entry>
<entry>16bit unsigned integer</entry>
<entry><type>uint16_t *</type></entry>
</row>
<row>
<entry><literal>i</literal></entry>
<entry><constant>SD_BUS_TYPE_INT32</constant></entry>
<entry>signed integer</entry>
<entry>int32_t *</entry>
<entry>32bit signed integer</entry>
<entry><type>int32_t *</type></entry>
</row>
<row>
<entry><literal>u</literal></entry>
<entry><constant>SD_BUS_TYPE_UINT32</constant></entry>
<entry>unsigned integer</entry>
<entry>uint32_t *</entry>
<entry>32bit unsigned integer</entry>
<entry><type>uint32_t *</type></entry>
</row>
<row>
<entry><literal>x</literal></entry>
<entry><constant>SD_BUS_TYPE_INT64</constant></entry>
<entry>signed integer</entry>
<entry>int64_t *</entry>
<entry>64bit signed integer</entry>
<entry><type>int64_t *</type></entry>
</row>
<row>
<entry><literal>t</literal></entry>
<entry><constant>SD_BUS_TYPE_UINT64</constant></entry>
<entry>unsigned integer</entry>
<entry>uint64_t *</entry>
<entry>64bit unsigned integer</entry>
<entry><type>uint64_t *</type></entry>
</row>
<row>
<entry><literal>d</literal></entry>
<entry><constant>SD_BUS_TYPE_DOUBLE</constant></entry>
<entry>floating-point</entry>
<entry>double *</entry>
<entry>IEEE 754 double precision floating-point</entry>
<entry><type>double *</type></entry>
</row>
<row>
<entry><literal>s</literal></entry>
<entry><constant>SD_BUS_TYPE_STRING</constant></entry>
<entry>Unicode string</entry>
<entry>const char **</entry>
<entry>UTF-8 string</entry>
<entry><type>const char **</type></entry>
</row>
<row>
<entry><literal>o</literal></entry>
<entry><constant>SD_BUS_TYPE_OBJECT_PATH</constant></entry>
<entry>object path</entry>
<entry>const char **</entry>
<entry>D-Bus object path stringy</entry>
<entry><type>const char **</type></entry>
</row>
<row>
<entry><literal>g</literal></entry>
<entry><constant>SD_BUS_TYPE_SIGNATURE</constant></entry>
<entry>signature</entry>
<entry>const char **</entry>
<entry>D-Bus signature string</entry>
<entry><type>const char **</type></entry>
</row>
<row>
<entry><literal>h</literal></entry>
<entry><constant>SD_BUS_TYPE_UNIX_FD</constant></entry>
<entry>UNIX file descriptor</entry>
<entry>int *</entry>
<entry><type>int *</type></entry>
</row>
</tbody>
</tgroup>