'\" t
.TH "SD_BUS_MESSAGE_READ_STRV" "3" "" "systemd 261.2" "sd_bus_message_read_strv"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
sd_bus_message_read_strv, sd_bus_message_read_strv_extend \- Access an array of strings in a message
.SH "SYNOPSIS"
.sp
.ft B
.nf
#include <systemd/sd\-bus\&.h>
.fi
.ft
.HP \w'int\ sd_bus_message_read_strv('u
.BI "int sd_bus_message_read_strv(sd_bus_message\ *" "m" ", char\ ***" "l" ");"
.HP \w'int\ sd_bus_message_read_strv_extend('u
.BI "int sd_bus_message_read_strv_extend(sd_bus_message\ *" "m" ", char\ ***" "l" ");"
.SH "DESCRIPTION"
.PP
\fBsd_bus_message_read_strv()\fR
reads an array of string\-like items from the message
\fIm\fR\&. 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
\fBNULL\fR\-terminated array of strings (strv) is returned in the output parameter
\fIl\fR\&. 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
\fBNULL\fR
pointer might be returned here, and should be considered equivalent to an array with zero entries\&.
.PP
\fBsd_bus_message_read_strv_extend()\fR
is similar, but the second parameter is an input\-output parameter\&. If
\fI*l\fR
is
\fBNULL\fR, if behaves identically to
\fBsd_bus_message_read_strv()\fR\&. Otherwise,
\fI*l\fR
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\&.
.SH "RETURN VALUE"
.PP
On success, these functions return a non\-negative integer\&. On failure, they return a negative errno\-style error code\&.
.SS "Errors"
.PP
Returned errors may indicate the following problems:
.PP
\fB\-EINVAL\fR
.RS 4
\fIm\fR
or
\fIl\fR
are
\fBNULL\fR\&.
.sp
Added in version 246\&.
.RE
.PP
\fB\-EPERM\fR
.RS 4
The message is not sealed\&.
.sp
Added in version 246\&.
.RE
.PP
\fB\-EBADMSG\fR
.RS 4
The message cannot be parsed\&.
.sp
Added in version 246\&.
.RE
.PP
\fB\-ENXIO\fR
.RS 4
The message "read pointer" is not right before an array of the appropriate type\&.
.sp
Added in version 248\&.
.RE
.SH "NOTES"
.PP
Functions described here are available as a shared library, which can be compiled against and linked to with the
\fBlibsystemd\fR\ \&\fBpkg-config\fR(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
\fBgetenv\fR(3), which is declared to be not multi\-thread\-safe\&. This means that the code calling the functions described here must not call
\fBsetenv\fR(3)
from a parallel thread\&. It is recommended to only do calls to
\fBsetenv()\fR
from an early phase of the program when no other threads have been started\&.
.SH "HISTORY"
.PP
\fBsd_bus_message_read_strv()\fR
was added in version 246\&.
.PP
\fBsd_bus_message_read_strv_extend()\fR
was added in version 252\&.
.SH "SEE ALSO"
.PP
\fBsystemd\fR(1), \fBsd-bus\fR(3), \fBsd_bus_message_read\fR(3)