Index · Directives systemd 254

Name

sd_bus_message_read_basic — Read a basic type from a message

Synopsis

#include <systemd/sd-bus.h>
int sd_bus_message_read_basic(sd_bus_message *m,
 char type,
 void *p);
 

Description

sd_bus_message_read_basic() reads a basic type from a message and advances the read position in the message. The set of basic types and their ascii codes passed in type are described in the D-Bus Specification.

If p is not NULL, it should contain a pointer to an appropriate object. For example, if type is 'y', the object passed in p should have type uint8_t *. If type is 's', the object passed in p should have type const char **. Note that, if the basic type is a pointer (e.g., const char * 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 message's lifetime. Similarly, during the lifetime of such a pointer, the message must not be modified. If type is 'h' (UNIX file descriptor), the descriptor is not duplicated by this call and the returned descriptor remains in possession of the message object, and needs to be duplicated by the caller in order to keep an open reference to it after the message object is freed (for example by calling "fcntl(fd, FD_DUPFD_CLOEXEC, 3)"). See the table below for a complete list of allowed types.

Table 1. Item type specifiers

SpecifierConstantDescriptionExpected C Type
"y"SD_BUS_TYPE_BYTE8-bit unsigned integeruint8_t *
"b"SD_BUS_TYPE_BOOLEANbooleanint * (NB: not bool *)
"n"SD_BUS_TYPE_INT1616-bit signed integerint16_t *
"q"SD_BUS_TYPE_UINT1616-bit unsigned integeruint16_t *
"i"SD_BUS_TYPE_INT3232-bit signed integerint32_t *
"u"SD_BUS_TYPE_UINT3232-bit unsigned integeruint32_t *
"x"SD_BUS_TYPE_INT6464-bit signed integerint64_t *
"t"SD_BUS_TYPE_UINT6464-bit unsigned integeruint64_t *
"d"SD_BUS_TYPE_DOUBLEIEEE 754 double precision floating-pointdouble *
"s"SD_BUS_TYPE_STRINGUTF-8 stringconst char **
"o"SD_BUS_TYPE_OBJECT_PATHD-Bus object path stringconst char **
"g"SD_BUS_TYPE_SIGNATURED-Bus signature stringconst char **
"h"SD_BUS_TYPE_UNIX_FDUNIX file descriptorint *

If there is no object of the specified type at the current position in the message, an error is returned.

Return Value

On success, sd_bus_message_read_basic() returns a positive integer. If the end of the currently opened array has been reached, it returns 0. On failure, it returns a negative errno-style error code.

Errors

Returned errors may indicate the following problems:

-EINVAL

Specified type string is invalid or the message parameter is NULL.

-ENXIO

The message does not contain the specified type at current position.

-EBADMSG

The message cannot be parsed.

See Also

systemd(1), sd-bus(3), sd_bus_message_append_basic(3), sd_bus_message_skip(3), sd_bus_message_read(3)