mirror of
https://sourceware.org/git/glibc.git
synced 2024-11-23 17:53:37 +08:00
3ba06713f8
2002-08-04 Jakub Jelinek <jakub@redhat.com> * manual/debug.texi: Fix spelling to programmatically. Reported by <hayastan132@hotmail.com>. * include/libio.h: Add libc_hidden_proto for __uflow. * include/stdio.h: Map fopen, fdopen, fclose, fputs, fsetpos, and fgetpos to _IO_* names. Add libc_hidden_proto for fileno, fwrite, fseek, fflush_unlocked, fread_unlocked, fwrite_unlocked, fgets_unlocked, fputs_unlocked. * include/wchar.h: Add libc_hidden_proto for fputws_unlocked, putwc_unlocked, vswscanf. * libio/iolibio.h: Add libc_hidden_proto for _IO_fputs. * libio/fileno.c: Use <stdio.h> and libc_hidden_def. * libio/fseek.c: Likewise. * libio/fmemopen.c: Include "libioP.h". Call _IO_fopencookie and not fopencookie. * libio/genops.c (__uflow): Add libc_hidden_def. * libio/iofflush_u.c (fflush_unlocked): Likewise. * libio/iofgets_u.c (fgets_unlocked): Likewise. * libio/iofputs_u.c (fputs_unlocked): Likewise. * libio/iofputws_u.c (fputws_unlocked): Likewise. * libio/iofread_u.c (fread_unlocked): Likewise. * libio/iofwrite_u.c (fwrite_unlocked): Likewise. * libio/iovswscanf.c (vswscanf): Likewise. * libio/putwc_u.c (putwc_unlocked): Likewise. * libio/iofputs.c: Use libc_hidden_def instead of INTDEF. * malloc/malloc.c: Redirect fwrite calls to _IO_fwrite. * malloc/mtrace.c: Likewise. * sunrpc/clnt_perr.c: Remove fputs macro. * sunrpc/svc_simple.c: Likewise. * sunrpc/svc_tcp.c: Likewise. * sunrpc/svc_udp.c: Likewise. * sunrpc/xdr_rec.c: Likewise. * sunrpc/xdr_ref.c: Likewise. * iconv/Makefile: Add CPPFLAGS definitions with -DNOT_in_libc for iconv_prog, linereader, and charmap-dir. * locale/Makefile: Likewise for locale and charmap-dir. * malloc/Makefile: Likewise for memusagestat. * nscd/Makefile: Likewise for nscd, nscd_conf, and dbg_log. * sunrpc/Makefile: Likewise for rpc_main. * sysdeps/unix/sysv/linux/Makefile: Likewise for lddlibc4. * timezone/Makefile: Likewise for zic. * stdio-common/perror.c: Avoid multiple calls to fileno_unlocked.
111 lines
4.8 KiB
Plaintext
111 lines
4.8 KiB
Plaintext
@node Debugging Support
|
|
@c @node Debugging Support, , Cryptographic Functions, Top
|
|
@c %MENU% Functions to help debugging applications.
|
|
@chapter Debugging support
|
|
|
|
Applications are usually debugged using dedicated debugger programs.
|
|
But sometimes this is not possible and, in any case, it is useful to
|
|
provide the developer with as much information as possible at the time
|
|
the problems are experienced. For this reason a few functions are
|
|
provided which a program can use to help the developer more easily
|
|
locate the problem.
|
|
|
|
|
|
@menu
|
|
* Backtraces:: Obtaining and printing a back trace of the
|
|
current stack.
|
|
@end menu
|
|
|
|
|
|
@node Backtraces, , , Debugging Support
|
|
@section Backtraces
|
|
|
|
@cindex backtrace
|
|
@cindex backtrace_symbols
|
|
@cindex backtrace_fd
|
|
A @dfn{backtrace} is a list of the function calls that are currently
|
|
active in a thread. The usual way to inspect a backtrace of a program
|
|
is to use an external debugger such as gdb. However, sometimes it is
|
|
useful to obtain a backtrace programmatically from within a program,
|
|
e.g., for the purposes of logging or diagnostics.
|
|
|
|
The header file @file{execinfo.h} declares three functions that obtain
|
|
and manipulate backtraces of the current thread.
|
|
@pindex execinfo.h
|
|
|
|
@comment execinfo.h
|
|
@comment GNU
|
|
@deftypefun int backtrace (void **@var{buffer}, int @var{size})
|
|
The @code{backtrace} function obtains a backtrace for the current
|
|
thread, as a list of pointers, and places the information into
|
|
@var{buffer}. The argument @var{size} should be the number of
|
|
@w{@code{void *}} elements that will fit into @var{buffer}. The return
|
|
value is the actual number of entries of @var{buffer} that are obtained,
|
|
and is at most @var{size}.
|
|
|
|
The pointers placed in @var{buffer} are actually return addresses
|
|
obtained by inspecting the stack, one return address per stack frame.
|
|
|
|
Note that certain compiler optimizations may interfere with obtaining a
|
|
valid backtrace. Function inlining causes the inlined function to not
|
|
have a stack frame; tail call optimization replaces one stack frame with
|
|
another; frame pointer elimination will stop @code{backtrace} from
|
|
interpreting the stack contents correctly.
|
|
@end deftypefun
|
|
|
|
@comment execinfo.h
|
|
@comment GNU
|
|
@deftypefun {char **} backtrace_symbols (void *const *@var{buffer}, int @var{size})
|
|
The @code{backtrace_symbols} function translates the information
|
|
obtained from the @code{backtrace} function into an array of strings.
|
|
The argument @var{buffer} should be a pointer to an array of addresses
|
|
obtained via the @code{backtrace} function, and @var{size} is the number
|
|
of entries in that array (the return value of @code{backtrace}).
|
|
|
|
The return value is a pointer to an array of strings, which has
|
|
@var{size} entries just like the array @var{buffer}. Each string
|
|
contains a printable representation of the corresponding element of
|
|
@var{buffer}. It includes the function name (if this can be
|
|
determined), an offset into the function, and the actual return address
|
|
(in hexadecimal).
|
|
|
|
Currently, the function name and offset only be obtained on systems that
|
|
use the ELF binary format for programs and libraries. On other systems,
|
|
only the hexadecimal return address will be present. Also, you may need
|
|
to pass additional flags to the linker to make the function names
|
|
available to the program. (For example, on systems using GNU ld, you
|
|
must pass (@code{-rdynamic}.)
|
|
|
|
The return value of @code{backtrace_symbols} is a pointer obtained via
|
|
the @code{malloc} function, and it is the responsibility of the caller
|
|
to @code{free} that pointer. Note that only the return value need be
|
|
freed, not the individual strings.
|
|
|
|
The return value is @code{NULL} if sufficient memory for the strings
|
|
cannot be obtained.
|
|
@end deftypefun
|
|
|
|
@comment execinfo.h
|
|
@comment GNU
|
|
@deftypefun void backtrace_symbols_fd (void *const *@var{buffer}, int @var{size}, int @var{fd})
|
|
The @code{backtrace_symbols_fd} function performs the same translation
|
|
as the function @code{backtrace_symbols} function. Instead of returning
|
|
the strings to the caller, it writes the strings to the file descriptor
|
|
@var{fd}, one per line. It does not use the @code{malloc} function, and
|
|
can therefore be used in situations where that function might fail.
|
|
@end deftypefun
|
|
|
|
The following program illustrates the use of these functions. Note that
|
|
the array to contain the return addresses returned by @code{backtrace}
|
|
is allocated on the stack. Therefore code like this can be used in
|
|
situations where the memory handling via @code{malloc} does not work
|
|
anymore (in which case the @code{backtrace_symbols} has to be replaced
|
|
by a @code{backtrace_symbols_fd} call as well). The number of return
|
|
addresses is normally not very large. Even complicated programs rather
|
|
seldom have a nesting level of more than, say, 50 and with 200 possible
|
|
entries probably all programs should be covered.
|
|
|
|
@smallexample
|
|
@include execinfo.c.texi
|
|
@end smallexample
|