diff options
Diffstat (limited to 'src/btparser/backtrace.h')
| -rw-r--r-- | src/btparser/backtrace.h | 269 |
1 files changed, 0 insertions, 269 deletions
diff --git a/src/btparser/backtrace.h b/src/btparser/backtrace.h deleted file mode 100644 index d5de3ff3..00000000 --- a/src/btparser/backtrace.h +++ /dev/null @@ -1,269 +0,0 @@ -/* - backtrace.h - - Copyright (C) 2010 Red Hat, Inc. - - This program is free software; you can redistribute it and/or modify - it under the terms of the GNU General Public License as published by - the Free Software Foundation; either version 2 of the License, or - (at your option) any later version. - - This program is distributed in the hope that it will be useful, - but WITHOUT ANY WARRANTY; without even the implied warranty of - MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the - GNU General Public License for more details. - - You should have received a copy of the GNU General Public License along - with this program; if not, write to the Free Software Foundation, Inc., - 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA. -*/ -#ifndef BTPARSER_BACKTRACE_H -#define BTPARSER_BACKTRACE_H - -#include <stdbool.h> - -#ifdef __cplusplus -extern "C" { -#endif - -struct btp_thread; -struct btp_frame; -struct btp_location; - -/** - * A backtrace obtained at the time of a program crash, consisting of - * several threads which contains frames. - */ -struct btp_backtrace -{ - struct btp_thread *threads; - /** - * The frame where the crash happened according to debugger. It - * might be that we can not tell to which thread this frame - * belongs, because some threads end with mutually - * indistinguishable frames. - */ - struct btp_frame *crash; -}; - -/** - * Creates and initializes a new backtrace structure. - * @returns - * It never returns NULL. The returned pointer must be released by - * calling the function btp_backtrace_free(). - */ -struct btp_backtrace * -btp_backtrace_new(); - -/** - * Initializes all members of the backtrace structure to their default - * values. No memory is released, members are simply overwritten. - * This is useful for initializing a backtrace structure placed on the - * stack. - */ -void -btp_backtrace_init(struct btp_backtrace *backtrace); - -/** - * Releases the memory held by the backtrace, its threads and frames. - * @param backtrace - * If the backtrace is NULL, no operation is performed. - */ -void -btp_backtrace_free(struct btp_backtrace *backtrace); - -/** - * Creates a duplicate of the backtrace. - * @param backtrace - * The backtrace to be copied. It's not modified by this function. - * @returns - * This function never returns NULL. If the returned duplicate is not - * shallow, it must be released by calling the function - * btp_backtrace_free(). - */ -struct btp_backtrace * -btp_backtrace_dup(struct btp_backtrace *backtrace); - -/** - * Returns a number of threads in the backtrace. - * @param backtrace - * It's not modified by calling this function. - */ -int -btp_backtrace_get_thread_count(struct btp_backtrace *backtrace); - -/** - * Removes all threads from the backtrace and deletes them, except the - * one provided as a parameter. - * @param thread - * This function does not check whether the thread is a member of the backtrace. - * If it's not, all threads are removed from the backtrace and then deleted. - */ -void -btp_backtrace_remove_threads_except_one(struct btp_backtrace *backtrace, - struct btp_thread *thread); - -/** - * Search all threads and tries to find the one that caused the crash. - * It might return NULL if the thread cannot be determined. - * @param backtrace - * It must be non-NULL pointer. It's not modified by calling this - * function. - */ -struct btp_thread * -btp_backtrace_find_crash_thread(struct btp_backtrace *backtrace); - -/** - * Remove frames from the bottom of threads in the backtrace, until - * all threads have at most 'depth' frames. - * @param backtrace - * Must be non-NULL pointer. - */ -void -btp_backtrace_limit_frame_depth(struct btp_backtrace *backtrace, - int depth); - -/** - * Evaluates the quality of the backtrace. The quality is the ratio of - * the number of frames with function name fully known to the number - * of all frames. This function does not take into account that some - * frames are more important than others. - * @param backtrace - * It must be non-NULL pointer. It's not modified by calling this - * function. - * @returns - * A number between 0 and 1. 0 means the lowest quality, 1 means full - * backtrace is known. - */ -float -btp_backtrace_quality_simple(struct btp_backtrace *backtrace); - -/** - * Evaluates the quality of the backtrace. The quality is determined - * depending on the ratio of frames with function name fully known to - * all frames. - * @param backtrace - * It must be non-NULL pointer. It's not modified by calling this - * function. - * @returns - * A number between 0 and 1. 0 means the lowest quality, 1 means full - * backtrace is known. The returned value takes into account that the - * thread which caused the crash is more important than the other - * threads, and the frames around the crash frame are more important - * than distant frames. - */ -float -btp_backtrace_quality_complex(struct btp_backtrace *backtrace); - -/** - * Returns textual representation of the backtrace. - * @param backtrace - * It must be non-NULL pointer. It's not modified by calling this - * function. - * @returns - * This function never returns NULL. The caller is responsible for - * releasing the returned memory using function free(). - */ -char * -btp_backtrace_to_text(struct btp_backtrace *backtrace, - bool verbose); - -/** - * Analyzes the backtrace to get the frame where a crash occurred. - * @param backtrace - * It must be non-NULL pointer. It's not modified by calling this - * function. - * @returns - * The returned value must be released by calling btp_frame_free(), - * when it's no longer needed. NULL is returned if the crash frame is - * not found. - */ -struct btp_frame * -btp_backtrace_get_crash_frame(struct btp_backtrace *backtrace); - -/** - * Calculates the duplication hash string of the backtrace. - * @param backtrace - * It must be non-NULL pointer. It's not modified by calling this - * function. - * @returns - * This function never returns NULL. The caller is responsible for - * releasing the returned memory using function free(). - */ -char * -btp_backtrace_get_duplication_hash(struct btp_backtrace *backtrace); - -/** - * Parses a textual backtrace and puts it into a structure. If - * parsing fails, the input parameter is not changed and NULL is - * returned. - * @code - * struct btp_location location; - * btp_location_init(&location); - * char *input = "..."; - * struct btp_backtrace *backtrace = btp_backtrace_parse(input, location; - * if (!backtrace) - * { - * fprintf(stderr, - * "Failed to parse the backtrace.\n" - * "Line %d, column %d: %s\n", - * location.line, - * location.column, - * location.message); - * exit(-1); - * } - * btp_backtrace_free(backtrace); - * @endcode - * @param input - * Pointer to the string with the backtrace. If this function returns - * true, this pointer is modified to point after the backtrace that - * was just parsed. - * @param location - * The caller must provide a pointer to an instance of btp_location - * here. The line and column members of the location are gradually - * increased as the parser handles the input, so the location should - * be initialized before calling this function to get reasonable - * values. When this function returns false (an error occurred), the - * structure will contain the error line, column, and message. - * @returns - * A newly allocated backtrace structure or NULL. A backtrace struct - * is returned when at least one thread was parsed from the input and - * no error occurred. The returned structure should be released by - * btp_backtrace_free(). - */ -struct btp_backtrace * -btp_backtrace_parse(char **input, - struct btp_location *location); - -/** - * Parse backtrace header if it is available in the backtrace. The - * header usually contains frame where the program crashed. - * @param input - * Pointer moved to point behind the header if the header is - * successfully detected and parsed. - * @param frame - * If this function succeeds and returns true, *frame contains the - * crash frame that is usually a part of the header. If no frame is - * detected in the header, *frame is set to NULL. - * @code - * [New Thread 11919] - * [New Thread 11917] - * Core was generated by `evince file:///tmp/Factura04-05-2010.pdf'. - * Program terminated with signal 8, Arithmetic exception. - * #0 0x000000322a2362b9 in repeat (image=<value optimized out>, - * mask=<value optimized out>, mask_bits=<value optimized out>) - * at pixman-bits-image.c:145 - * 145 pixman-bits-image.c: No such file or directory. - * in pixman-bits-image.c - * @endcode - */ -bool -btp_backtrace_parse_header(char **input, - struct btp_frame **frame, - struct btp_location *location); - -#ifdef __cplusplus -} -#endif - -#endif |