Debian Codegraph @

upstream/debian-unstable/man3/sd_bus_list_names.3

raw
1 '\" t
2 .TH "SD_BUS_LIST_NAMES" "3" "" "systemd 261~rc3" "sd_bus_list_names"
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_list_names \- Retrieve information about registered names on a bus
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_list_names('u
32 .BI "int sd_bus_list_names(sd_bus\ *" "bus" ", char\ ***" "acquired" ", char\ ***" "activatable" ");"
33 .SH "DESCRIPTION"
34 .PP
35 \fBsd_bus_list_names()\fR
36 retrieves information about the registered names on a bus\&. If
37 \fIacquired\fR
38 is not
39 \fBNULL\fR, this function calls
40 \m[blue]\fBorg\&.freedesktop\&.DBus\&.ListNames\fR\m[]\&\s-2\u[1]\d\s+2
41 to retrieve the list of currently\-owned names on the bus\&. If
42 \fIacquired\fR
43 is not
44 \fBNULL\fR, the function calls
45 \m[blue]\fBorg\&.freedesktop\&.DBus\&.ListActivableNames\fR\m[]\&\s-2\u[2]\d\s+2
46 to retrieve the list of all names on the bus that can be activated\&. Note that ownership of the arrays returned by
47 \fBsd_bus_list_names()\fR
48 in
49 \fIacquired\fR
50 and
51 \fIactivatable\fR
52 is transferred to the caller and hence, the caller is responsible for freeing these arrays and their contents\&.
53 .SH "RETURN VALUE"
54 .PP
55 On success,
56 \fBsd_bus_list_names()\fR
57 returns a non\-negative integer\&. On failure, it returns a negative errno\-style error code\&.
58 .SS "Errors"
59 .PP
60 Returned errors may indicate the following problems:
61 .PP
62 \fB\-EINVAL\fR
63 .RS 4
64 \fIbus\fR
65 or both
66 \fIacquired\fR
67 and
68 \fIactivatable\fR
69 were
70 \fBNULL\fR\&.
71 .RE
72 .PP
73 \fB\-ENOPKG\fR
74 .RS 4
75 The bus cannot be resolved\&.
76 .RE
77 .PP
78 \fB\-ECHILD\fR
79 .RS 4
80 The bus was created in a different process, library or module instance\&.
81 .RE
82 .PP
83 \fB\-ENOMEM\fR
84 .RS 4
85 Memory allocation failed\&.
86 .RE
87 .PP
88 \fB\-ENOTCONN\fR
89 .RS 4
90 The bus is not connected\&.
91 .RE
92 .SH "NOTES"
93 .PP
94 Functions described here are available as a shared library, which can be compiled against and linked to with the
95 \fBlibsystemd\fR\ \&\fBpkg-config\fR(1)
96 file\&.
97 .PP
98 The code described here uses
99 \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
100 \fBsetenv\fR(3)
101 from a parallel thread\&. It is recommended to only do calls to
102 \fBsetenv()\fR
103 from an early phase of the program when no other threads have been started\&.
104 .SH "HISTORY"
105 .PP
106 \fBsd_bus_list_names()\fR
107 was added in version 221\&.
108 .SH "SEE ALSO"
109 .PP
110 \fBsystemd\fR(1), \fBsd-bus\fR(3)
111 .SH "NOTES"
112 .IP " 1." 4
113 org.freedesktop.DBus.ListNames
114 .RS 4
115 \%https://dbus.freedesktop.org/doc/dbus-specification.html#bus-messages-list-names
116 .RE
117 .IP " 2." 4
118 org.freedesktop.DBus.ListActivableNames
119 .RS 4
120 \%https://dbus.freedesktop.org/doc/dbus-specification.html#bus-messages-list-activatable-names
121 .RE