1explain_output(3) Library Functions Manual explain_output(3)
2
6 explain_output - output error messages
7
9 #include <libexplain/output.h>
10
12 These functions may be used to write error messages.
13 explain_output_message
15 void explain_output_message(const char *text);
16 The explain_output_message function is used to print text. It is
18 printed via the registered output class, see explain_output_register(3)
19 for how.
20 text The text of the message to be printed. It has not been wrapped
22 (yet).
23 explain_output_error
25 void explain_output_error(const char *fmt, ...);
26 The explain_output_error function is used to print a formatted error
28 message. The printing is done via the explain_output_message(3) func‐
29 tion.
30 fmt The format text of the message to be printed. See printf(3)
32 for more information.
33 explain_output_error_and_die
35 void explain_output_error_and_die(const char *fmt, ...);
36 The explain_output_error_and_die function is used to print text, and
38 then terminate immediately. The printing is done via the explain_out‐
39 put_message(3) function, process termination is via the explain_out‐
40 put_exit_failure(3) function.
41 fmt The format text of the message to be printed. See printf(3)
43 for more information.
44 explain_output_warning
46 void explain_output_warning(const char *fmt, ...);
47 The explain_output_warning function is used to print a formatted error
49 message, including the word “warning”. The printing is done via the
50 explain_output_message(3) function.
51 fmt The format text of the message to be printed. See printf(3)
53 for more information.
54 explain_output_exit
56 void explain_output_exit(int status);
57 The explain_output_exit function is used to terminate execution. It is
59 executed via the registered output class, explain_output_register(3)
60 for how.
61 status The exist status requested.
63 explain_output_exit_failure
65 void explain_output_exit_failure(void);
66 The explain_output_exit_failure function is used to terminate execu‐
68 tion, with exit status EXIT_FAILURE. It is executed via the registered
69 output class, see explain_output_register(3) for how.
70 explain_option_hanging_indent_set
72 void explain_option_hanging_indent_set(int columns);
73 The explain_option_hanging_indent_set function is used to cause the
75 output wrapping to use hanging indents. By default no hanging indent
76 is used, but this can sometimes obfuscate the end of one error message
77 and the beginning of another. A hanging indent results in continuation
78 lines starting with white space, similar to RFC822 headers.
79 This can be set using the “hanging‐indent=n” string in the
81 EXPLAIN_OPTIONS environment variable. See explain(3) for more informa‐
82 tion.
83 Using this function will override any environment variable setting.
85 columns The number of columns of hanging indent to be used. A value of
87 0 means no hanging indent (all lines flush with left margin).
88 A common value to use is 4: it doesn't consume too much of each
89 line, and it is a clear indent.
90
92 It is possible to change how and where libexplain sends its output, and
93 even how it calls the exit(2) function. This functionality is used by
94 the explain_*_or_die and explain_*_on_error functions.
95 By default, libexplain will wrap and print error messages on stderr,
97 and call the exit(2) system call to terminate execution.
98 Clients of the libexplain library may choose to use some message han‐
100 dling facilities provided by libexplain, or they may choose to imple‐
101 ment their own.
102 syslog
104 To cause all output to be sent to syslog, use
105 explain_output_register(explain_output_syslog_new());
107 This is useful for servers and daemons.
109 stderr and syslog
111 The “tee” output class can be used to duplicate output. To
112 cause all output to be sent to both stderr and syslog, use
113 explain_output_register
115 (
116 explain_output_tee_new
117 (
118 explain_output_stderr_new(),
119 explain_output_syslog_new()
120 )
121 );
122 If you need more than two, use several instances of “tee”, cas‐
124 caded.
125 stderr and a file
127 To cause all output to be sent to both stderr and a regular
128 file, use
129 explain_output_register
131 (
132 explain_output_tee_new
133 (
134 explain_output_stderr_new(),
135 explain_output_file_new(filename, 0)
136 )
137 );
138 See the <libexplain/output.h> file for extensive documentation.
140 explain_output_new
142 explain_output_t *explain_output_new(const explain_output_vtable_t
143 *vtable);
144 The explain_output_new function may be used to create a new dynamically
146 allocated instance of explain_output_t.
147 vtable The struct containing the pointers to the methods of the
149 derived class.
150 returns NULL on error (i.e. malloc failed), or a pointer to a new
152 dynamically allocated instance of the class.
153 explain_output_stderr_new
155 explain_output_t *explain_output_stderr_new(void);
156 The explain_output_stderr_new function may be used to create a new
158 dynamically allocated instance of an explain_output_t class that writes
159 to stderr, and exits via exit(2);
160 This is the default output handler.
162 returns NULL on error (i.e. malloc failed), or a pointer to a new
164 dynamically allocated instance of the stderr class.
165 explain_output_syslog_new
167 explain_output_t *explain_output_syslog_new(void);
168 The explain_output_syslog_new function may be used to create a new
170 dynamically allocated instance of an explain_output_t class that writes
171 to syslog, and exits via exit(2);
172 The following values are used:
174 option = 0
176 facility = LOG_USER
177 level = LOG_ERR
178 See syslog(3) for more information.
180 returns NULL on error (i.e. malloc(3) failed), or a pointer to a new
182 dynamically allocated instance of the syslog class.
183 explain_output_syslog_new1
185 explain_output_t *explain_output_syslog_new1(int level);
186 The explain_output_syslog_new1 function may be used to create a new
188 dynamically allocated instance of an explain_output_t class that writes
189 to syslog, and exits via exit(2);
190 The following values are used:
192 option = 0
194 facility = LOG_USER
195 See syslog(3) for more information.
197 level The syslog level to be used, see syslog(3) for a definition.
199 returns NULL on error (i.e. malloc(3) failed), or a pointer to a new
201 dynamically allocated instance of the syslog class.
202 explain_output_syslog_new3
204 explain_output_t *explain_output_syslog_new3(int option, int facility,
205 int level);
206 The explain_output_syslog_new3 function may be used to create a new
208 dynamically allocated instance of an explain_output_t class that writes
209 to syslog, and exits via exit(2);
210 If you want different facilities or levels, create multiple instances.
212 option The syslog option to be used, see syslog(3) for a definition.
214 facility
216 The syslog facility to be used, see syslog(3) for a definition.
217 level The syslog level to be used, see syslog(3) for a definition.
219 returns NULL on error (i.e. malloc(3) failed), or a pointer to a new
221 dynamically allocated instance of the syslog class.
222 explain_output_file_new
224 explain_output_t *explain_output_file_new(const char *filename, int
225 append);
226 The explain_output_file_new function may be used to create a new dynam‐
228 ically allocated instance of an explain_output_t class that writes to a
229 file, and exits via exit(2).
230 filename
232 The file to be opened and written to.
233 append true (non‐zero) if messages are to be appended to the file,
235 false (zero) if the file is to be replaced with new contents.
236 returns NULL on error (i.e. malloc(3) or open(2) failed), or a pointer
238 to a new dynamically allocated instance of the syslog class.
239 explain_output_tee_new
241 explain_output_t *explain_output_tee_new(explain_output_t *first,
242 explain_output_t *second);
243 The explain_output_tee_new function may be used to create a new dynami‐
245 cally allocated instance of an explain_output_t class that writes to
246 two other output classes.
247 first The first output class to write to.
249 second The second output class to write to.
251 returns NULL on error (i.e. malloc(3) failed), or a pointer to a new
253 dynamically allocated instance of the syslog class.
254 The output subsystem will “own” the first and second objects after this
256 call. You may not make any reference to these pointers ever again.
257 The output subsystem will destroy these objects and free the memory
258 when it feels like it.
259 explain_output_register
261 void explain_output_register(explain_output_t *op);
262 The explain_output_register function is used to change libexplain's
264 default output handling facilities with something else. The NULL
265 pointer restores libexplain's default processing.
266 If no output class is registered, the default is to wrap and print to
268 stderr, and to exit via the exit(2) system call.
269 op Pointer to the explain_output_t instance to be operated on.
271 The output subsystem will “own” the pointer after this call. You may
273 not make any reference to this pointer ever again. The output subsys‐
274 tem will destroy the object and free the memory when it feels like it.
275
277 libexplain version 1.4
278 Copyright (C) 2010 Peter Miller
279
281 Written by Peter Miller <pmiller@opensource.org.au>
282 explain_output(3)