2004-10-08 Jeff Johnston <jjohnstn@redhat.com>
[deliverable/binutils-gdb.git] / gdb / doc / gdbint.texinfo
index 081f9995e8f253155676fd2e651d37d075bc1c71..38532d3f0ca6718ded76a228a3d3d7407f95960f 100644 (file)
@@ -1,7 +1,7 @@
 \input texinfo   @c -*- texinfo -*-
 @setfilename gdbint.info
 @include gdb-cfg.texi
-@dircategory Programming & development tools.
+@dircategory Software development
 @direntry
 * Gdb-Internals: (gdbint).     The GNU debugger's internals.
 @end direntry
@@ -476,9 +476,10 @@ no other code touches these values, the implementations of the above
 two macros can use them for their internal purposes.
 
 @findex target_stopped_data_address
-@item target_stopped_data_address ()
-If the inferior has some watchpoint that triggered, return the address
-associated with that watchpoint.  Otherwise, return zero.
+@item target_stopped_data_address (@var{addr_p})
+If the inferior has some watchpoint that triggered, place the address
+associated with the watchpoint at the location pointed to by
+@var{addr_p} and return non-zero.  Otherwise, return zero.
 
 @findex HAVE_STEPPABLE_WATCHPOINT
 @item HAVE_STEPPABLE_WATCHPOINT
@@ -598,15 +599,25 @@ less than 4, the number of debug registers available to x86
 processors.
 
 @findex i386_stopped_data_address
-@item i386_stopped_data_address (void)
-The macros @code{STOPPED_BY_WATCHPOINT} and
-@code{target_stopped_data_address} are set to call this function.  The
-argument passed to @code{STOPPED_BY_WATCHPOINT} is ignored.  This
+@item i386_stopped_data_address (@var{addr_p})
+The target function
+@code{target_stopped_data_address} is set to call this function.
+This
 function examines the breakpoint condition bits in the DR6 Debug
 Status register, as returned by the @code{I386_DR_LOW_GET_STATUS}
 macro, and returns the address associated with the first bit that is
 set in DR6.
 
+@findex i386_stopped_by_watchpoint
+@item i386_stopped_by_watchpoint (void)
+The macro @code{STOPPED_BY_WATCHPOINT}
+is set to call this function.  The
+argument passed to @code{STOPPED_BY_WATCHPOINT} is ignored.  This
+function examines the breakpoint condition bits in the DR6 Debug
+Status register, as returned by the @code{I386_DR_LOW_GET_STATUS}
+macro, and returns true if any bit is set.  Otherwise, false is
+returned.
+
 @findex i386_insert_watchpoint
 @findex i386_remove_watchpoint
 @item i386_insert_watchpoint (@var{addr}, @var{len}, @var{type})
@@ -654,7 +665,7 @@ register.
 @item i386_stopped_by_hwbp (void)
 This function returns non-zero if the inferior has some watchpoint or
 hardware breakpoint that triggered.  It works like
-@code{i386_stopped_data_address}, except that it doesn't return the
+@code{i386_stopped_data_address}, except that it doesn't record the
 address whose watchpoint triggered.
 
 @findex i386_cleanup_dregs
@@ -1372,7 +1383,7 @@ Finally, here's an example of printing an address.  The original code:
 @smallexample
   annotate_field (4);
   printf_filtered ("%s ",
-        local_hex_string_custom ((unsigned long) b->address, "08l"));
+        hex_string_custom ((unsigned long) b->address, 8));
 @end smallexample
 
 It became:
@@ -2134,9 +2145,6 @@ The default name of @value{GDBN}'s initialization file (normally
 @item NO_STD_REGS
 This macro is deprecated.
 
-@item NO_SYS_FILE
-Define this if your system does not have a @code{<sys/file.h>}.
-
 @item SIGWINCH_HANDLER
 If your host defines @code{SIGWINCH}, you can define this to be the name
 of a function to be called if @code{SIGWINCH} is received.
@@ -2168,19 +2176,9 @@ The default value of the prompt string (normally @code{"(gdb) "}).
 @cindex terminal device
 The name of the generic TTY device, defaults to @code{"/dev/tty"}.
 
-@item FCLOSE_PROVIDED
-Define this if the system declares @code{fclose} in the headers included
-in @code{defs.h}.  This isn't needed unless your compiler is unusually
-anal.
-
 @item FOPEN_RB
 Define this if binary files are opened the same way as text files.
 
-@item GETENV_PROVIDED
-Define this if the system declares @code{getenv} in its headers included
-in @code{defs.h}.  This isn't needed unless your compiler is unusually
-anal.
-
 @item HAVE_MMAP
 @findex mmap
 In some cases, use the system call @code{mmap} for reading symbol
@@ -2251,10 +2249,6 @@ of functions to indicate that they never return.  The default is already
 set correctly if compiling with GCC.  This will almost never need to be
 defined.
 
-@item NO_SIGINTERRUPT
-@findex siginterrupt
-Define this to indicate that @code{siginterrupt} is not available.
-
 @item SEEK_CUR
 @itemx SEEK_SET
 Define these to appropriate value for the system @code{lseek}, if not already
@@ -2264,11 +2258,6 @@ defined.
 This is the signal for stopping @value{GDBN}.  Defaults to
 @code{SIGTSTP}.  (Only redefined for the Convex.)
 
-@item USE_O_NOCTTY
-Define this if the interior's tty should be opened with the @code{O_NOCTTY}
-flag.  (FIXME: This should be a native-only flag, but @file{inflow.c} is
-always linked in.)
-
 @item USG
 Means that System V (prior to SVR4) include files are in use.  (FIXME:
 This symbol is abused in @file{infrun.c}, @file{regex.c}, and
@@ -2930,12 +2919,6 @@ Define if the compiler promotes a @code{short} or @code{char}
 parameter to an @code{int}, but still reports the parameter as its
 original type, rather than the promoted type.
 
-@item BELIEVE_PCC_PROMOTION_TYPE
-@findex BELIEVE_PCC_PROMOTION_TYPE
-Define this if @value{GDBN} should believe the type of a @code{short}
-argument when compiled by @code{pcc}, but look within a full int space to get
-its value.  Only defined for Sun-3 at present.
-
 @item BITS_BIG_ENDIAN
 @findex BITS_BIG_ENDIAN
 Define this if the numbering of bits in the targets does @strong{not} match the
@@ -3041,35 +3024,6 @@ Since the adjustment of a breakpoint may significantly alter a user's
 expectation, @value{GDBN} prints a warning when an adjusted breakpoint
 is initially set and each time that that breakpoint is hit.
 
-@item DEPRECATED_CALL_DUMMY_WORDS
-@findex DEPRECATED_CALL_DUMMY_WORDS
-Pointer to an array of @code{LONGEST} words of data containing
-host-byte-ordered @code{DEPRECATED_REGISTER_SIZE} sized values that
-partially specify the sequence of instructions needed for an inferior
-function call.
-
-Should be deprecated in favor of a macro that uses target-byte-ordered
-data.
-
-This method has been replaced by @code{push_dummy_code}
-(@pxref{push_dummy_code}).
-
-@item DEPRECATED_SIZEOF_CALL_DUMMY_WORDS
-@findex DEPRECATED_SIZEOF_CALL_DUMMY_WORDS
-The size of @code{DEPRECATED_CALL_DUMMY_WORDS}.  This must return a
-positive value.  See also @code{DEPRECATED_CALL_DUMMY_LENGTH}.
-
-This method has been replaced by @code{push_dummy_code}
-(@pxref{push_dummy_code}).
-
-@item CALL_DUMMY
-@findex CALL_DUMMY
-A static initializer for @code{DEPRECATED_CALL_DUMMY_WORDS}.
-Deprecated.
-
-This method has been replaced by @code{push_dummy_code}
-(@pxref{push_dummy_code}).
-
 @item CALL_DUMMY_LOCATION
 @findex CALL_DUMMY_LOCATION
 See the file @file{inferior.h}.
@@ -3077,12 +3031,6 @@ See the file @file{inferior.h}.
 This method has been replaced by @code{push_dummy_code}
 (@pxref{push_dummy_code}).
 
-@item DEPRECATED_CALL_DUMMY_STACK_ADJUST
-@findex DEPRECATED_CALL_DUMMY_STACK_ADJUST
-Stack adjustment needed when performing an inferior function call.  This
-function is no longer needed.  @xref{push_dummy_call}, which can handle
-all alignment directly.
-
 @item CANNOT_FETCH_REGISTER (@var{regno})
 @findex CANNOT_FETCH_REGISTER
 A C expression that should be nonzero if @var{regno} cannot be fetched
@@ -3096,15 +3044,6 @@ written to the target.  This is often the case for program counters,
 status words, and other special registers.  If this is not defined,
 @value{GDBN} will assume that all registers may be written.
 
-@item DO_DEFERRED_STORES
-@itemx CLEAR_DEFERRED_STORES
-@findex CLEAR_DEFERRED_STORES
-@findex DO_DEFERRED_STORES
-Define this to execute any deferred stores of registers into the inferior,
-and to cancel any deferred stores.
-
-Currently only implemented correctly for native Sparc configurations?
-
 @item int CONVERT_REGISTER_P(@var{regnum})
 @findex CONVERT_REGISTER_P
 Return non-zero if register @var{regnum} can represent data values in a
@@ -3195,8 +3134,8 @@ macro to be the number (greater than or equal to zero) of that register.
 This should only need to be defined if @code{DEPRECATED_TARGET_READ_FP}
 is not defined.
 
-@item FRAMELESS_FUNCTION_INVOCATION(@var{fi})
-@findex FRAMELESS_FUNCTION_INVOCATION
+@item DEPRECATED_FRAMELESS_FUNCTION_INVOCATION(@var{fi})
+@findex DEPRECATED_FRAMELESS_FUNCTION_INVOCATION
 Define this to an expression that returns 1 if the function invocation
 represented by @var{fi} does not have a stack frame associated with it.
 Otherwise return 0.
@@ -3314,20 +3253,20 @@ function end symbol is 0.  For such targets, you must define
 @code{FUNCTION_EPILOGUE_SIZE} to expand into the standard size of a
 function's epilogue.
 
-@item FUNCTION_START_OFFSET
-@findex FUNCTION_START_OFFSET
+@item DEPRECATED_FUNCTION_START_OFFSET
+@findex DEPRECATED_FUNCTION_START_OFFSET
 An integer, giving the offset in bytes from a function's address (as
 used in the values of symbols, function pointers, etc.), and the
 function's first genuine instruction.
 
 This is zero on almost all machines: the function's address is usually
-the address of its first instruction.  However, on the VAX, for example,
-each function starts with two bytes containing a bitmask indicating
-which registers to save upon entry to the function.  The VAX @code{call}
-instructions check this value, and save the appropriate registers
-automatically.  Thus, since the offset from the function's address to
-its first instruction is two bytes, @code{FUNCTION_START_OFFSET} would
-be 2 on the VAX.
+the address of its first instruction.  However, on the VAX, for
+example, each function starts with two bytes containing a bitmask
+indicating which registers to save upon entry to the function.  The
+VAX @code{call} instructions check this value, and save the
+appropriate registers automatically.  Thus, since the offset from the
+function's address to its first instruction is two bytes,
+@code{DEPRECATED_FUNCTION_START_OFFSET} would be 2 on the VAX.
 
 @item GCC_COMPILED_FLAG_SYMBOL
 @itemx GCC2_COMPILED_FLAG_SYMBOL
@@ -3417,10 +3356,10 @@ The epilogue of a function is defined as the part of a function where
 the stack frame of the function already has been destroyed up to the
 final `return from function call' instruction.
 
-@item SIGTRAMP_START (@var{pc})
-@findex SIGTRAMP_START
-@itemx SIGTRAMP_END (@var{pc})
-@findex SIGTRAMP_END
+@item DEPRECATED_SIGTRAMP_START (@var{pc})
+@findex DEPRECATED_SIGTRAMP_START
+@itemx DEPRECATED_SIGTRAMP_END (@var{pc})
+@findex DEPRECATED_SIGTRAMP_END
 Define these to be the start and end address of the @code{sigtramp} for the
 given @var{pc}.  On machines where the address is just a compile time
 constant, the macro expansion will typically just ignore the supplied
@@ -3557,43 +3496,6 @@ form.
 Return the appropriate register set for a core file section with name
 @var{sect_name} and size @var{sect_size}.
 
-
-@item RETURN_VALUE_ON_STACK(@var{type})
-@findex RETURN_VALUE_ON_STACK
-@cindex returning structures by value
-@cindex structures, returning by value
-
-Return non-zero if values of type TYPE are returned on the stack, using
-the ``struct convention'' (i.e., the caller provides a pointer to a
-buffer in which the callee should store the return value).  This
-controls how the @samp{finish} command finds a function's return value,
-and whether an inferior function call reserves space on the stack for
-the return value.
-
-The full logic @value{GDBN} uses here is kind of odd.  
-
-@itemize @bullet
-@item
-If the type being returned by value is not a structure, union, or array,
-and @code{RETURN_VALUE_ON_STACK} returns zero, then @value{GDBN}
-concludes the value is not returned using the struct convention.
-
-@item
-Otherwise, @value{GDBN} calls @code{USE_STRUCT_CONVENTION} (see below).
-If that returns non-zero, @value{GDBN} assumes the struct convention is
-in use.
-@end itemize
-
-In other words, to indicate that a given type is returned by value using
-the struct convention, that type must be either a struct, union, array,
-or something @code{RETURN_VALUE_ON_STACK} likes, @emph{and} something
-that @code{USE_STRUCT_CONVENTION} likes.
-
-Note that, in C and C@t{++}, arrays are never returned by value.  In those
-languages, these predicates will always see a pointer type, never an
-array type.  All the references above to arrays being returned by value
-apply only to other languages.
-
 @item SOFTWARE_SINGLE_STEP_P()
 @findex SOFTWARE_SINGLE_STEP_P
 Define this as 1 if the target does not have a hardware single-step
@@ -3638,22 +3540,6 @@ and guess the starting and ending addresses of the compilation unit from
 them.
 @end itemize
 
-@item PCC_SOL_BROKEN
-@findex PCC_SOL_BROKEN
-(Used only in the Convex target.)
-
-@item PC_IN_SIGTRAMP (@var{pc}, @var{name})
-@findex PC_IN_SIGTRAMP
-@cindex sigtramp
-The @dfn{sigtramp} is a routine that the kernel calls (which then calls
-the signal handler).  On most machines it is a library routine that is
-linked into the executable.
-
-This function, given a program counter value in @var{pc} and the
-(possibly NULL) name of the function in which that @var{pc} resides,
-returns nonzero if the @var{pc} and/or @var{name} show that we are in
-sigtramp.
-
 @item PC_LOAD_SEGMENT
 @findex PC_LOAD_SEGMENT
 If defined, print information about the load segment for the program
@@ -3701,7 +3587,7 @@ definition is only used in generic code when parsing "$ps".)
 If defined, used by @code{frame_pop} to remove a stack frame.  This
 method has been superseeded by generic code.
 
-@item push_dummy_call (@var{gdbarch}, @var{func_addr}, @var{regcache}, @var{pc_addr}, @var{nargs}, @var{args}, @var{sp}, @var{struct_return}, @var{struct_addr})
+@item push_dummy_call (@var{gdbarch}, @var{function}, @var{regcache}, @var{pc_addr}, @var{nargs}, @var{args}, @var{sp}, @var{struct_return}, @var{struct_addr})
 @findex push_dummy_call
 @findex DEPRECATED_PUSH_ARGUMENTS.
 @anchor{push_dummy_call} Define this to push the dummy frame's call to
@@ -3709,13 +3595,15 @@ the inferior function onto the stack.  In addition to pushing
 @var{nargs}, the code should push @var{struct_addr} (when
 @var{struct_return}), and the return address (@var{bp_addr}).
 
+@var{function} is a pointer to a @code{struct value}; on architectures that use
+function descriptors, this contains the function descriptor value.
+
 Returns the updated top-of-stack pointer.
 
 This method replaces @code{DEPRECATED_PUSH_ARGUMENTS}.
 
 @item CORE_ADDR push_dummy_code (@var{gdbarch}, @var{sp}, @var{funaddr}, @var{using_gcc}, @var{args}, @var{nargs}, @var{value_type}, @var{real_pc}, @var{bp_addr})
 @findex push_dummy_code
-@findex DEPRECATED_FIX_CALL_DUMMY
 @anchor{push_dummy_code} Given a stack based call dummy, push the
 instruction sequence (including space for a breakpoint) to which the
 called function should return.
@@ -3728,24 +3616,8 @@ By default, the stack is grown sufficient to hold a frame-aligned
 (@pxref{frame_align}) breakpoint, @var{bp_addr} is set to the address
 reserved for that breakpoint, and @var{real_pc} set to @var{funaddr}.
 
-This method replaces @code{DEPRECATED_CALL_DUMMY_WORDS},
-@code{DEPRECATED_SIZEOF_CALL_DUMMY_WORDS}, @code{CALL_DUMMY},
-@code{CALL_DUMMY_LOCATION}, @code{DEPRECATED_REGISTER_SIZE},
-@code{GDB_TARGET_IS_HPPA},
-@code{DEPRECATED_CALL_DUMMY_BREAKPOINT_OFFSET}, and
-@code{DEPRECATED_FIX_CALL_DUMMY}.
-
-@item DEPRECATED_PUSH_DUMMY_FRAME
-@findex DEPRECATED_PUSH_DUMMY_FRAME
-Used in @samp{call_function_by_hand} to create an artificial stack frame.
-
-@item DEPRECATED_REGISTER_BYTES
-@findex DEPRECATED_REGISTER_BYTES
-The total amount of space needed to store @value{GDBN}'s copy of the
-machine's register state.
-
-This is no longer needed.  @value{GDBN} instead computes the size of the
-register buffer at run-time.
+This method replaces @code{CALL_DUMMY_LOCATION},
+@code{DEPRECATED_REGISTER_SIZE}.
 
 @item REGISTER_NAME(@var{i})
 @findex REGISTER_NAME
@@ -3876,10 +3748,6 @@ value that is to be returned.
 This method has been deprecated in favour of @code{gdbarch_return_value}
 (@pxref{gdbarch_return_value}).
 
-@item SUN_FIXED_LBRAC_BUG
-@findex SUN_FIXED_LBRAC_BUG
-(Used only for Sun-3 and Sun-4 targets.)
-
 @item SYMBOL_RELOADING_DEFAULT
 @findex SYMBOL_RELOADING_DEFAULT
 The default value of the ``symbol-reloading'' variable.  (Never defined in
@@ -3959,9 +3827,9 @@ Number of bits in a short integer; defaults to @code{2 * TARGET_CHAR_BIT}.
 @findex read_sp
 @findex read_fp
 @anchor{TARGET_READ_SP} These change the behavior of @code{read_pc},
-@code{write_pc}, @code{read_sp} and @code{deprecated_read_fp}.  For most
-targets, these may be left undefined.  @value{GDBN} will call the read
-and write register functions with the relevant @code{_REGNUM} argument.
+@code{write_pc}, and @code{read_sp}.  For most targets, these may be
+left undefined.  @value{GDBN} will call the read and write register
+functions with the relevant @code{_REGNUM} argument.
 
 These macros are useful when a target keeps one of these registers in a
 hard to get at place; for example, part in a segment register and part
@@ -4002,8 +3870,8 @@ frame.  The value returned must match the dummy frame stack value
 previously saved using @code{SAVE_DUMMY_FRAME_TOS}.
 @xref{SAVE_DUMMY_FRAME_TOS}.
 
-@item USE_STRUCT_CONVENTION (@var{gcc_p}, @var{type})
-@findex USE_STRUCT_CONVENTION
+@item DEPRECATED_USE_STRUCT_CONVENTION (@var{gcc_p}, @var{type})
+@findex DEPRECATED_USE_STRUCT_CONVENTION
 If defined, this must be an expression that is nonzero if a value of the
 given @var{type} being returned from a function must have space
 allocated for it on the stack.  @var{gcc_p} is true if the function
@@ -4477,10 +4345,6 @@ target systems are the same.  These macros should be defined (or left
 undefined) in @file{nm-@var{system}.h}.
 
 @table @code
-@item ATTACH_DETACH
-@findex ATTACH_DETACH
-If defined, then @value{GDBN} will include support for the @code{attach} and
-@code{detach} commands.
 
 @item CHILD_PREPARE_TO_STORE
 @findex CHILD_PREPARE_TO_STORE
@@ -4499,10 +4363,6 @@ Define this if the native-dependent code will provide its own routines
 @file{infptrace.c} is included in this configuration, the default
 routines in @file{infptrace.c} are used for these functions.
 
-@item FILES_INFO_HOOK
-@findex FILES_INFO_HOOK
-(Only defined for Convex.)
-
 @item FP0_REGNUM
 @findex FP0_REGNUM
 This macro is normally defined to be the number of the first floating
@@ -4533,12 +4393,6 @@ 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
-@findex KERNEL_U_ADDR_BSD
-Define this to cause @value{GDBN} 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
 @findex KERNEL_U_ADDR_HPUX
 Define this to cause @value{GDBN} to determine the address of @code{u} at
@@ -4556,10 +4410,6 @@ Defines the format for the name of a @file{/proc} device.  Should be
 defined in @file{nm.h} @emph{only} in order to override the default
 definition in @file{procfs.c}.
 
-@item PTRACE_FP_BUG
-@findex PTRACE_FP_BUG
-See @file{mach386-xdep.c}.
-
 @item PTRACE_ARG3_TYPE
 @findex PTRACE_ARG3_TYPE
 The type of the third argument to the @code{ptrace} system call, if it
@@ -4599,10 +4449,6 @@ the shell execs, and once when the program itself execs.  If the actual
 number of traps is something other than 2, then define this macro to
 expand into the number expected.
 
-@item SVR4_SHARED_LIBS
-@findex SVR4_SHARED_LIBS
-Define this to indicate that SVR4-style shared libraries are in use.
-
 @item USE_PROC_FS
 @findex USE_PROC_FS
 This determines whether small routines in @file{*-tdep.c}, which
@@ -4678,6 +4524,66 @@ library because it's also used in binutils, for @file{objdump}).
 @section mmalloc
 
 @section libiberty
+@cindex @code{libiberty} library
+
+The @code{libiberty} library provides a set of functions and features
+that integrate and improve on functionality found in modern operating
+systems.  Broadly speaking, such features can be divided into three
+groups: supplemental functions (functions that may be missing in some
+environments and operating systems), replacement functions (providing
+a uniform and easier to use interface for commonly used standard
+functions), and extensions (which provide additional functionality
+beyond standard functions).
+
+@value{GDBN} uses various features provided by the @code{libiberty}
+library, for instance the C@t{++} demangler, the @acronym{IEEE}
+floating format support functions, the input options parser
+@samp{getopt}, the @samp{obstack} extension, and other functions.
+
+@subsection @code{obstacks} in @value{GDBN}
+@cindex @code{obstacks}
+
+The obstack mechanism provides a convenient way to allocate and free
+chunks of memory.  Each obstack is a pool of memory that is managed
+like a stack.  Objects (of any nature, size and alignment) are
+allocated and freed in a @acronym{LIFO} fashion on an obstack (see
+@code{libiberty}'s documenatation for a more detailed explanation of
+@code{obstacks}).
+
+The most noticeable use of the @code{obstacks} in @value{GDBN} is in
+object files.  There is an obstack associated with each internal
+representation of an object file.  Lots of things get allocated on
+these @code{obstacks}: dictionary entries, blocks, blockvectors,
+symbols, minimal symbols, types, vectors of fundamental types, class
+fields of types, object files section lists, object files section
+offets lists, line tables, symbol tables, partial symbol tables,
+string tables, symbol table private data, macros tables, debug
+information sections and entries, import and export lists (som),
+unwind information (hppa), dwarf2 location expressions data.  Plus
+various strings such as directory names strings, debug format strings,
+names of types.
+
+An essential and convenient property of all data on @code{obstacks} is
+that memory for it gets allocated (with @code{obstack_alloc}) at
+various times during a debugging sesssion, but it is released all at
+once using the @code{obstack_free} function.  The @code{obstack_free}
+function takes a pointer to where in the stack it must start the
+deletion from (much like the cleanup chains have a pointer to where to
+start the cleanups).  Because of the stack like structure of the
+@code{obstacks}, this allows to free only a top portion of the
+obstack.  There are a few instances in @value{GDBN} where such thing
+happens.  Calls to @code{obstack_free} are done after some local data
+is allocated to the obstack.  Only the local data is deleted from the
+obstack.  Of course this assumes that nothing between the
+@code{obstack_alloc} and the @code{obstack_free} allocates anything
+else on the same obstack.  For this reason it is best and safest to
+use temporary @code{obstacks}.
+
+Releasing the whole obstack is also not safe per se.  It is safe only
+under the condition that we know the @code{obstacks} memory is no
+longer needed.  In @value{GDBN} we get rid of the @code{obstacks} only
+when we get rid of the whole objfile(s), for instance upon reading a
+new symbol file.
 
 @section gnu-regex
 @cindex regular expressions library
@@ -4818,138 +4724,104 @@ functions, since they might never return to your code (they
 @cindex multi-arch data
 @cindex data-pointer, per-architecture/per-module
 
-The multi-arch framework includes a mechanism for adding module specific
-per-architecture data-pointers to the @code{struct gdbarch} architecture
-object.
+The multi-arch framework includes a mechanism for adding module
+specific per-architecture data-pointers to the @code{struct gdbarch}
+architecture object.
 
-A module registers one or more per-architecture data-pointers using the
-function @code{register_gdbarch_data}:
+A module registers one or more per-architecture data-pointers using:
 
-@deftypefun struct gdbarch_data *register_gdbarch_data (gdbarch_data_init_ftype *@var{init}, gdbarch_data_free_ftype *@var{free})
+@deftypefun struct gdbarch_data *gdbarch_data_register_pre_init (gdbarch_data_pre_init_ftype *@var{pre_init})
+@var{pre_init} is used to, on-demand, allocate an initial value for a
+per-architecture data-pointer using the architecture's obstack (passed
+in as a parameter).  Since @var{pre_init} can be called during
+architecture creation, it is not parameterized with the architecture.
+and must not call modules that use per-architecture data.
+@end deftypefun
 
-The @var{init} function is used to obtain an initial value for a
-per-architecture data-pointer.  The function is called, after the
-architecture has been created, when the data-pointer is still
-uninitialized (@code{NULL}) and its value has been requested via a call
-to @code{gdbarch_data}.  A data-pointer can also be initialize
-explicitly using @code{set_gdbarch_data}.
+@deftypefun struct gdbarch_data *gdbarch_data_register_post_init (gdbarch_data_post_init_ftype *@var{post_init})
+@var{post_init} is used to obtain an initial value for a
+per-architecture data-pointer @emph{after}.  Since @var{post_init} is
+always called after architecture creation, it both receives the fully
+initialized architecture and is free to call modules that use
+per-architecture data (care needs to be taken to ensure that those
+other modules do not try to call back to this module as that will
+create in cycles in the initialization call graph).
+@end deftypefun
 
-The @var{free} function is called when a data-pointer needs to be
-destroyed.  This occurs when either the corresponding @code{struct
-gdbarch} object is being destroyed or when @code{set_gdbarch_data} is
-overriding a non-@code{NULL} data-pointer value.
+These functions return a @code{struct gdbarch_data} that is used to
+identify the per-architecture data-pointer added for that module.
 
-The function @code{register_gdbarch_data} returns a @code{struct
-gdbarch_data} that is used to identify the data-pointer that was added
-to the module.
+The per-architecture data-pointer is accessed using the function:
 
+@deftypefun void *gdbarch_data (struct gdbarch *@var{gdbarch}, struct gdbarch_data *@var{data_handle})
+Given the architecture @var{arch} and module data handle
+@var{data_handle} (returned by @code{gdbarch_data_register_pre_init}
+or @code{gdbarch_data_register_post_init}), this function returns the
+current value of the per-architecture data-pointer.  If the data
+pointer is @code{NULL}, it is first initialized by calling the
+corresponding @var{pre_init} or @var{post_init} method.
 @end deftypefun
 
-A typical module has @code{init} and @code{free} functions of the form:
+The examples below assume the following definitions:
 
 @smallexample
+struct nozel @{ int total; @};
 static struct gdbarch_data *nozel_handle;
-static void *
-nozel_init (struct gdbarch *gdbarch)
-@{
-  struct nozel *data = XMALLOC (struct nozel);
-  @dots{}
-  return data;
-@}
-@dots{}
-static void
-nozel_free (struct gdbarch *gdbarch, void *data)
-@{
-  xfree (data);
-@}
 @end smallexample
 
-Since uninitialized (@code{NULL}) data-pointers are initialized
-on-demand, an @code{init} function is free to call other modules that
-use data-pointers.  Those modules data-pointers will be initialized as
-needed.  Care should be taken to ensure that the @code{init} call graph
-does not contain cycles.
+A module can extend the architecture vector, adding additional
+per-architecture data, using the @var{pre_init} method.  The module's
+per-architecture data is then initialized during architecture
+creation.
 
-The data-pointer is registered with the call:
+In the below, the module's per-architecture @emph{nozel} is added.  An
+architecture can specify its nozel by calling @code{set_gdbarch_nozel}
+from @code{gdbarch_init}.
 
 @smallexample
-void
-_initialize_nozel (void)
+static void *
+nozel_pre_init (struct obstack *obstack)
 @{
-  nozel_handle = register_gdbarch_data (nozel_init, nozel_free);
-@dots{}
+  struct nozel *data = OBSTACK_ZALLOC (obstack, struct nozel);
+  return data;
+@}
 @end smallexample
 
-The per-architecture data-pointer is accessed using the function:
-
-@deftypefun void *gdbarch_data (struct gdbarch *@var{gdbarch}, struct gdbarch_data *@var{data_handle})
-Given the architecture @var{arch} and module data handle
-@var{data_handle} (returned by @code{register_gdbarch_data}, this
-function returns the current value of the per-architecture data-pointer.
-@end deftypefun
-
-The non-@code{NULL} data-pointer returned by @code{gdbarch_data} should
-be saved in a local variable and then used directly:
-
 @smallexample
-int
-nozel_total (struct gdbarch *gdbarch)
+extern void
+set_gdbarch_nozel (struct gdbarch *gdbarch, int total)
 @{
-  int total;
   struct nozel *data = gdbarch_data (gdbarch, nozel_handle);
-  @dots{}
-  return total;
+  data->total = nozel;
 @}
 @end smallexample
 
-It is also possible to directly initialize the data-pointer using:
+A module can on-demand create architecture dependant data structures
+using @code{post_init}.
 
-@deftypefun void set_gdbarch_data (struct gdbarch *@var{gdbarch}, struct gdbarch_data *handle, void *@var{pointer})
-Update the data-pointer corresponding to @var{handle} with the value of
-@var{pointer}.  If the previous data-pointer value is non-NULL, then it
-is freed using data-pointers @var{free} function.
-@end deftypefun
-
-This function is used by modules that require a mechanism for explicitly
-setting the per-architecture data-pointer during architecture creation:
+In the below, the nozel's total is computed on-demand by
+@code{nozel_post_init} using information obtained from the
+architecture.
 
 @smallexample
-/* Called during architecture creation.  */
-extern void
-set_gdbarch_nozel (struct gdbarch *gdbarch,
-                   int total)
-@{
-  struct nozel *data = XMALLOC (struct nozel);
-  @dots{}
-  set_gdbarch_data (gdbarch, nozel_handle, nozel);
-@}
-@end smallexample
-
-@smallexample
-/* Default, called when nozel not set by set_gdbarch_nozel().  */
 static void *
-nozel_init (struct gdbarch *gdbarch)
+nozel_post_init (struct gdbarch *gdbarch)
 @{
-  struct nozel *default_nozel = XMALLOC (struc nozel);
-  @dots{}
-  return default_nozel;
+  struct nozel *data = GDBARCH_OBSTACK_ZALLOC (gdbarch, struct nozel);
+  nozel->total = gdbarch@dots{} (gdbarch);
+  return data;
 @}
 @end smallexample
 
 @smallexample
-void
-_initialize_nozel (void)
+extern int
+nozel_total (struct gdbarch *gdbarch)
 @{
-  nozel_handle = register_gdbarch_data (nozel_init, NULL);
-  @dots{}
+  struct nozel *data = gdbarch_data (gdbarch, nozel_handle);
+  return data->total;
+@}
 @end smallexample
 
-@noindent
-Note that an @code{init} function still needs to be registered.  It is
-used to initialize the data-pointer when the architecture creation phase
-fail to set an initial value.
-
-
 @section Wrapping Output Lines
 @cindex line wrap in output
 
@@ -5029,7 +4901,7 @@ allocation of small temporary values (such as strings).
 restrict the memory being allocated to no more than a few kilobytes.}
 
 @value{GDBN} uses the string function @code{xstrdup} and the print
-function @code{xasprintf}.
+function @code{xstrprintf}.
 
 @emph{Pragmatics: @code{asprintf} and @code{strdup} can fail.  Print
 functions such as @code{sprintf} are very prone to buffer overflow
@@ -5094,6 +4966,8 @@ switch (sched)
     break;
   @}
 @end smallexample
+
+@item -Wunused-function
 @end table
 
 @emph{Pragmatics: Due to the way that @value{GDBN} is implemented most
@@ -6408,6 +6282,15 @@ difficult to test, such as code that handles host OS failures or bugs
 in particular versions of compilers, and it's OK not to try to write
 tests for all of those.
 
+DejaGNU supports separate build, host, and target machines.  However,
+some @value{GDBN} test scripts do not work if the build machine and
+the host machine are not the same.  In such an environment, these scripts
+will give a result of ``UNRESOLVED'', like this:
+
+@smallexample
+UNRESOLVED: gdb.base/example.exp: This test script does not work on a remote host.
+@end smallexample
+
 @section Testsuite Organization
 
 @cindex test suite organization
@@ -6437,7 +6320,7 @@ intelligibility.
 This is the base testsuite.  The tests in it should apply to all
 configurations of @value{GDBN} (but generic native-only tests may live here).
 The test programs should be in the subset of C that is valid K&R,
-ANSI/ISO, and C++ (@code{#ifdef}s are allowed if necessary, for instance
+ANSI/ISO, and C@t{++} (@code{#ifdef}s are allowed if necessary, for instance
 for prototypes).
 
 @item gdb.@var{lang}
@@ -6693,7 +6576,9 @@ is so old that it has never been converted to use BFD.  Now that's old!
 @end table
 
 @include observer.texi
+@raisesections
 @include fdl.texi
+@lowersections
 
 @node Index
 @unnumbered Index
This page took 0.034951 seconds and 4 git commands to generate.