Update.
2001-01-17 Ulrich Drepper <drepper@redhat.com> * manual/Makefile (chapters): Add debug. * manual/debug.texi: New file. * manual/examples/execinfo.c: New file. Patch by suckfish@ihug.co.nz.
This commit is contained in:
Ulrich Drepper
parent
17abb551ce
commit
2244ddf2bf
|
|
@ -1,3 +1,10 @@
|
|||
2001-01-17 Ulrich Drepper <drepper@redhat.com>
|
||||
|
||||
* manual/Makefile (chapters): Add debug.
|
||||
* manual/debug.texi: New file.
|
||||
* manual/examples/execinfo.c: New file.
|
||||
Patch by suckfish@ihug.co.nz.
|
||||
|
||||
2001-01-17 Andreas Schwab <schwab@suse.de>
|
||||
|
||||
* sysdeps/m68k/bits/byteswap.h (__bswap_32): Add cast to avoid
|
||||
|
|
|
|||
|
|
@ -56,7 +56,7 @@ chapters = $(addsuffix .texi, \
|
|||
message search pattern io stdio llio filesys \
|
||||
pipe socket terminal syslog math arith time \
|
||||
resource setjmp signal startup process job nss \
|
||||
users sysinfo conf crypt)
|
||||
users sysinfo conf crypt debug)
|
||||
add-chapters = $(wildcard $(foreach d, $(add-ons), ../$d/$d.texi))
|
||||
appendices = lang.texi header.texi install.texi maint.texi contrib.texi
|
||||
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
@c This node must have no pointers.
|
||||
@node Cryptographic Functions
|
||||
@c @node Cryptographic Functions, , System Configuration, Top
|
||||
@c @node Cryptographic Functions, Debugging Support, System Configuration, Top
|
||||
@chapter DES Encryption and Password Handling
|
||||
@c %MENU% DES encryption and password handling
|
||||
|
||||
|
|
@ -31,7 +31,7 @@ It also provides support for Secure RPC, and some library functions that
|
|||
can be used to perform normal DES encryption.
|
||||
|
||||
The add-on is not included in the main distribution of the GNU C library
|
||||
because some governments, most notably those of France, Russia,
|
||||
because some governments, most notably those of France, Russia,
|
||||
and the US, have very restrictive rules governing the distribution and
|
||||
use of encryption software. The first section below tries to describe some
|
||||
of those rules.
|
||||
|
|
@ -213,7 +213,7 @@ The Data Encryption Standard is described in the US Government Federal
|
|||
Information Processing Standards (FIPS) 46-3 published by the National
|
||||
Institute of Standards and Technology. The DES has been very thoroughly
|
||||
analysed since it was developed in the late 1970s, and no new
|
||||
significant flaws have been found.
|
||||
significant flaws have been found.
|
||||
|
||||
However, the DES uses only a 56-bit key (plus 8 parity bits), and a
|
||||
machine has been built in 1998 which can search through all possible
|
||||
|
|
@ -269,13 +269,13 @@ stored in a @code{char}, but there are no parity bits in @var{block}.
|
|||
|
||||
These are reentrant versions of @code{setkey} and @code{encrypt}. The
|
||||
only difference is the extra parameter, which stores the expanded
|
||||
version of @var{key}. Before calling @code{setkey_r} the first time,
|
||||
version of @var{key}. Before calling @code{setkey_r} the first time,
|
||||
@code{data->initialised} must be cleared to zero.
|
||||
@end deftypefun
|
||||
|
||||
The @code{setkey_r} and @code{encrypt_r} functions are GNU extensions.
|
||||
@code{setkey}, @code{encrypt}, @code{setkey_r}, and @code{encrypt_r} are
|
||||
defined in @file{crypt.h}.
|
||||
defined in @file{crypt.h}.
|
||||
|
||||
If the @code{crypt} add-on is not used to build the library, programs
|
||||
that use these four functions will crash when the functions are called.
|
||||
|
|
|
|||
|
|
@ -0,0 +1,110 @@
|
|||
@node Debugging Support
|
||||
@c @node Debugging Support, , Cryptographic Functions, Top
|
||||
@c %MENU% Functions to help debugging applications.
|
||||
@chapter Debugging support
|
||||
|
||||
Applications often get debugged using dedicated debugger programs. But
|
||||
sometimes this is not possible and it is in any case useful to provide
|
||||
the developer at the time the problems are experienced with as much
|
||||
information as possible. For this reason there exist a few functions
|
||||
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 programatically 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 fitting 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 optimisations may interfere with obtaining a
|
||||
valid backtrace. Function inlining causes the inlined function to not
|
||||
have a stack frame; tail call optimisation 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 hexidecimal).
|
||||
|
||||
Currently, the function name and offset can currently only be obtained
|
||||
on systems that use the ELF binary format for programs and libraries.
|
||||
On other systems, only the hexidecimal return address will be present.
|
||||
Also, you may need to pass additional flags to the linker
|
||||
(@code{-rdynamic} on systems using GNU ld) to make the function names
|
||||
available to the program.
|
||||
|
||||
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, but 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
|
||||
Loading…
Reference in New Issue