Debian Codegraph @

upstream/debian-unstable/man3/sd_bus_message_read_strv.3

raw
1 '\" t
2 .TH "SD_BUS_MESSAGE_READ_STRV" "3" "" "systemd 261~rc3" "sd_bus_message_read_strv"
3 .\" -----------------------------------------------------------------
4 .\" * Define some portability stuff
5 .\" -----------------------------------------------------------------
6 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
7 .\" http://bugs.debian.org/507673
8 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
9 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
10 .ie \n(.g .ds Aq \(aq
11 .el .ds Aq '
12 .\" -----------------------------------------------------------------
13 .\" * set default formatting
14 .\" -----------------------------------------------------------------
15 .\" disable hyphenation
16 .nh
17 .\" disable justification (adjust text to left margin only)
18 .ad l
19 .\" -----------------------------------------------------------------
20 .\" * MAIN CONTENT STARTS HERE *
21 .\" -----------------------------------------------------------------
22 .SH "NAME"
23 sd_bus_message_read_strv, sd_bus_message_read_strv_extend \- Access an array of strings in a message
24 .SH "SYNOPSIS"
25 .sp
26 .ft B
27 .nf
28 #include <systemd/sd\-bus\&.h>
29 .fi
30 .ft
31 .HP \w'int\ sd_bus_message_read_strv('u
32 .BI "int sd_bus_message_read_strv(sd_bus_message\ *" "m" ", char\ ***" "l" ");"
33 .HP \w'int\ sd_bus_message_read_strv_extend('u
34 .BI "int sd_bus_message_read_strv_extend(sd_bus_message\ *" "m" ", char\ ***" "l" ");"
35 .SH "DESCRIPTION"
36 .PP
37 \fBsd_bus_message_read_strv()\fR
38 reads an array of string\-like items from the message
39 \fIm\fR\&. The "read pointer" in the message must be right before an array of strings (D\-Bus type
40 "as"), object paths (D\-Bus type
41 "ao"), or signatures (D\-Bus type
42 "ag")\&. On success, a pointer to a
43 \fBNULL\fR\-terminated array of strings (strv) is returned in the output parameter
44 \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
45 \fBNULL\fR
46 pointer might be returned here, and should be considered equivalent to an array with zero entries\&.
47 .PP
48 \fBsd_bus_message_read_strv_extend()\fR
49 is similar, but the second parameter is an input\-output parameter\&. If
50 \fI*l\fR
51 is
52 \fBNULL\fR, if behaves identically to
53 \fBsd_bus_message_read_strv()\fR\&. Otherwise,
54 \fI*l\fR
55 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\&.
56 .SH "RETURN VALUE"
57 .PP
58 On success, these functions return a non\-negative integer\&. On failure, they return a negative errno\-style error code\&.
59 .SS "Errors"
60 .PP
61 Returned errors may indicate the following problems:
62 .PP
63 \fB\-EINVAL\fR
64 .RS 4
65 \fIm\fR
66 or
67 \fIl\fR
68 are
69 \fBNULL\fR\&.
70 .sp
71 Added in version 246\&.
72 .RE
73 .PP
74 \fB\-EPERM\fR
75 .RS 4
76 The message is not sealed\&.
77 .sp
78 Added in version 246\&.
79 .RE
80 .PP
81 \fB\-EBADMSG\fR
82 .RS 4
83 The message cannot be parsed\&.
84 .sp
85 Added in version 246\&.
86 .RE
87 .PP
88 \fB\-ENXIO\fR
89 .RS 4
90 The message "read pointer" is not right before an array of the appropriate type\&.
91 .sp
92 Added in version 248\&.
93 .RE
94 .SH "HISTORY"
95 .PP
96 \fBsd_bus_message_read_strv()\fR
97 was added in version 246\&.
98 .PP
99 \fBsd_bus_message_read_strv_extend()\fR
100 was added in version 252\&.
101 .SH "SEE ALSO"
102 .PP
103 \fBsystemd\fR(1), \fBsd-bus\fR(3), \fBsd_bus_message_read\fR(3)