Debian Codegraph @

upstream/debian-unstable/man3/sd_bus_enqueue_for_read.3

raw
1 '\" t
2 .TH "SD_BUS_ENQUEUE_FOR_READ" "3" "" "systemd 261~rc3" "sd_bus_enqueue_for_read"
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_enqueue_for_read \- Re\-enqueue a bus message on a bus connection, for reading
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_enqueue_for_read('u
32 .BI "int sd_bus_enqueue_for_read(sd_bus\ *" "bus" ", sd_bus_message\ *" "message" ");"
33 .SH "DESCRIPTION"
34 .PP
35 \fBsd_bus_enqueue_for_read()\fR
36 may be used to re\-enqueue an incoming bus message on the local read queue, so that it is processed and dispatched locally again, similarly to how an incoming message from the peer is processed\&. Takes a bus connection object and the message to enqueue\&. A reference is taken of the message and the caller\*(Aqs reference thus remains in possession of the caller\&. The message is enqueued at the end of the queue, thus will be dispatched after all other already queued messages are dispatched\&.
37 .PP
38 This call is primarily useful for dealing with incoming method calls that may be processed only after an additional asynchronous operation completes\&. One example are PolicyKit authorization requests that are determined to be necessary to authorize a newly incoming method call: when the PolicyKit response is received the original method call may be re\-enqueued to process it again, this time with the authorization result known\&.
39 .SH "RETURN VALUE"
40 .PP
41 On success, this function return 0 or a positive integer\&. On failure, it returns a negative errno\-style error code\&.
42 .SS "Errors"
43 .PP
44 Returned errors may indicate the following problems:
45 .PP
46 \fB\-ECHILD\fR
47 .RS 4
48 The bus connection has been created in a different process, library or module instance\&.
49 .RE
50 .SH "NOTES"
51 .PP
52 Functions described here are available as a shared library, which can be compiled against and linked to with the
53 \fBlibsystemd\fR\ \&\fBpkg-config\fR(1)
54 file\&.
55 .PP
56 The code described here uses
57 \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
58 \fBsetenv\fR(3)
59 from a parallel thread\&. It is recommended to only do calls to
60 \fBsetenv()\fR
61 from an early phase of the program when no other threads have been started\&.
62 .SH "HISTORY"
63 .PP
64 \fBsd_bus_enqueue_for_read()\fR
65 was added in version 245\&.
66 .SH "SEE ALSO"
67 .PP
68 \fBsystemd\fR(1), \fBsd-bus\fR(3), \fBsd_bus_send\fR(3)