sd_bus_message_read_strv, sd_bus_message_read_strv_extend — Access an array of strings in a message
#include <systemd/sd-bus.h>
int sd_bus_message_read_strv( | sd_bus_message *m, |
char ***l); |
int sd_bus_message_read_strv_extend( | sd_bus_message *m, |
char ***l); |
sd_bus_message_read_strv() reads an array of string-like items from the
message m. The "read pointer" in the message must be right before an array of
strings (D-Bus type "as"), object paths (D-Bus type "ao"), or
signatures (D-Bus type "ag"). On success, a pointer to a
NULL-terminated array of strings (strv) is returned in the output parameter
l. Note that ownership of this array is transferred to the caller. Hence, the
caller is responsible for freeing this array and its contents. Also note that as a matter of
optimization, if an empty array is encountered a NULL pointer might be returned
here, and should be considered equivalent to an array with zero entries.
sd_bus_message_read_strv_extend() is similar, but the second parameter is an
input-output parameter. If *l is NULL, if behaves identically
to sd_bus_message_read_strv(). Otherwise, *l must point to a
strv, which will be reallocated and extended with additional strings. This function is particularly
useful when combining multiple lists of strings in a message or messages into a single array of strings.
On success, these functions return a non-negative integer. On failure, they return a negative errno-style error code.
Functions described here are available as a shared
library, which can be compiled against and linked to with the
libsystemd pkg-config(1)
file.
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.
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.
sd_bus_message_read_strv() was added in version 246.
sd_bus_message_read_strv_extend() was added in version 252.