Debian Codegraph @

upstream/debian-unstable/man3/sd_bus_send.3

raw
1 '\" t
2 .TH "SD_BUS_SEND" "3" "" "systemd 261~rc3" "sd_bus_send"
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_send, sd_bus_send_to, sd_bus_message_send \- Queue a D\-Bus message for transfer
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_send('u
32 .BI "int sd_bus_send(sd_bus\ *" "bus" ", sd_bus_message\ *" "m" ", uint64_t\ *" "cookie" ");"
33 .HP \w'int\ sd_bus_send_to('u
34 .BI "int sd_bus_send_to(sd_bus\ *" "bus" ", sd_bus_message\ *" "m" ", const\ char\ *" "destination" ", uint64_t\ *" "cookie" ");"
35 .HP \w'int\ sd_bus_message_send('u
36 .BI "int sd_bus_message_send(sd_bus_message\ *" "m" ");"
37 .SH "DESCRIPTION"
38 .PP
39 \fBsd_bus_send()\fR
40 queues the bus message object
41 \fIm\fR
42 for transfer\&. If
43 \fIbus\fR
44 is
45 \fBNULL\fR, the bus that
46 \fIm\fR
47 is attached to is used\&.
48 \fIbus\fR
49 only needs to be set when the message is sent to a different bus than the one it is attached to, for example when forwarding messages\&. If the output parameter
50 \fIcookie\fR
51 is not
52 \fBNULL\fR, it is set to the message identifier\&. This value can later be used to match incoming replies to their corresponding messages\&. If
53 \fIcookie\fR
54 is set to
55 \fBNULL\fR
56 and the message is not sealed,
57 \fBsd_bus_send()\fR
58 assumes the message
59 \fIm\fR
60 does not expect a reply and adds the necessary headers to indicate this\&.
61 .PP
62 Note that in most scenarios,
63 \fBsd_bus_send()\fR
64 should not be called directly\&. Instead, use higher level functions such as
65 \fBsd_bus_call_method\fR(3)
66 and
67 \fBsd_bus_reply_method_return\fR(3)
68 which call
69 \fBsd_bus_send()\fR
70 internally\&.
71 .PP
72 \fBsd_bus_send_to()\fR
73 is a shorthand for sending a message to a specific destination\&. It\*(Aqs main use case is to simplify sending unicast signal messages (signals that only have a single receiver)\&. It\*(Aqs behavior is similar to calling
74 \fBsd_bus_message_set_destination\fR(3)
75 followed by calling
76 \fBsd_bus_send()\fR\&.
77 .PP
78 \fBsd_bus_send()\fR/\fBsd_bus_send_to()\fR
79 will write the message directly to the underlying transport (e\&.g\&. kernel socket buffer) if possible\&. If the connection is not set up fully yet the message is queued locally\&. If the transport buffers are congested any unwritten message data is queued locally, too\&. If the connection has been closed or is currently being closed the call fails\&.
80 \fBsd_bus_process\fR(3)
81 should be invoked to write out any queued message data to the transport\&.
82 .PP
83 \fBsd_bus_message_send()\fR
84 is the same as
85 \fBsd_bus_send()\fR
86 but without the first and last argument\&.
87 \fBsd_bus_message_send(m)\fR
88 is equivalent to
89 \fBsd_bus_send(sd_bus_message_get_bus(m), m, NULL)\fR\&.
90 .SH "RETURN VALUE"
91 .PP
92 On success, these functions return a non\-negative integer\&. On failure, they return a negative errno\-style error code\&.
93 .SS "Errors"
94 .PP
95 Returned errors may indicate the following problems:
96 .PP
97 \fB\-EINVAL\fR
98 .RS 4
99 The input parameter
100 \fIm\fR
101 is
102 \fBNULL\fR\&.
103 .sp
104 Added in version 246\&.
105 .RE
106 .PP
107 \fB\-EOPNOTSUPP\fR
108 .RS 4
109 The bus connection does not support sending file descriptors\&.
110 .sp
111 Added in version 246\&.
112 .RE
113 .PP
114 \fB\-ECHILD\fR
115 .RS 4
116 The bus connection was allocated in a parent process and is being reused in a child process after
117 \fBfork()\fR\&.
118 .sp
119 Added in version 246\&.
120 .RE
121 .PP
122 \fB\-ENOBUFS\fR
123 .RS 4
124 The bus connection\*(Aqs write queue is full\&.
125 .sp
126 Added in version 246\&.
127 .RE
128 .PP
129 \fB\-ENOTCONN\fR
130 .RS 4
131 The input parameter
132 \fIbus\fR
133 is
134 \fBNULL\fR
135 or the bus is not connected\&.
136 .sp
137 Added in version 246\&.
138 .RE
139 .PP
140 \fB\-ECONNRESET\fR
141 .RS 4
142 The bus connection was closed while waiting for the response\&.
143 .sp
144 Added in version 246\&.
145 .RE
146 .PP
147 \fB\-ENOMEM\fR
148 .RS 4
149 Memory allocation failed\&.
150 .sp
151 Added in version 246\&.
152 .RE
153 .SH "NOTES"
154 .PP
155 Functions described here are available as a shared library, which can be compiled against and linked to with the
156 \fBlibsystemd\fR\ \&\fBpkg-config\fR(1)
157 file\&.
158 .PP
159 The code described here uses
160 \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
161 \fBsetenv\fR(3)
162 from a parallel thread\&. It is recommended to only do calls to
163 \fBsetenv()\fR
164 from an early phase of the program when no other threads have been started\&.
165 .SH "HISTORY"
166 .PP
167 \fBsd_bus_send()\fR
168 and
169 \fBsd_bus_send_to()\fR
170 were added in version 246\&.
171 .SH "SEE ALSO"
172 .PP
173 \fBsystemd\fR(1), \fBsd-bus\fR(3), \fBsd_bus_call_method\fR(3), \fBsd_bus_message_set_destination\fR(3), \fBsd_bus_reply_method_return\fR(3), \fBsd_bus_process\fR(3)