| SD_BUS_MESSAGE_READ_ARRAY(3) | sd_bus_message_read_array | SD_BUS_MESSAGE_READ_ARRAY(3) |
.SH "NAME" sd_bus_message_read_array - Access an array of elements
in a message
.SH "SYNOPSIS"
#include <systemd/sd-bus.h>
.HP 720u int
sd_bus_message_read_array(sd_bus_message *m,
char type,
const void **ret_ptr,
size_t *ret_size);
.SH "DESCRIPTION"
.PP sd_bus_message_read_array() provides access to an array of
elements in the bus message m. The "read pointer" in the
message must be right before an array of type type. A pointer to the
array data is returned in the parameter ret_ptr and the size of the
array data (in bytes) is returned in the parameter ret_size. If this
returns a positive value and the returned ret_size is 0, a valid
non-NULL pointer will be returned as ret_ptr, but it may not
be dereferenced. The data is aligned as 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. If this returns a positive value,
the "read pointer" points at the next element after the array.
.PP 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.
.SH "RETURN VALUE"
.PP On success and when an array was read, sd_bus_message_read_array()
returns an integer greater than zero. If invoked while inside a container
element (such as an array, e.g. when operating on an array of arrays) and
the final element of the outer container has been read already and the read
pointer is thus behind the last element of the outer container this call
returns 0 (and the returned pointer will be NULL and the size will be
0). On failure, it returns a negative errno-style error code.
.SS "Errors"
.PP Returned errors may indicate the following problems:
.PP -EINVAL
Specified type is invalid or not a trivial type (see above), or the message
parameter or one of the output parameters are NULL.
.RE
.PP -EOPNOTSUPP
The byte order in the message is different than native byte order.
.RE
.PP -EPERM
The message is not sealed.
.RE
.PP -EBADMSG
The message cannot be parsed.
.RE
.SH "NOTES"
.PP Functions described here are available as a shared library, which can be
compiled against and linked to with the
libsystemd pkg-config(1) file.
.PP All functions listed here are thread-agnostic and only a single thread
may operate on a given object at any given time. Different threads may
access the same object at different times. Multiple independent objects may
be used from different threads in parallel.
.PP The code described here uses getenv(3), which is declared to be
not multi-thread-safe. This means that the code calling the functions
described here must not call setenv(3) from a parallel thread. It is
recommended to only do calls to setenv() from an early phase of the
program when no other threads have been started.
.SH "HISTORY"
.PP sd_bus_message_read_array() was added in version 240.
.SH "SEE ALSO"
.PP systemd(1), sd-bus(3), sd_bus_message_read(3),
sd_bus_message_read_strv(3)
| systemd 262.2 |