stacktrace.h File Reference

Stack trace as produced by GDB. More...

#include "../report_type.h"
#include <stdbool.h>
#include <stdint.h>

Go to the source code of this file.

Data Structures
struct	sr_gdb_stacktrace
	A stack trace produced by GDB. More...

Functions
struct sr_gdb_stacktrace *	sr_gdb_stacktrace_new (void)
void	sr_gdb_stacktrace_init (struct sr_gdb_stacktrace *stacktrace)
void	sr_gdb_stacktrace_free (struct sr_gdb_stacktrace *stacktrace)
struct sr_gdb_stacktrace *	sr_gdb_stacktrace_dup (struct sr_gdb_stacktrace *stacktrace)
int	sr_gdb_stacktrace_get_thread_count (struct sr_gdb_stacktrace *stacktrace)
void	sr_gdb_stacktrace_remove_threads_except_one (struct sr_gdb_stacktrace *stacktrace, struct sr_gdb_thread *thread)
struct sr_gdb_thread *	sr_gdb_stacktrace_find_crash_thread (struct sr_gdb_stacktrace *stacktrace)
void	sr_gdb_stacktrace_limit_frame_depth (struct sr_gdb_stacktrace *stacktrace, int depth)
float	sr_gdb_stacktrace_quality_simple (struct sr_gdb_stacktrace *stacktrace)
float	sr_gdb_stacktrace_quality_complex (struct sr_gdb_stacktrace *stacktrace)
char *	sr_gdb_stacktrace_to_text (struct sr_gdb_stacktrace *stacktrace, bool verbose)
struct sr_gdb_frame *	sr_gdb_stacktrace_get_crash_frame (struct sr_gdb_stacktrace *stacktrace)
void	sr_gdb_stacktrace_set_crash_tid (struct sr_gdb_stacktrace *stacktrace, uint32_t tid)
struct sr_gdb_stacktrace *	sr_gdb_stacktrace_parse (const char **input, struct sr_location *location)
bool	sr_gdb_stacktrace_parse_header (const char **input, struct sr_gdb_frame **frame, struct sr_location *location)
void	sr_gdb_stacktrace_set_libnames (struct sr_gdb_stacktrace *stacktrace)
char *	sr_gdb_stacktrace_to_short_text (struct sr_gdb_stacktrace *stacktrace, int max_frames)

Detailed Description

Stack trace as produced by GDB.

Definition in file gdb/stacktrace.h.

Function Documentation

sr_gdb_stacktrace_dup()

struct sr_gdb_stacktrace * sr_gdb_stacktrace_dup

(

struct sr_gdb_stacktrace *

stacktrace

)

Creates a duplicate of a stacktrace.

Parameters

stacktrace

The stacktrace to be copied. It's not modified by this function.

Returns

This function never returns NULL. The returned duplicate must be released by calling the function sr_gdb_stacktrace_free().

sr_gdb_stacktrace_find_crash_thread()

struct sr_gdb_thread * sr_gdb_stacktrace_find_crash_thread

(

struct sr_gdb_stacktrace *

stacktrace

)

Searches all threads and tries to find the one that caused the crash. It might return NULL if the thread cannot be determined.

Parameters

stacktrace

It must be non-NULL pointer. It's not modified by calling this function.

sr_gdb_stacktrace_free()

void sr_gdb_stacktrace_free

(

struct sr_gdb_stacktrace *

stacktrace

)

Releases the memory held by the stacktrace, its threads, frames, shared libraries.

Parameters

stacktrace

If the stacktrace is NULL, no operation is performed.

sr_gdb_stacktrace_get_crash_frame()

struct sr_gdb_frame * sr_gdb_stacktrace_get_crash_frame

(

struct sr_gdb_stacktrace *

stacktrace

)

Analyzes the stacktrace to get the frame where a crash occurred.

Parameters

stacktrace

It must be non-NULL pointer. It's not modified by calling this function.

Returns

The returned value must be released by calling sr_gdb_frame_free() when it's no longer needed, because it is a deep copy of the crash frame from the stacktrace. NULL is returned if the crash frame is not found.

sr_gdb_stacktrace_get_thread_count()

int sr_gdb_stacktrace_get_thread_count

(

struct sr_gdb_stacktrace *

stacktrace

)

Returns a number of threads in the stacktrace.

Parameters

stacktrace

It's not modified by calling this function.

sr_gdb_stacktrace_init()

void sr_gdb_stacktrace_init

(

struct sr_gdb_stacktrace *

stacktrace

)

Initializes all members of the stacktrace structure to their default values. No memory is released, members are simply overwritten. This is useful for initializing a stacktrace structure placed on the stack.

sr_gdb_stacktrace_limit_frame_depth()

void sr_gdb_stacktrace_limit_frame_depth	(	struct sr_gdb_stacktrace *	stacktrace,
		int	depth )

Remove frames from the bottom of threads in the stacktrace, until all threads have at most 'depth' frames.

Parameters

stacktrace

Must be non-NULL pointer.

sr_gdb_stacktrace_new()

struct sr_gdb_stacktrace * sr_gdb_stacktrace_new

(

void

)

Creates and initializes a new stack trace structure.

Returns

It never returns NULL. The returned pointer must be released by calling the function sr_gdb_stacktrace_free().

sr_gdb_stacktrace_parse()

struct sr_gdb_stacktrace * sr_gdb_stacktrace_parse	(	const char **	input,
		struct sr_location *	location )

Parses a textual stack trace and puts it into a structure. If parsing fails, the input parameter is not changed and NULL is returned.

struct sr_location location;
sr_location_init(&location);
char *input = "...";
struct sr_gdb_stacktrace *stacktrace;
stacktrace = sr_gdb_stacktrace_parse(input, location);
if (!stacktrace)
{
  fprintf(stderr,
          "Failed to parse the stacktrace.\n"
          "Line %d, column %d: %s\n",
          location.line,
          location.column,
          location.message);
  exit(-1);
}
sr_gdb_stacktrace_free(stacktrace);

Parameters

input

Pointer to the string with the stacktrace. If this function returns a non-NULL value, this pointer is modified to point after the stacktrace that was just parsed.

location

The caller must provide a pointer to an instance of sr_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 by sr_location_init() 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 stacktrace structure or NULL. A stacktrace struct is returned when at least one thread was parsed from the input and no error occurred. The returned structure should be released by sr_gdb_stacktrace_free().

sr_gdb_stacktrace_parse_header()

bool sr_gdb_stacktrace_parse_header	(	const char **	input,
		struct sr_gdb_frame **	frame,
		struct sr_location *	location )

Parse stacktrace header if it is available in the stacktrace. The header usually contains frame where the program crashed.

Parameters

input

Pointer that will be moved to point behind the header if the header is successfully detected and parsed.

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. [New Thread 11919] [New Thread 11917] Core was generated by `evince file: 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

sr_gdb_stacktrace_quality_complex()

float sr_gdb_stacktrace_quality_complex

(

struct sr_gdb_stacktrace *

stacktrace

)

Evaluates the quality of the stacktrace. The quality is determined depending on the ratio of frames with function name fully known to all frames.

Parameters

stacktrace

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 stacktrace 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.

sr_gdb_stacktrace_quality_simple()

float sr_gdb_stacktrace_quality_simple

(

struct sr_gdb_stacktrace *

stacktrace

)

Evaluates the quality of the stacktrace. 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.

Parameters

stacktrace

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 stacktrace is known (all function names are known).

sr_gdb_stacktrace_remove_threads_except_one()

void sr_gdb_stacktrace_remove_threads_except_one	(	struct sr_gdb_stacktrace *	stacktrace,
		struct sr_gdb_thread *	thread )

Removes all threads from the stacktrace and deletes them, except the one provided as a parameter.

Parameters

thread

This function does not check whether the thread is a member of the stacktrace. If it's not, all threads are removed from the stacktrace and then deleted.

sr_gdb_stacktrace_set_crash_tid()

void sr_gdb_stacktrace_set_crash_tid	(	struct sr_gdb_stacktrace *	stacktrace,
		uint32_t	tid )

Sets the crash TID, which is used to search for the crash thread, to the given value.

Parameters

tid	Value of the 'i' parameter passed on command line by Kernel when piping a core dump file to a program.

sr_gdb_stacktrace_set_libnames()

void sr_gdb_stacktrace_set_libnames

(

struct sr_gdb_stacktrace *

stacktrace

)

Set library names in all frames in the stacktrace according to the the sharedlib data.

sr_gdb_stacktrace_to_short_text()

char * sr_gdb_stacktrace_to_short_text	(	struct sr_gdb_stacktrace *	stacktrace,
		int	max_frames )

Return short text representation of the crash thread. The trace is normalized and functions without names (signal handlers) are removed.

Parameters

stacktrace	It must be non-NULL pointer. It's not modified by calling this function.
max_frames	The maximum number of frames in the returned crash thread. Superfluous frames are not included in the output.

Returns

Brief text representation of the crash thread suitable for being part of a bugzilla comment. The string is allocated by the function and must be freed using the g_free() function.

sr_gdb_stacktrace_to_text()

char * sr_gdb_stacktrace_to_text	(	struct sr_gdb_stacktrace *	stacktrace,
		bool	verbose )

Returns textual representation of the stacktrace.

Parameters

stacktrace

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 g_free().