Debian Codegraph @

upstream/debian-unstable/man3/sd_bus_message_new_method_error.3

raw
1 '\" t
2 .TH "SD_BUS_MESSAGE_NEW_METHOD_ERROR" "3" "" "systemd 261~rc3" "sd_bus_message_new_method_error"
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_new_method_error, sd_bus_message_new_method_errorf, sd_bus_message_new_method_errno, sd_bus_message_new_method_errnof \- Create an error reply for a method call
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_new_method_error('u
32 .BI "int sd_bus_message_new_method_error(sd_bus_message\ *" "call" ", sd_bus_message\ **" "m" ", const\ sd_bus_error\ *" "e" ");"
33 .HP \w'int\ sd_bus_message_new_method_errorf('u
34 .BI "int sd_bus_message_new_method_errorf(sd_bus_message\ *" "call" ", sd_bus_message\ **" "m" ", const\ char\ *" "name" ", const\ char\ *" "format" ", \&...);"
35 .HP \w'int\ sd_bus_message_new_method_errno('u
36 .BI "int sd_bus_message_new_method_errno(sd_bus_message\ *" "call" ", sd_bus_message\ **" "m" ", int\ " "error" ", const\ sd_bus_error\ *" "p" ");"
37 .HP \w'int\ sd_bus_message_new_method_errnof('u
38 .BI "int sd_bus_message_new_method_errnof(sd_bus_message\ *" "call" ", sd_bus_message\ **" "m" ", int\ " "error" ", const\ char\ *" "format" ", \&...);"
39 .SH "DESCRIPTION"
40 .PP
41 The
42 \fBsd_bus_message_new_method_error()\fR
43 function creates a new bus message object that is an error reply to the
44 \fIcall\fR
45 message, and returns it in the
46 \fIm\fR
47 output parameter\&. The error information from error
48 \fIe\fR
49 is appended: the
50 \fIname\fR
51 field of
52 \fIe\fR
53 is used as the error identifier in the reply header (for example an error name such as
54 "org\&.freedesktop\&.DBus\&.Error\&.NotSupported"
55 or the equivalent symbolic
56 \fBSD_BUS_ERROR_NOT_SUPPORTED\fR), and the
57 \fImessage\fR
58 field is set as the human\-readable error message string if present\&. The error
59 \fIe\fR
60 must have the
61 \fIname\fR
62 field set, see
63 \fBsd_bus_error_is_set\fR(3)\&.
64 .PP
65 The
66 \fBsd_bus_message_new_method_errorf()\fR
67 function creates an error reply similarly to
68 \fBsd_bus_message_new_method_error()\fR, but instead of a ready error structure, it takes an error identifier string
69 \fIname\fR, plus a
70 \fBprintf\fR(3)
71 format string
72 \fIformat\fR
73 and corresponding arguments\&. An error reply is sent with the error identifier
74 \fIname\fR
75 and the formatted string as the message\&.
76 \fIname\fR
77 and
78 \fIformat\fR
79 must not be
80 \fBNULL\fR\&.
81 .PP
82 The
83 \fBsd_bus_message_new_method_errno()\fR
84 function creates an error reply similarly to
85 \fBsd_bus_message_new_method_error()\fR, but in addition to the error structure
86 \fIp\fR, it takes an
87 \fBerrno\fR(3)
88 error value in parameter
89 \fIerror\fR\&. If the error
90 \fIp\fR
91 is set (see
92 \fBsd_bus_error_is_set\fR(3)), it is used in the reply\&. Otherwise,
93 \fIerror\fR
94 is translated to an error identifier and used to create a new error structure using
95 \fBsd_bus_error_set_errno\fR(3)
96 and that is used in the reply\&. (If
97 \fIerror\fR
98 is zero, no error is actually set, and an error reply with no information is created\&.)
99 .PP
100 The
101 \fBsd_bus_message_new_method_errnof()\fR
102 function creates an error reply similarly to
103 \fBsd_bus_message_new_method_error()\fR\&. It takes an
104 \fBerrno\fR(3)
105 error value in parameter
106 \fIerror\fR, plus a
107 \fBprintf\fR(3)
108 format string
109 \fIformat\fR
110 and corresponding arguments\&.
111 "%m"
112 may be used in the format string to refer to the error string corresponding to the specified errno code\&. The error message is initialized using the error identifier generated from
113 \fBerror\fR
114 and the formatted string\&. (If
115 \fIerror\fR
116 is zero, no error is actually set, and an error reply with no information is created\&.)
117 .SH "RETURN VALUE"
118 .PP
119 These functions return 0 if the error reply was successfully created, and a negative errno\-style error code otherwise\&.
120 .SS "Errors"
121 .PP
122 Returned errors may indicate the following problems:
123 .PP
124 \fB\-EINVAL\fR
125 .RS 4
126 The call message
127 \fIcall\fR
128 or the output parameter
129 \fIm\fR
130 are
131 \fBNULL\fR\&.
132 .sp
133 Message
134 \fIcall\fR
135 is not a method call message\&.
136 .sp
137 The error
138 \fIe\fR
139 parameter to
140 \fBsd_bus_message_new_method_error()\fR
141 is not set, see
142 \fBsd_bus_error_is_set\fR(3)\&.
143 .RE
144 .PP
145 \fB\-EPERM\fR
146 .RS 4
147 Message
148 \fIcall\fR
149 has been sealed\&.
150 .RE
151 .PP
152 \fB\-ENOTCONN\fR
153 .RS 4
154 The bus to which message
155 \fIcall\fR
156 is attached is not connected\&.
157 .RE
158 .PP
159 \fB\-ENOMEM\fR
160 .RS 4
161 Memory allocation failed\&.
162 .RE
163 .SH "NOTES"
164 .PP
165 Functions described here are available as a shared library, which can be compiled against and linked to with the
166 \fBlibsystemd\fR\ \&\fBpkg-config\fR(1)
167 file\&.
168 .PP
169 The code described here uses
170 \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
171 \fBsetenv\fR(3)
172 from a parallel thread\&. It is recommended to only do calls to
173 \fBsetenv()\fR
174 from an early phase of the program when no other threads have been started\&.
175 .SH "SEE ALSO"
176 .PP
177 \fBsystemd\fR(1), \fBsd-bus\fR(3)