aboutsummaryrefslogtreecommitdiff
path: root/gdb/doc
diff options
context:
space:
mode:
authorElena Zannoni <ezannoni@kwikemart.cygnus.com>2004-02-11 15:11:35 +0000
committerElena Zannoni <ezannoni@kwikemart.cygnus.com>2004-02-11 15:11:35 +0000
commit1eb288ea7392802d39a8db01a3b39682c29d0432 (patch)
treec98cc5beb5853200d4cbae6ecb07c5683bfb3a20 /gdb/doc
parent6e19e2bf780e173c5a8c6fc5cec11d8fb8218f26 (diff)
downloadgdb-1eb288ea7392802d39a8db01a3b39682c29d0432.zip
gdb-1eb288ea7392802d39a8db01a3b39682c29d0432.tar.gz
gdb-1eb288ea7392802d39a8db01a3b39682c29d0432.tar.bz2
2004-02-11 Elena Zannoni <ezannoni@redhat.com>
* gdbint.texinfo (Support Libraries): Add doco about obstacks and minimal information about libiberty.
Diffstat (limited to 'gdb/doc')
-rw-r--r--gdb/doc/ChangeLog5
-rw-r--r--gdb/doc/gdbint.texinfo60
2 files changed, 65 insertions, 0 deletions
diff --git a/gdb/doc/ChangeLog b/gdb/doc/ChangeLog
index 6516237..9ac981c 100644
--- a/gdb/doc/ChangeLog
+++ b/gdb/doc/ChangeLog
@@ -1,3 +1,8 @@
+2004-02-11 Elena Zannoni <ezannoni@redhat.com>
+
+ * gdbint.texinfo (Support Libraries): Add doco about obstacks and
+ minimal information about libiberty.
+
2004-02-06 Michael Chastain <mec.gnu@mindspring.com>
* gdb.texinfo (Auxiliary Vector): Fix thinko with @value{GDBN}.
diff --git a/gdb/doc/gdbint.texinfo b/gdb/doc/gdbint.texinfo
index 081f999..9472c03 100644
--- a/gdb/doc/gdbint.texinfo
+++ b/gdb/doc/gdbint.texinfo
@@ -4678,6 +4678,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