libreport  2.9.5
A tool to inform users about various problems on the running system
problem_report.h
1 /*
2  Copyright (C) 2014 ABRT team
3  Copyright (C) 2014 RedHat Inc
4 
5  This program is free software; you can redistribute it and/or modify
6  it under the terms of the GNU General Public License as published by
7  the Free Software Foundation; either version 2 of the License, or
8  (at your option) any later version.
9 
10  This program is distributed in the hope that it will be useful,
11  but WITHOUT ANY WARRANTY; without even the implied warranty of
12  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
13  GNU General Public License for more details.
14 
15  You should have received a copy of the GNU General Public License along
16  with this program; if not, write to the Free Software Foundation, Inc.,
17  51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
18 
19  @brief API for formating of problem data
20 
21  These functions can be used to convert a problem data to its string
22  representation.
23 
24  The output format can be parsed from a string:
25 
26  problem_formatter_t *formatter = problem_formatter_new();
27  problem_formatter_load_string(formatter, MY_FORMAT_STRING);
28 
29  or loaded from a file:
30 
31  problem_formatter_t *formatter = problem_formatter_new();
32  problem_formatter_load_file(formatter, MY_FORMAT_FILE);
33 
34  Once you have configured your formatter you can convert problem_data to
35  problem_report by calling:
36 
37  problem_report_t *report;
38  if (problem_formatter_generate_report(formatter, data, &report) != 0)
39  errx(EXIT_FAILURE, "Problem data cannot be converted to problem report.");
40 
41  Now you can print the report:
42 
43  printf("Problem: %s\n", problem_report_get_summary());
44  printf("%s\n", problem_report_get_description());
45 
46  puts("Problem attachments:");
47  for (GList *a = problem_report_get_attachments(pr); a != NULL; a = g_list_next(a))
48  printf(" %s\n", a->data);
49 
50  Format description:
51 
52  ----
53  %summary:: summary format
54  %attach:: elemnt1[,element2]...
55  section:: element1[,element2]...
56  The literal text line to be added to report.
57  ----
58 
59  Summary format is a line of text, where %element% is replaced by
60  text element's content, and [[...%element%...]] block is used only if
61  %element% exists. [[...]] blocks can nest.
62 
63  Sections can be:
64  - %summary: bug summary format string.
65 
66  - %attach: a list of elements to attach.
67 
68  - text, double colon (::) and the list of comma-separated elements.
69  Text can be empty (":: elem1, elem2, elem3" works),
70  in this case "Text:" header line will be omitted.
71 
72  - %description: this section is implicit and contains all text
73  sections unless another section was specified (%summary and %attach
74  are ignored when determining text section's placement)
75 
76  - every text element belongs to the last specified section (%summary
77  and %attach sections are ignored). If no section was specified,
78  the text element belogns to %description.
79 
80  - If none of elements exists, the section will not be created.
81 
82  - Empty lines are NOT ignored.
83 
84  Elements can be:
85  - problem directory element names, which get formatted as
86  <element_name>: <contents>
87  or
88  <element_name>:
89  :<contents>
90  :<contents>
91  :<contents>
92 
93  - problem directory element names prefixed by "%bare_",
94  which is formatted as-is, without "<element_name>:" and colons
95 
96  - %oneline, %multiline, %text wildcards, which select all corresponding
97  elements for output or attachment
98 
99  - %binary wildcard, valid only for %attach section, instructs to attach
100  binary elements
101 
102  - %short_backtrace is a reserved element that is replaced with contents
103  of backtrace file truncated to optimal number of frames
104 
105  - %reporter is a reserved element that is replaced by name and version
106  of the software that created the report
107 
108  - problem directory element names prefixed by "-",
109  which excludes given element from all wildcards
110 
111  - Nonexistent elements are silently ignored.
112 
113  You can add your own section:
114 
115  problem_formatter_t *formatter = problem_formatter_new();
116  problem_formatter_add_section(formatter, "additional_info", PFFF_REQUIRED);
117 
118  and then you can use the section in the formatting string:
119 
120  problem_formatter_load_string(formatter,
121  "::comment\n"
122  "%additional_info:: maps");
123  problem_formatter_generate_report(formatter, data, &report);
124 
125  printf("Problem: %s\n", problem_report_get_summary());
126  printf("%s\n", problem_report_get_description());
127  printf("Additional info: %s\n", problem_report_get_section(report, "additiona_info"));
128 
129  The lines above are equivalent to the following lines:
130 
131  printf("Problem: %s\n", problem_data_get_content_or_NULL(data, "reason"));
132  printf("%s\n", problem_data_get_content_or_NULL(data, "comment"));
133  printf("Additional info: %s\n", problem_data_get_content_or_NULL(data, "maps"));
134 */
135 #ifndef LIBREPORT_PROBLEM_REPORT_H
136 #define LIBREPORT_PROBLEM_REPORT_H
137 
138 #include <glib.h>
139 #include <stdio.h>
140 #include "problem_data.h"
141 
142 #ifdef __cplusplus
143 extern "C" {
144 #endif
145 
146 #define PR_SEC_SUMMARY "summary"
147 #define PR_SEC_DESCRIPTION "description"
148 
149 /*
150  * The problem report structure represents a problem data formatted according
151  * to a format string.
152  *
153  * A problem report is composed of well-known sections:
154  * - summary
155  * - descritpion
156  * - attach
157  *
158  * and custom sections accessed by:
159  * problem_report_get_section();
160  */
161 struct problem_report;
162 typedef struct problem_report problem_report_t;
163 
164 /*
165  * The problem report settings structure contains advance settings
166  * for report generating
167  */
169 {
172 };
173 
175 
176 /*
177  * Helpers for easily switching between FILE and struct strbuf
178  */
179 
180 /*
181  * Type of buffer used by Problem report
182  */
183 typedef FILE problem_report_buffer;
184 
185 /*
186  * Wrapper for the proble buffer's formated output function.
187  */
188 #define problem_report_buffer_printf(buf, fmt, ...)\
189  fprintf((buf), (fmt), ##__VA_ARGS__)
190 
191 
192 /*
193  * Get a section buffer
194  *
195  * Use this function if you need to amend something to a formatted section.
196  *
197  * @param self Problem report
198  * @param section_name Name of required section
199  * @return Always valid pointer to a section buffer
200  */
201 problem_report_buffer *problem_report_get_buffer(const problem_report_t *self,
202  const char *section_name);
203 
204 /*
205  * Get Summary string
206  *
207  * The returned pointer is valid as long as you perform no further output to
208  * the summary buffer.
209  *
210  * @param self Problem report
211  * @return Non-NULL pointer to summary data
212  */
213 const char *problem_report_get_summary(const problem_report_t *self);
214 
215 /*
216  * Get Description string
217  *
218  * The returned pointer is valid as long as you perform no further output to
219  * the description buffer.
220  *
221  * @param self Problem report
222  * @return Non-NULL pointer to description data
223  */
224 const char *problem_report_get_description(const problem_report_t *self);
225 
226 /*
227  * Get Section's string
228  *
229  * The returned pointer is valid as long as you perform no further output to
230  * the section's buffer.
231  *
232  * @param self Problem report
233  * @param section_name Name of the required section
234  * @return Non-NULL pointer to description data
235  */
236 const char *problem_report_get_section(const problem_report_t *self,
237  const char *section_name);
238 
239 /*
240  * Get GList of the problem data items that are to be attached
241  *
242  * @param self Problem report
243  * @return A pointer to GList (NULL means empty list)
244  */
245 GList *problem_report_get_attachments(const problem_report_t *self);
246 
247 /*
248  * Releases all resources allocated by a problem report
249  *
250  * @param self Problem report
251  */
252 void problem_report_free(problem_report_t *self);
253 
254 
255 /*
256  * An enum of Extra section flags
257  */
258 enum problem_formatter_section_flags {
259  PFFF_REQUIRED = 1 << 0,
260 };
261 
262 /*
263  * The problem formatter structure formats a problem data according to a format
264  * string and stores result a problem report.
265  *
266  * The problem formatter uses '%reason%' as %summary section format string, if
267  * %summary is not provided by a format string.
268  */
269 struct problem_formatter;
270 typedef struct problem_formatter problem_formatter_t;
271 
272 /*
273  * Constructs a new problem formatter.
274  *
275  * @return Non-NULL pointer to the new problem formatter
276  */
277 problem_formatter_t *problem_formatter_new(void);
278 
279 /*
280  * Releases all resources allocated by a problem formatter
281  *
282  * @param self Problem formatter
283  */
284 void problem_formatter_free(problem_formatter_t *self);
285 
286 /*
287  * Adds a new recognized section
288  *
289  * The problem formatter ignores a section in the format spec if the section is
290  * not one of the default nor added by this function.
291  *
292  * How the problem formatter handles these extra sections:
293  *
294  * A custom section is something like %description section. %description is the
295  * default section where all text (sub)sections are stored. If the formatter
296  * finds the custom section in format string, then starts storing text
297  * (sub)sections in the custom section.
298  *
299  * (%description) |:: comment
300  * (%description) |
301  * (%description) |Package:: package
302  * (%description) |
303  * (%additiona_info) |%additional_info::
304  * (%additiona_info) |%reporter%
305  * (%additiona_info) |User:: user_name,uid
306  * (%additiona_info) |
307  * (%additiona_info) |Directories:: root,cwd
308  *
309  *
310  * @param self Problem formatter
311  * @param name Name of the added section
312  * @param flags Info about the added section
313  * @return Zero on success. -EEXIST if the name is already known by the formatter
314  */
315 int problem_formatter_add_section(problem_formatter_t *self, const char *name, int flags);
316 
317 /*
318  * Loads a problem format from a string.
319  *
320  * @param self Problem formatter
321  * @param fmt Format
322  * @return Zero on success or number of warnings (e.g. missing section,
323  * unrecognized section).
324  */
325 int problem_formatter_load_string(problem_formatter_t* self, const char *fmt);
326 
327 /*
328  * Loads a problem format from a file.
329  *
330  * @param self Problem formatter
331  * @param pat Path to the format file
332  * @return Zero on success or number of warnings (e.g. missing section,
333  * unrecognized section).
334  */
335 int problem_formatter_load_file(problem_formatter_t* self, const char *path);
336 
337 /*
338  * Creates a new problem report, formats the data according to the loaded
339  * format string and stores output in the report.
340  *
341  * @param self Problem formatter
342  * @param data Problem data to format
343  * @param report Pointer where the created problem report is to be stored
344  * @return Zero on success, otherwise non-zero value.
345  */
346 int problem_formatter_generate_report(const problem_formatter_t *self, problem_data_t *data, problem_report_t **report);
347 
348 /*
349  * Returns problem report settings from given formatter
350  *
351  * @param self Problem formatter
352  * @return problem report settings
353  */
354 problem_report_settings_t problem_formatter_get_settings(const problem_formatter_t *self);
355 
356 /*
357  * Sets problem report settings to given formatter
358  *
359  * @param self Problem formatter
360  * @param settings Problem report settings
361  */
362 void problem_formatter_set_settings(problem_formatter_t *self, problem_report_settings_t settings);
363 
364 #ifdef __cplusplus
365 }
366 #endif
367 
368 #endif // LIBREPORT_PROBLEM_REPORT_H
int prs_shortbt_max_frames
generate only max top frames in short_backtrace
size_t prs_shortbt_max_text_size
short bt only if it is bigger then this