gdbint.texinfo

早期freebsd实现

later.  When your code does something (like @code{malloc} some memory, or open
a file) that needs to be undone later (e.g. free the memory or close
the file), it can make a cleanup.  The cleanup will be done at some
future point:  when the command is finished, when an error occurs, or
when your code decides it's time to do cleanups.

You can also discard cleanups, that is, throw them away without doing
what they say.  This is only done if you ask that it be done.

Syntax:

@table @code
@item @var{old_chain} = make_cleanup (@var{function}, @var{arg});
Make a cleanup which will cause @var{function} to be called with @var{arg}
(a @code{char *}) later.  The result, @var{old_chain}, is a handle that can be
passed to @code{do_cleanups} or @code{discard_cleanups} later.  Unless you are
going to call @code{do_cleanups} or @code{discard_cleanups} yourself,
you can ignore the result from @code{make_cleanup}.


@item do_cleanups (@var{old_chain});
Perform all cleanups done since @code{make_cleanup} returned @var{old_chain}.
E.g.:   
@example
make_cleanup (a, 0); 
old = make_cleanup (b, 0); 
do_cleanups (old);
@end example
@noindent
will call @code{b()} but will not call @code{a()}.  The cleanup that calls @code{a()} will remain
in the cleanup chain, and will be done later unless otherwise discarded.@refill

@item discard_cleanups (@var{old_chain});
Same as @code{do_cleanups} except that it just removes the cleanups from the
chain and does not call the specified functions.

@end table

Some functions, e.g. @code{fputs_filtered()} or @code{error()}, specify that they
``should not be called when cleanups are not in place''.  This means
that any actions you need to reverse in the case of an error or
interruption must be on the cleanup chain before you call these functions,
since they might never return to your code (they @samp{longjmp} instead).


@node Wrapping
@chapter Wrapping Output Lines

Output that goes through @code{printf_filtered} or @code{fputs_filtered} or
@code{fputs_demangled} needs only to have calls to @code{wrap_here} added 
in places that would be good breaking points.  The utility routines
will take care of actually wrapping if the line width is exceeded.

The argument to @code{wrap_here} is an indentation string which is printed
@emph{only} if the line breaks there.  This argument is saved away and used
later.  It must remain valid until the next call to @code{wrap_here} or
until a newline has been printed through the @code{*_filtered} functions.
Don't pass in a local variable and then return!

It is usually best to call @code{wrap_here()} after printing a comma or space.
If you call it before printing a space, make sure that your indentation
properly accounts for the leading space that will print if the line wraps
there.

Any function or set of functions that produce filtered output must finish
by printing a newline, to flush the wrap buffer, before switching to
unfiltered (``@code{printf}'') output.  Symbol reading routines that print
warnings are a good example.


@node Frames
@chapter Frames

A frame is a construct that GDB uses to keep track of calling and called
functions.

@table @code
@item FRAME_FP
in the machine description has no meaning to the machine-independent
part of GDB, except that it is used when setting up a new frame from
scratch, as follows:

@example
      create_new_frame (read_register (FP_REGNUM), read_pc ()));
@end example

Other than that, all the meaning imparted to @code{FP_REGNUM} is imparted by
the machine-dependent code.  So, @code{FP_REGNUM} can have any value that
is convenient for the code that creates new frames.  (@code{create_new_frame}
calls @code{INIT_EXTRA_FRAME_INFO} if it is defined; that is where you should
use the @code{FP_REGNUM} value, if your frames are nonstandard.)

@item FRAME_CHAIN
Given a GDB frame, determine the address of the calling function's
frame.  This will be used to create a new GDB frame struct, and then
@code{INIT_EXTRA_FRAME_INFO} and @code{INIT_FRAME_PC} will be called for
the new frame.
@end table

@node Coding Style
@chapter Coding Style

GDB is generally written using the GNU coding standards, as described in
@file{standards.texi}, which you can get from the Free Software
Foundation.  There are some additional considerations for GDB maintainers
that reflect the unique environment and style of GDB maintenance.
If you follow these guidelines, GDB will be more consistent and easier
to maintain.

GDB's policy on the use of prototypes is that prototypes are used
to @emph{declare} functions but never to @emph{define} them.  Simple
macros are used in the declarations, so that a non-ANSI compiler can
compile GDB without trouble.  The simple macro calls are used like
this:

@example @code
extern int
memory_remove_breakpoint PARAMS ((CORE_ADDR, char *));
@end example

Note the double parentheses around the parameter types.  This allows
an arbitrary number of parameters to be described, without freaking
out the C preprocessor.  When the function has no parameters, it
should be described like:

@example @code
void
noprocess PARAMS ((void));
@end example

The @code{PARAMS} macro expands to its argument in ANSI C, or to a simple
@code{()} in traditional C.

All external functions should have a @code{PARAMS} declaration in a
header file that callers include.  All static functions should have such
a declaration near the top of their source file.

We don't have a gcc option that will properly check that these rules
have been followed, but it's GDB policy, and we periodically check it
using the tools available (plus manual labor), and clean up any remnants.

@node Host Conditionals
@chapter Host Conditionals

When GDB is configured and compiled, various macros are defined or left
undefined, to control compilation based on the attributes of the host
system.  These macros and their meanings are:

@emph{NOTE:  For now, both host and target conditionals are here.
Eliminate target conditionals from this list as they are identified.}

@table @code
@item ALIGN_SIZE
alloca.c
@item BLOCK_ADDRESS_FUNCTION_RELATIVE
dbxread.c
@item GDBINIT_FILENAME
main.c
@item KERNELDEBUG
tm-hppa.h
@item MEM_FNS_DECLARED
defs.h
@item NO_SYS_FILE
dbxread.c
@item PYRAMID_CONTROL_FRAME_DEBUGGING
pyr-xdep.c
@item SIGWINCH_HANDLER_BODY
utils.c
@item 1
buildsym.c
@item 1
dbxread.c
@item 1
dbxread.c
@item 1
buildsym.c
@item 1
dwarfread.c
@item 1
valops.c
@item 1
valops.c
@item 1
pyr-xdep.c
@item ADDITIONAL_OPTIONS
main.c
@item ADDITIONAL_OPTION_CASES
main.c
@item ADDITIONAL_OPTION_HANDLER
main.c
@item ADDITIONAL_OPTION_HELP
main.c
@item ADDR_BITS_REMOVE
defs.h
@item AIX_BUGGY_PTRACE_CONTINUE
infptrace.c
@item ALIGN_STACK_ON_STARTUP
main.c
@item ALTOS
altos-xdep.c
@item ALTOS_AS
xm-altos.h
@item ASCII_COFF
remote-adapt.c
@item BADMAG
coffread.c
@item BCS
tm-delta88.h
@item BEFORE_MAIN_LOOP_HOOK
main.c
@item BELIEVE_PCC_PROMOTION
coffread.c
@item BELIEVE_PCC_PROMOTION_TYPE
stabsread.c
@item BIG_ENDIAN
defs.h
@item BITS_BIG_ENDIAN
defs.h
@item BKPT_AT_MAIN
solib.c
@item BLOCK_ADDRESS_ABSOLUTE
dbxread.c
@item BPT_VECTOR
tm-68k.h
@item BREAKPOINT
tm-68k.h
@item BREAKPOINT_DEBUG
breakpoint.c
@item BROKEN_LARGE_ALLOCA
Avoid large @code{alloca}'s.  For example, on sun's, Large alloca's fail
because the attempt to increase the stack limit in main() fails because
shared libraries are allocated just below the initial stack limit.  The
SunOS kernel will not allow the stack to grow into the area occupied by
the shared libraries.
@item BSTRING
regex.c
@item CALL_DUMMY
valops.c
@item CALL_DUMMY_LOCATION
inferior.h
@item CALL_DUMMY_STACK_ADJUST
valops.c
@item CANNOT_FETCH_REGISTER
hppabsd-xdep.c
@item CANNOT_STORE_REGISTER
findvar.c
@item CFRONT_PRODUCER
dwarfread.c
@item CHILD_PREPARE_TO_STORE
inftarg.c
@item CLEAR_DEFERRED_STORES
inflow.c
@item CLEAR_SOLIB
objfiles.c
@item COFF_ENCAPSULATE
hppabsd-tdep.c
@item COFF_FORMAT
symm-tdep.c
@item COFF_NO_LONG_FILE_NAMES
coffread.c
@item CORE_NEEDS_RELOCATION
stack.c
@item CPLUS_MARKER
cplus-dem.c
@item CREATE_INFERIOR_HOOK
infrun.c
@item C_ALLOCA
regex.c
@item C_GLBLREG
coffread.c
@item DAMON
xcoffexec.c
@item DBXREAD_ONLY
partial-stab.h
@item DBX_PARM_SYMBOL_CLASS
stabsread.c
@item DEBUG
remote-adapt.c
@item DEBUG_INFO
partial-stab.h
@item DEBUG_PTRACE
hppabsd-xdep.c
@item DECR_PC_AFTER_BREAK
breakpoint.c
@item DEFAULT_PROMPT
main.c
@item DELTA88
m88k-xdep.c
@item DEV_TTY
symmisc.c
@item DGUX
m88k-xdep.c
@item DISABLE_UNSETTABLE_BREAK
breakpoint.c
@item DONT_USE_REMOTE
remote.c
@item DO_DEFERRED_STORES
infrun.c
@item DO_REGISTERS_INFO
infcmd.c
@item END_OF_TEXT_DEFAULT
dbxread.c
@item EXTERN
buildsym.h
@item EXTRACT_RETURN_VALUE
tm-68k.h
@item EXTRACT_STRUCT_VALUE_ADDRESS
values.c
@item EXTRA_FRAME_INFO
frame.h
@item EXTRA_SYMTAB_INFO
symtab.h
@item FILES_INFO_HOOK
target.c
@item FIXME
coffread.c
@item FLOAT_INFO
infcmd.c
@item FOPEN_RB
defs.h
@item FP0_REGNUM
a68v-xdep.c
@item FPC_REGNUM
mach386-xdep.c
@item FP_REGNUM
parse.c
@item FRAMELESS_FUNCTION_INVOCATION
blockframe.c
@item FRAME_ARGS_ADDRESS_CORRECT
stack.c
@item FRAME_CHAIN_COMBINE
blockframe.c
@item FRAME_CHAIN_VALID
frame.h
@item FRAME_CHAIN_VALID_ALTERNATE
frame.h
@item FRAME_FIND_SAVED_REGS
stack.c
@item FRAME_GET_BASEREG_VALUE
frame.h
@item FRAME_NUM_ARGS
tm-68k.h
@item FRAME_SPECIFICATION_DYADIC
stack.c
@item FUNCTION_EPILOGUE_SIZE
coffread.c
@item F_OK
xm-ultra3.h
@item GCC2_COMPILED_FLAG_SYMBOL
dbxread.c
@item GCC_COMPILED_FLAG_SYMBOL
dbxread.c
@item GCC_MANGLE_BUG
symtab.c
@item GCC_PRODUCER
dwarfread.c
@item GET_SAVED_REGISTER
findvar.c
@item GPLUS_PRODUCER
dwarfread.c
@item GR64_REGNUM
remote-adapt.c
@item GR64_REGNUM
remote-mm.c
@item HANDLE_RBRAC
partial-stab.h
@item HAVE_68881
m68k-tdep.c
@item HAVE_MMAP
In some cases, use the system call @code{mmap} for reading symbol
tables.  For some machines this allows for sharing and quick updates.
@item HAVE_REGISTER_WINDOWS
findvar.c
@item HAVE_SIGSETMASK
main.c
@item HAVE_TERMIO
inflow.c
@item HEADER_SEEK_FD
arm-tdep.c
@item HOSTING_ONLY
xm-rtbsd.h
@item HOST_BYTE_ORDER
ieee-float.c
@item HPUX_ASM
xm-hp300hpux.h
@item HPUX_VERSION_5
hp300ux-xdep.c
@item HP_OS_BUG
infrun.c
@item I80960
remote-vx.c
@item IBM6000_HOST
breakpoint.c
@item IBM6000_TARGET
buildsym.c
@item IEEE_DEBUG
ieee-float.c
@item IEEE_FLOAT
valprint.c
@item IGNORE_SYMBOL
dbxread.c
@item INIT_EXTRA_FRAME_INFO
blockframe.c
@item INIT_EXTRA_SYMTAB_INFO
symfile.c
@item INIT_FRAME_PC
blockframe.c
@item INNER_THAN
valops.c
@item INT_MAX
defs.h
@item INT_MIN
defs.h
@item IN_GDB
i960-pinsn.c
@item IN_SIGTRAMP
infrun.c
@item IN_SOLIB_TRAMPOLINE
infrun.c
@item ISATTY
main.c
@item IS_TRAPPED_INTERNALVAR
values.c
@item KERNELDEBUG
dbxread.c
@item KERNEL_DEBUGGING
tm-ultra3.h
@item KERNEL_U_ADDR
Define this to the address of the @code{u} structure (the ``user struct'',
also known as the ``u-page'') in kernel virtual memory.  GDB needs to know
this so that it can subtract this address from absolute addresses in
the upage, that are obtained via ptrace or from core files.  On systems
that don't need this value, set it to zero.
@item KERNEL_U_ADDR_BSD
Define this to cause GDB to determine the address of @code{u} at runtime,
by using Berkeley-style @code{nlist} on the kernel's image in the root
directory.
@item KERNEL_U_ADDR_HPUX
Define this to cause GDB to determine the address of @code{u} at runtime,
by using HP-style @code{nlist} on the kernel's image in the root
directory.
@item LCC_PRODUCER
dwarfread.c
@item LITTLE_ENDIAN
defs.h
@item LOG_FILE
remote-adapt.c
@item LONGERNAMES
cplus-dem.c
@item LONGEST
defs.h
@item LONG_LONG
defs.h
@item LONG_MAX
defs.h
@item LSEEK_NOT_LINEAR
source.c
@item L_LNNO32
coffread.c