/* 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 #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=, * mask=, mask_bits=) * 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