diff options
author | Andrew Cagney <cagney@redhat.com> | 2002-03-19 02:49:53 +0000 |
---|---|---|
committer | Andrew Cagney <cagney@redhat.com> | 2002-03-19 02:49:53 +0000 |
commit | 474c824023f17af87cf6632bf1e863157970e1ea (patch) | |
tree | e2e4caecaa4880a03546d590170d6c3fc302c830 /gdb/doc | |
parent | 7d0766f3c30e00dd87a789de68e93eb1df8f24da (diff) | |
download | gdb-474c824023f17af87cf6632bf1e863157970e1ea.zip gdb-474c824023f17af87cf6632bf1e863157970e1ea.tar.gz gdb-474c824023f17af87cf6632bf1e863157970e1ea.tar.bz2 |
s/@example/@smallexample/
Diffstat (limited to 'gdb/doc')
-rw-r--r-- | gdb/doc/ChangeLog | 5 | ||||
-rw-r--r-- | gdb/doc/gdb.texinfo | 512 | ||||
-rw-r--r-- | gdb/doc/gdbint.texinfo | 182 |
3 files changed, 352 insertions, 347 deletions
diff --git a/gdb/doc/ChangeLog b/gdb/doc/ChangeLog index 73951d7..d7165c1 100644 --- a/gdb/doc/ChangeLog +++ b/gdb/doc/ChangeLog @@ -1,5 +1,10 @@ 2002-03-18 Andrew Cagney <ac131313@redhat.com> + * gdb.texinfo: Change all examples to @smallexample. + * gdbint.texinfo: Ditto. + +2002-03-18 Andrew Cagney <ac131313@redhat.com> + * gdbint.texinfo (Releasing GDB): Add section ``Versions and Branches''. diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo index e7d20a2..147bdd1 100644 --- a/gdb/doc/gdb.texinfo +++ b/gdb/doc/gdb.texinfo @@ -767,24 +767,24 @@ options may effectively be unavailable. The most usual way to start @value{GDBN} is with one argument, specifying an executable program: -@example +@smallexample @value{GDBP} @var{program} -@end example +@end smallexample @noindent You can also start with both an executable program and a core file specified: -@example +@smallexample @value{GDBP} @var{program} @var{core} -@end example +@end smallexample You can, instead, specify a process ID as a second argument, if you want to debug a running process: -@example +@smallexample @value{GDBP} @var{program} 1234 -@end example +@end smallexample @noindent would attach @value{GDBN} to process @code{1234} (unless you also have a file @@ -799,9 +799,9 @@ will warn you if it is unable to attach or to read core dumps. You can optionally have @code{@value{GDBP}} pass any arguments after the executable file to the inferior using @code{--args}. This option stops option processing. -@example +@smallexample gdb --args gcc -O2 -c foo.c -@end example +@end smallexample This will cause @code{@value{GDBP}} to debug @code{gcc}, and to set @code{gcc}'s command-line arguments (@pxref{Arguments}) to @samp{-O2 -c foo.c}. @@ -819,9 +819,9 @@ options. @value{GDBN} itself can remind you of the options available. @noindent Type -@example +@smallexample @value{GDBP} -help -@end example +@end smallexample @noindent to display all available options and briefly describe their use @@ -950,9 +950,9 @@ information. (@xref{Files,,Commands to specify files}, for information on @file{.syms} files.) A simple @value{GDBN} invocation to do nothing but build a @file{.syms} file for future use is: -@example +@smallexample gdb -batch -nx -mapped -readnow programname -@end example +@end smallexample @node Mode Options @subsection Choosing modes @@ -991,9 +991,9 @@ Batch mode may be useful for running @value{GDBN} as a filter, for example to download and run a program on another computer; in order to make this more useful, the message -@example +@smallexample Program exited normally. -@end example +@end smallexample @noindent (which is ordinarily issued whenever a program running under @@ -1283,17 +1283,17 @@ enter it). For example, if you type @c complete accuracy in these examples; space introduced for clarity. @c If texinfo enhancements make it unnecessary, it would be nice to @c replace " @key" by "@key" in the following... -@example +@smallexample (@value{GDBP}) info bre @key{TAB} -@end example +@end smallexample @noindent @value{GDBN} fills in the rest of the word @samp{breakpoints}, since that is the only @code{info} subcommand beginning with @samp{bre}: -@example +@smallexample (@value{GDBP}) info breakpoints -@end example +@end smallexample @noindent You can either press @key{RET} at this point, to run the @code{info @@ -1313,7 +1313,7 @@ just sounds the bell. Typing @key{TAB} again displays all the function names in your program that begin with those characters, for example: -@example +@smallexample (@value{GDBP}) b make_ @key{TAB} @exdent @value{GDBN} sounds bell; press @key{TAB} again, to see: make_a_section_from_file make_environ @@ -1322,7 +1322,7 @@ make_blockvector make_pointer_type make_cleanup make_reference_type make_command make_symbol_completion_list (@value{GDBP}) b make_ -@end example +@end smallexample @noindent After displaying the available possibilities, @value{GDBN} copies your @@ -1355,22 +1355,22 @@ word-completion facilities in this situation, type a single quote @value{GDBN} that it may need to consider more information than usual when you press @key{TAB} or @kbd{M-?} to request word completion: -@example +@smallexample (@value{GDBP}) b 'bubble( @kbd{M-?} bubble(double,double) bubble(int,int) (@value{GDBP}) b 'bubble( -@end example +@end smallexample In some cases, @value{GDBN} can tell that completing a name requires using quotes. When this happens, @value{GDBN} inserts the quote for you (while completing as much as it can) if you do not type the quote in the first place: -@example +@smallexample (@value{GDBP}) b bub @key{TAB} @exdent @value{GDBN} alters your input line to the following, and rings a bell: (@value{GDBP}) b 'bubble( -@end example +@end smallexample @noindent In general, @value{GDBN} can tell that a quote is needed (and inserts it) if @@ -1806,9 +1806,9 @@ null value. For example, this command: -@example +@smallexample set env USER = foo -@end example +@end smallexample @noindent tells the debugged program, when subsequently run, that its user is named @@ -1879,9 +1879,9 @@ program is using. You can redirect your program's input and/or output using shell redirection with the @code{run} command. For example, -@example +@smallexample run > outfile -@end example +@end smallexample @noindent starts your program, diverting its output to the file @file{outfile}. @@ -1894,9 +1894,9 @@ argument, and causes this file to be the default for future @code{run} commands. It also resets the controlling terminal for the child process, for future @code{run} commands. For example, -@example +@smallexample tty /dev/ttyb -@end example +@end smallexample @noindent directs that processes started with subsequent @code{run} commands @@ -2055,9 +2055,9 @@ form @samp{[New @var{systag}]}. @var{systag} is a thread identifier whose form varies depending on the particular system. For example, on LynxOS, you might see -@example +@smallexample [New process 35 thread 27] -@end example +@end smallexample @noindent when @value{GDBN} notices a new thread. In contrast, on an SGI system, @@ -2126,9 +2126,9 @@ form @samp{[New @var{systag}]}. @var{systag} is a thread identifier whose form varies depending on the particular system. For example, on HP-UX, you see -@example +@smallexample [New thread 2 (system thread 26594)] -@end example +@end smallexample @noindent when @value{GDBN} notices a new thread. @@ -2155,7 +2155,7 @@ For example, @end table @c end table here to get a little more width for example -@example +@smallexample (@value{GDBP}) info threads * 3 system thread 26607 worker (wptr=0x7b09c318 "@@") \@* at quicksort.c:137 @@ -2163,7 +2163,7 @@ For example, from /usr/lib/libc.2 1 system thread 27905 0x7b003498 in _brk () \@* from /usr/lib/libc.2 -@end example +@end smallexample @table @code @kindex thread @var{threadno} @@ -2639,9 +2639,9 @@ statement, not the instruction, after the change occurs. When you issue the @code{watch} command, @value{GDBN} reports -@example +@smallexample Hardware watchpoint @var{num}: @var{expr} -@end example +@end smallexample @noindent if it was able to set a hardware watchpoint. @@ -2820,11 +2820,11 @@ knowledge of the implementation. In the case of @sc{gnu} C@t{++}, exceptions ar raised by calling a library function named @code{__raise_exception} which has the following ANSI C interface: -@example +@smallexample /* @var{addr} is where the exception identifier is stored. @var{id} is the exception identifier. */ void __raise_exception (void **addr, void *id); -@end example +@end smallexample @noindent To make the debugger catch all exceptions before any stack @@ -3017,9 +3017,9 @@ referents in the context of your breakpoint. If @var{expression} uses symbols not referenced in the context of the breakpoint, @value{GDBN} prints an error message: -@example +@smallexample No symbol "foo" in current context. -@end example +@end smallexample @noindent @value{GDBN} does @@ -3128,14 +3128,14 @@ breakpoints. @xref{Output, ,Commands for controlled output}. For example, here is how you could use breakpoint commands to print the value of @code{x} at entry to @code{foo} whenever @code{x} is positive. -@example +@smallexample break foo if x>0 commands silent printf "x is %d\n",x cont end -@end example +@end smallexample One application for breakpoint commands is to compensate for one bug so you can test for another. Put a breakpoint just after the erroneous line @@ -3145,14 +3145,14 @@ to any variables that need them. End with the @code{continue} command so that your program does not stop, and start with the @code{silent} command so that no output is produced. Here is an example: -@example +@smallexample break 403 commands silent set x = y + 4 cont end -@end example +@end smallexample @node Breakpoint Menus @subsection Breakpoint menus @@ -3211,10 +3211,10 @@ any other process is running that program. In this situation, attempting to run or continue a program with a breakpoint causes @value{GDBN} to print an error message: -@example +@smallexample Cannot insert breakpoints. The same program may be running in another process. -@end example +@end smallexample When this happens, you have three ways to proceed: @@ -3419,13 +3419,13 @@ example, in the following excerpt from a debugging session, the @code{f} (@code{frame}) command shows that execution is stopped at line @code{206}; yet when we use @code{until}, we get to line @code{195}: -@example +@smallexample (@value{GDBP}) f #0 main (argc=4, argv=0xf7fffae8) at m4.c:206 206 expand_input(); (@value{GDBP}) until 195 for ( ; argc > 0; NEXTARG) @{ -@end example +@end smallexample This happened because, for execution efficiency, the compiler had generated code for the loop closure test at the end, rather than the @@ -3747,9 +3747,9 @@ frames in @value{GDBN} commands. @cindex frameless execution Some compilers provide a way to compile functions so that they operate without stack frames. (For example, the @value{GCC} option -@example +@smallexample @samp{-fomit-frame-pointer} -@end example +@end smallexample generates functions without a frame.) This is occasionally done with heavily used library functions to save the frame setup time. @value{GDBN} has limited facilities for dealing @@ -4483,7 +4483,7 @@ programming language from the point of execution in that frame @noindent This means that in the function -@example +@smallexample foo (a) int a; @{ @@ -4493,7 +4493,7 @@ foo (a) bar (b); @} @} -@end example +@end smallexample @noindent you can examine and use the variable @code{a} whenever your program is @@ -4515,10 +4515,10 @@ using the colon-colon notation: @c info cannot cope with a :: index entry, but why deprive hard copy readers? @cindex @code{::}, context for variables/functions @end iftex -@example +@smallexample @var{file}::@var{variable} @var{function}::@var{variable} -@end example +@end smallexample @noindent Here @var{file} or @var{function} is the name of the context for the @@ -4526,9 +4526,9 @@ static @var{variable}. In the case of file names, you can use quotes to make sure @value{GDBN} parses the file name as a single word---for example, to print a global value of @code{x} defined in @file{f2.c}: -@example +@smallexample (@value{GDBP}) p 'f2.c'::x -@end example +@end smallexample @cindex C@t{++} scope resolution This use of @samp{::} is very rarely in conflict with the very similar @@ -4565,9 +4565,9 @@ offered by the debug info format used by the compiler, @value{GDBN} might not be able to display values for such local variables. If that happens, @value{GDBN} will print a message like this: -@example +@smallexample No symbol "foo" in current context. -@end example +@end smallexample To solve such problems, either recompile without optimizations, or use a different debug info format, if the compiler supports several such @@ -4600,16 +4600,16 @@ argument; the second element comes from bytes of memory immediately following those that hold the first element, and so on. Here is an example. If a program says -@example +@smallexample int *array = (int *) malloc (len * sizeof (int)); -@end example +@end smallexample @noindent you can print the contents of @code{array} with -@example +@smallexample p *array@@len -@end example +@end smallexample The left operand of @samp{@@} must reside in memory. Array values made with @samp{@@} in this way behave just like other arrays in terms of @@ -4620,18 +4620,18 @@ Artificial arrays most often appear in expressions via the value history Another way to create an artificial array is to use a cast. This re-interprets a value as if it were an array. The value need not be in memory: -@example +@smallexample (@value{GDBP}) p/x (short[2])0x12345678 $1 = @{0x1234, 0x5678@} -@end example +@end smallexample As a convenience, if you leave the array length out (as in @samp{(@var{type}[])@var{value}}) @value{GDBN} calculates the size to fill the value (as @samp{sizeof(@var{value})/sizeof(@var{type})}: -@example +@smallexample (@value{GDBP}) p/x (short[])0x12345678 $2 = @{0x1234, 0x5678@} -@end example +@end smallexample Sometimes the artificial array mechanism is not quite enough; in moderately complex data structures, the elements of interest may not @@ -4644,13 +4644,13 @@ instance, suppose you have an array @code{dtab} of pointers to structures, and you are interested in the values of a field @code{fv} in each structure. Here is an example of what you might type: -@example +@smallexample set $i = 0 p dtab[$i++]->fv @key{RET} @key{RET} @dots{} -@end example +@end smallexample @node Output Formats @section Output formats @@ -4695,10 +4695,10 @@ Print as an address, both absolute in hexadecimal and as an offset from the nearest preceding symbol. You can use this format used to discover where (in what function) an unknown address is located: -@example +@smallexample (@value{GDBP}) p/a 0x54320 $3 = 0x54320 <_initialize_vx+396> -@end example +@end smallexample @noindent The command @code{info symbol 0x54320} yields similar results. @@ -4714,9 +4714,9 @@ using typical floating point syntax. For example, to print the program counter in hex (@pxref{Registers}), type -@example +@smallexample p/x $pc -@end example +@end smallexample @noindent Note that no space is required before the slash; this is because command @@ -4843,10 +4843,10 @@ Each expression added to the list is given a number to identify it; to remove an expression from the list, you specify that number. The automatic display looks like this: -@example +@smallexample 2: foo = 38 3: bar[5] = (struct hack *) 0x3804 -@end example +@end smallexample @noindent This display shows item numbers, expressions and their current values. As with @@ -5034,11 +5034,11 @@ and source file location of the variable where it points, using For example, here @value{GDBN} shows that a variable @code{ptt} points at another variable @code{t}, defined in @file{hi2.c}: -@example +@smallexample (@value{GDBP}) set print symbol-filename on (@value{GDBP}) p/a ptt $4 = 0xe008 <t in hi2.c> -@end example +@end smallexample @quotation @emph{Warning:} For pointers that point to a local variable, @samp{p/a} @@ -5320,16 +5320,16 @@ is the value just prior to @code{$$}, @code{$$1} is equivalent to For example, suppose you have just printed a pointer to a structure and want to see the contents of the structure. It suffices to type -@example +@smallexample p *$ -@end example +@end smallexample If you have a chain of structures where the component @code{next} points to the next one, you can print the contents of the next one with this: -@example +@smallexample p *$.next -@end example +@end smallexample @noindent You can print successive links in the chain by repeating this @@ -5338,10 +5338,10 @@ command---which you can do by just typing @key{RET}. Note that the history records values, not expressions. If the value of @code{x} is 4 and you type these commands: -@example +@smallexample print x set x=5 -@end example +@end smallexample @noindent then the value recorded in the value history by the @code{print} command @@ -5385,9 +5385,9 @@ You can save a value in a convenience variable with an assignment expression, just as you would set a variable in your program. For example: -@example +@smallexample set $foo = *object_ptr -@end example +@end smallexample @noindent would save in @code{$foo} the value contained in the object pointed to by @@ -5413,10 +5413,10 @@ One of the ways to use a convenience variable is as a counter to be incremented or a pointer to be advanced. For example, to print a field from successive elements of an array of structures: -@example +@smallexample set $i = 0 print bar[$i++]->contents -@end example +@end smallexample @noindent Repeat that command by typing @key{RET}. @@ -5488,16 +5488,16 @@ pointer to the current stack frame, and @code{$ps} is used for a register that contains the processor status. For example, you could print the program counter in hex with -@example +@smallexample p/x $pc -@end example +@end smallexample @noindent or print the instruction to be executed next with -@example +@smallexample x/i $pc -@end example +@end smallexample @noindent or add four to the stack pointer@footnote{This is a way of removing @@ -5508,9 +5508,9 @@ stack frames are selected. To pop entire frames off the stack, regardless of machine architecture, use @code{return}; see @ref{Returning, ,Returning from a function}.} with -@example +@smallexample set $sp += 4 -@end example +@end smallexample Whenever possible, these four standard register names are available on your machine even though the machine has different canonical mnemonics, @@ -6368,7 +6368,7 @@ there. @c size of all overlays. This is intentional to remind the developer @c that overlays don't necessarily need to be the same size. -@example +@smallexample @group Data Instruction Larger Address Space Address Space Address Space @@ -6396,7 +6396,7 @@ Address Space Address Space Address Space @anchor{A code overlay}A code overlay @end group -@end example +@end smallexample The diagram (@pxref{A code overlay}) shows a system with separate data and instruction address spaces. To map an overlay, the program copies @@ -6553,33 +6553,33 @@ addresses, load addresses, and sizes. Normally, when @value{GDBN} prints a code address, it includes the name of the function the address falls in: -@example +@smallexample (gdb) print main $3 = @{int ()@} 0x11a0 <main> -@end example +@end smallexample @noindent When overlay debugging is enabled, @value{GDBN} recognizes code in unmapped overlays, and prints the names of unmapped functions with asterisks around them. For example, if @code{foo} is a function in an unmapped overlay, @value{GDBN} prints it this way: -@example +@smallexample (gdb) overlay list No sections are mapped. (gdb) print foo $5 = @{int (int)@} 0x100000 <*foo*> -@end example +@end smallexample @noindent When @code{foo}'s overlay is mapped, @value{GDBN} prints the function's name normally: -@example +@smallexample (gdb) overlay list Section .ov.foo.text, loaded at 0x100000 - 0x100034, mapped at 0x1016 - 0x104a (gdb) print foo $6 = @{int (int)@} 0x1016 <foo> -@end example +@end smallexample When overlay debugging is enabled, @value{GDBN} can find the correct address for functions and variables in an overlay, whether or not the @@ -6621,7 +6621,7 @@ Here are the variables your overlay manager must define to support @item @code{_ovly_table}: This variable must be an array of the following structures: -@example +@smallexample struct @{ /* The overlay's mapped address. */ @@ -6637,7 +6637,7 @@ struct zero otherwise. */ unsigned long mapped; @} -@end example +@end smallexample @item @code{_novlys}: This variable must be a four-byte signed integer, holding the total @@ -6698,7 +6698,7 @@ and @code{m32r-elf} targets. You can build the test program using the @code{d10v-elf} GCC cross-compiler like this: -@example +@smallexample $ d10v-elf-gcc -g -c overlays.c $ d10v-elf-gcc -g -c ovlymgr.c $ d10v-elf-gcc -g -c foo.c @@ -6707,7 +6707,7 @@ $ d10v-elf-gcc -g -c baz.c $ d10v-elf-gcc -g -c grbx.c $ d10v-elf-gcc -g overlays.o ovlymgr.o foo.o bar.o \ baz.o grbx.o -Wl,-Td10v.ld -o overlays -@end example +@end smallexample The build process is identical for any other architecture, except that you must substitute the appropriate compiler and linker script for the @@ -6836,9 +6836,9 @@ languages---but means different things. For instance, if the current source file were written in C, and @value{GDBN} was parsing Modula-2, a command such as: -@example +@smallexample print a = b + c -@end example +@end smallexample @noindent might not have the effect you intended. In C, this means to add @@ -7032,9 +7032,9 @@ error. In many implementations of C, mathematical overflow causes the result to ``wrap around'' to lower values---for example, if @var{m} is the largest integer value, and @var{s} is the smallest, then -@example +@smallexample @var{m} + 1 @result{} @var{s} -@end example +@end smallexample This, too, is specific to individual languages, and in some cases specific to individual compilers or machines. @xref{Support, , @@ -7394,9 +7394,9 @@ support in @value{GDBN} does @emph{not} work. @item Member function calls are allowed; you can use expressions like -@example +@smallexample count = aml->GetOriginal(x, y) -@end example +@end smallexample @vindex this@r{, inside C@t{++} member functions} @cindex namespace in C@t{++} @@ -8014,11 +8014,11 @@ There are a few subtle differences between the Modula-2 scope operator (@code{.}) and the @value{GDBN} scope operator (@code{::}). The two have similar syntax: -@example +@smallexample @var{module} . @var{id} @var{scope} :: @var{id} -@end example +@end smallexample @noindent where @var{scope} is the name of a module or a procedure, @@ -8580,9 +8580,9 @@ ordinarily parse a typical file name, like @file{foo.c}, as the three words @samp{foo} @samp{.} @samp{c}. To allow @value{GDBN} to recognize @samp{foo.c} as a single symbol, enclose it in single quotes; for example, -@example +@smallexample p 'foo.c'::x -@end example +@end smallexample @noindent looks up the value of @code{x} in the scope of the file @file{foo.c}. @@ -8607,10 +8607,10 @@ Print the name of a symbol which is stored at the address @var{addr}. If no symbol is stored exactly at @var{addr}, @value{GDBN} prints the nearest symbol and an offset from it: -@example +@smallexample (@value{GDBP}) info symbol 0x54320 _initialize_vx + 396 in section .text -@end example +@end smallexample @noindent This is the opposite of the @code{info address} command. You can use @@ -8641,14 +8641,14 @@ of just the name of the type. For example, for this variable declaration: -@example +@smallexample struct complex @{double real; double imag;@} v; -@end example +@end smallexample @noindent the two commands give this output: -@example +@smallexample @group (@value{GDBP}) whatis v type = struct complex @@ -8658,7 +8658,7 @@ type = struct complex @{ double imag; @} @end group -@end example +@end smallexample @noindent As with @code{whatis}, using @code{ptype} without an argument refers to @@ -8854,9 +8854,9 @@ address, or even return prematurely from a function. To alter the value of a variable, evaluate an assignment expression. @xref{Expressions, ,Expressions}. For example, -@example +@smallexample print x=4 -@end example +@end smallexample @noindent stores the value 4 into the variable @code{x}, and then prints the @@ -8880,22 +8880,22 @@ program has a variable @code{width}, you get an error if you try to set a new value with just @samp{set width=13}, because @value{GDBN} has the command @code{set width}: -@example +@smallexample (@value{GDBP}) whatis width type = double (@value{GDBP}) p width $4 = 13 (@value{GDBP}) set width=47 Invalid syntax in expression. -@end example +@end smallexample @noindent The invalid expression, of course, is @samp{=47}. In order to actually set the program's variable @code{width}, use -@example +@smallexample (@value{GDBP}) set var width=47 -@end example +@end smallexample Because the @code{set} command has many subcommands that can conflict with the names of program variables, it is a good idea to use the @@ -8904,7 +8904,7 @@ your program has a variable @code{g}, you run into problems if you try to set a new value with just @samp{set g=4}, because @value{GDBN} has the command @code{set gnutarget}, abbreviated @code{set g}: -@example +@smallexample @group (@value{GDBP}) whatis g type = double @@ -8922,16 +8922,16 @@ Starting program: /home/smith/cc_progs/a.out (@value{GDBP}) show g The current BFD target is "=4". @end group -@end example +@end smallexample @noindent The program variable @code{g} did not change, and you silently set the @code{gnutarget} to an invalid value. In order to set the variable @code{g}, use -@example +@smallexample (@value{GDBP}) set var g=4 -@end example +@end smallexample @value{GDBN} allows more implicit conversions in assignments than C; you can freely store an integer value into a pointer variable or vice versa, @@ -8946,9 +8946,9 @@ construct to generate a value of specified type at a specified address to memory location @code{0x83040} as an integer (which implies a certain size and representation in memory), and -@example +@smallexample set @{int@}0x83040 = 4 -@end example +@end smallexample @noindent stores the value 4 into that memory location. @@ -8991,9 +8991,9 @@ difference is that this does not start your program running; it only changes the address of where it @emph{will} run when you continue. For example, -@example +@smallexample set $pc = 0x485 -@end example +@end smallexample @noindent makes the next @code{continue} command or stepping command execute at @@ -9765,11 +9765,11 @@ it somewhere in memory where it won't get clobbered by the download. @item target sim Builtin CPU simulator. @value{GDBN} includes simulators for most architectures. In general, -@example +@smallexample target sim load run -@end example +@end smallexample @noindent works; however, you cannot assume that a specific memory map, device drivers, or even basic I/O is available, although some simulators do @@ -9891,21 +9891,21 @@ displayed is determined on a per-OS basis. Use the @code{set os} command to set the operating system. This tells @value{GDBN} which kernel object display module to initialize: -@example +@smallexample (@value{GDBP}) set os cisco -@end example +@end smallexample If @code{set os} succeeds, @value{GDBN} will display some information about the operating system, and will create a new @code{info} command which can be used to query the target. The @code{info} command is named after the operating system: -@example +@smallexample (@value{GDBP}) info cisco List of Cisco Kernel Objects Object Description any Any and all objects -@end example +@end smallexample Further subcommands can be used to query about particular objects known by the kernel. @@ -10359,18 +10359,18 @@ Make sure you have defined the supporting low-level routines @item Insert these lines near the top of your program: -@example +@smallexample set_debug_traps(); breakpoint(); -@end example +@end smallexample @item For the 680x0 stub only, you need to provide a variable called @code{exceptionHook}. Normally you just use: -@example +@smallexample void (*exceptionHook)() = 0; -@end example +@end smallexample @noindent but if before calling @code{set_debug_traps}, you set it to point to a @@ -10408,27 +10408,27 @@ TCP port (usually to a terminal server which in turn has a serial line to the target). For example, to use a serial line connected to the device named @file{/dev/ttyb}: -@example +@smallexample target remote /dev/ttyb -@end example +@end smallexample @cindex TCP port, @code{target remote} To use a TCP connection, use an argument of the form @code{@var{host}:port}. For example, to connect to port 2828 on a terminal server named @code{manyfarms}: -@example +@smallexample target remote manyfarms:2828 -@end example +@end smallexample If your remote target is actually running on the same machine as your debugger session (e.g.@: a simulator of your target running on the same host), you can omit the hostname. For example, to connect to port 1234 on your local machine: -@example +@smallexample target remote :1234 -@end example +@end smallexample @noindent Note that the colon is still required here. @@ -10448,10 +10448,10 @@ program. This may or may not succeed, depending in part on the hardware and the serial drivers the remote system uses. If you type the interrupt character once again, @value{GDBN} displays this prompt: -@example +@smallexample Interrupted while waiting for the program. Give up (and stop debugging it)? (y or n) -@end example +@end smallexample If you type @kbd{y}, @value{GDBN} abandons the remote debugging session. (If you decide you want to try again later, you can use @samp{target @@ -10845,9 +10845,9 @@ run @value{GDBN}. From your Unix host, run @code{@value{GDBP}} (or @value{GDBN} comes up showing the prompt: -@example +@smallexample (vxgdb) -@end example +@end smallexample @menu * VxWorks Connection:: Connecting to VxWorks @@ -10861,9 +10861,9 @@ run @value{GDBN}. From your Unix host, run @code{@value{GDBP}} (or The @value{GDBN} command @code{target} lets you connect to a VxWorks target on the network. To connect to a target whose host name is ``@code{tt}'', type: -@example +@smallexample (vxgdb) target vxworks tt -@end example +@end smallexample @need 750 @value{GDBN} displays messages like these: @@ -10880,9 +10880,9 @@ these files by searching the directories listed in the command search path (@pxref{Environment, ,Your program's environment}); if it fails to find an object file, it displays a message such as: -@example +@smallexample prog.o: No such file or directory. -@end example +@end smallexample When this happens, add the appropriate directory to the search path with the @value{GDBN} command @code{path}, and execute the @code{target} @@ -10908,17 +10908,17 @@ the file by its name, without any path. For instance, a program and in @file{@var{hostpath}/vw/demo/rdb} on the host. To load this program, type this on VxWorks: -@example +@smallexample -> cd "@var{vxpath}/vw/demo/rdb" -@end example +@end smallexample @noindent Then, in @value{GDBN}, type: -@example +@smallexample (vxgdb) cd @var{hostpath}/vw/demo/rdb (vxgdb) load prog.o -@end example +@end smallexample @value{GDBN} displays a response similar to this: @@ -10941,9 +10941,9 @@ table.) You can also attach to an existing task using the @code{attach} command as follows: -@example +@smallexample (vxgdb) attach @var{task} -@end example +@end smallexample @noindent where @var{task} is the VxWorks hexadecimal task ID. The task can be running @@ -11049,9 +11049,9 @@ configurations. @c OBSOLETE The next step is to set up the PC's port, by doing something like this @c OBSOLETE in DOS on the PC: @c OBSOLETE -@c OBSOLETE @example +@c OBSOLETE @smallexample @c OBSOLETE C:\> MODE com1:9600,n,8,1,none -@c OBSOLETE @end example +@c OBSOLETE @end smallexample @c OBSOLETE @c OBSOLETE @noindent @c OBSOLETE This example---run on an MS DOS 4.0 system---sets the PC port to 9600 @@ -11070,9 +11070,9 @@ configurations. @c OBSOLETE To give control of the PC to the Unix side of the serial line, type @c OBSOLETE the following at the DOS console: @c OBSOLETE -@c OBSOLETE @example +@c OBSOLETE @smallexample @c OBSOLETE C:\> CTTY com1 -@c OBSOLETE @end example +@c OBSOLETE @end smallexample @c OBSOLETE @c OBSOLETE @noindent @c OBSOLETE (Later, if you wish to return control to the DOS console, you can use @@ -11082,18 +11082,18 @@ configurations. @c OBSOLETE From the Unix host, use a communications program such as @code{tip} or @c OBSOLETE @code{cu} to communicate with the PC; for example, @c OBSOLETE -@c OBSOLETE @example +@c OBSOLETE @smallexample @c OBSOLETE cu -s 9600 -l /dev/ttya -@c OBSOLETE @end example +@c OBSOLETE @end smallexample @c OBSOLETE @c OBSOLETE @noindent @c OBSOLETE The @code{cu} options shown specify, respectively, the linespeed and the @c OBSOLETE serial port to use. If you use @code{tip} instead, your command line @c OBSOLETE may look something like the following: @c OBSOLETE -@c OBSOLETE @example +@c OBSOLETE @smallexample @c OBSOLETE tip -9600 /dev/ttya -@c OBSOLETE @end example +@c OBSOLETE @end smallexample @c OBSOLETE @c OBSOLETE @noindent @c OBSOLETE Your system may require a different name where we show @@ -11121,7 +11121,7 @@ configurations. @c OBSOLETE @code{EBMON} similar to the one that follows, ending with the @c OBSOLETE @code{EBMON} prompt @samp{#}--- @c OBSOLETE -@c OBSOLETE @example +@c OBSOLETE @smallexample @c OBSOLETE C:\> G: @c OBSOLETE @c OBSOLETE G:\> CD \usr\joe\work29k @@ -11150,7 +11150,7 @@ configurations. @c OBSOLETE Byte Write Available = Yes @c OBSOLETE @c OBSOLETE # ~. -@c OBSOLETE @end example +@c OBSOLETE @end smallexample @c OBSOLETE @c OBSOLETE Then exit the @code{cu} or @code{tip} program (done in the example by @c OBSOLETE typing @code{~.} at the @code{EBMON} prompt). @code{EBMON} keeps @@ -11172,20 +11172,20 @@ configurations. @c OBSOLETE program on the Unix system, and start @value{GDBN}---specifying as argument the @c OBSOLETE name of your 29K program: @c OBSOLETE -@c OBSOLETE @example +@c OBSOLETE @smallexample @c OBSOLETE cd /usr/joe/work29k @c OBSOLETE @value{GDBP} myfoo -@c OBSOLETE @end example +@c OBSOLETE @end smallexample @c OBSOLETE @c OBSOLETE @need 500 @c OBSOLETE Now you can use the @code{target} command: @c OBSOLETE -@c OBSOLETE @example +@c OBSOLETE @smallexample @c OBSOLETE target amd-eb /dev/ttya 9600 MYFOO @c OBSOLETE @c FIXME: test above 'target amd-eb' as spelled, with caps! caps are meant to @c OBSOLETE @c emphasize that this is the name as seen by DOS (since I think DOS is @c OBSOLETE @c single-minded about case of letters). ---doc@cygnus.com, 25feb91 -@c OBSOLETE @end example +@c OBSOLETE @end smallexample @c OBSOLETE @c OBSOLETE @noindent @c OBSOLETE In this example, we've assumed your program is in a file called @@ -11335,7 +11335,7 @@ debugger, you give it just the numeric part of the serial port's name; for example, @samp{asyncstr 2} below runs @code{asyncstr} on @code{COM2}. -@example +@smallexample C:\H8300\TEST> asynctsr 2 C:\H8300\TEST> mode com2:9600,n,8,1,p @@ -11343,7 +11343,7 @@ Resident portion of MODE loaded COM2: 9600, n, 8, 1, p -@end example +@end smallexample @quotation @emph{Warning:} We have noticed a bug in PC-NFS that conflicts with @@ -11516,9 +11516,9 @@ If you simply start @code{@value{GDBP}} without using any command-line options, you are prompted for what serial port to use, @emph{before} you reach the ordinary @value{GDBN} prompt: -@example +@smallexample Attach /dev/ttyNN -- specify NN, or "quit" to quit: -@end example +@end smallexample @noindent Respond to the prompt with whatever suffix (after @samp{/dev/tty}) @@ -11681,13 +11681,13 @@ For example, this sequence connects to the target board through a serial port, and loads and runs a program called @var{prog} through the debugger: -@example +@smallexample host$ @value{GDBP} @var{prog} @value{GDBN} is free software and @dots{} (@value{GDBP}) target mips /dev/ttyb (@value{GDBP}) load @var{prog} (@value{GDBP}) run -@end example +@end smallexample @item target mips @var{hostname}:@var{portnumber} On some @value{GDBN} host configurations, you can specify a TCP @@ -11884,15 +11884,15 @@ information and @samp{-Ttext} to relocate the program to where you wish to load it on the target. You may also want to add the options @samp{-n} or @samp{-N} in order to reduce the size of the sections. Example: -@example +@smallexample sparclet-aout-gcc prog.c -Ttext 0x12010000 -g -o prog -N -@end example +@end smallexample You can use @code{objdump} to verify that the addresses are what you intended: -@example +@smallexample sparclet-aout-objdump --headers --syms prog -@end example +@end smallexample @cindex running, on Sparclet Once you have set @@ -11902,9 +11902,9 @@ run @value{GDBN}. From your Unix host, run @code{@value{GDBP}} @value{GDBN} comes up showing the prompt: -@example +@smallexample (gdbslet) -@end example +@end smallexample @menu * Sparclet File:: Setting the file to debug @@ -11918,9 +11918,9 @@ run @value{GDBN}. From your Unix host, run @code{@value{GDBP}} The @value{GDBN} command @code{file} lets you choose with program to debug. -@example +@smallexample (gdbslet) file prog -@end example +@end smallexample @need 1000 @value{GDBN} then attempts to read the symbol table of @file{prog}. @@ -11935,9 +11935,9 @@ path (@pxref{Environment, ,Your program's environment}). If it fails to find a file, it displays a message such as: -@example +@smallexample prog: No such file or directory. -@end example +@end smallexample When this happens, add the appropriate directories to the search paths with the @value{GDBN} commands @code{path} and @code{dir}, and execute the @@ -11949,18 +11949,18 @@ the @value{GDBN} commands @code{path} and @code{dir}, and execute the The @value{GDBN} command @code{target} lets you connect to a Sparclet target. To connect to a target on serial port ``@code{ttya}'', type: -@example +@smallexample (gdbslet) target sparclet /dev/ttya Remote target sparclet connected to /dev/ttya main () at ../prog.c:3 -@end example +@end smallexample @need 750 @value{GDBN} displays messages like these: -@example +@smallexample Connected to ttya. -@end example +@end smallexample @node Sparclet Download @subsubsection Sparclet download @@ -11979,10 +11979,10 @@ For instance, if the program @file{prog} was linked to text address 0x1201000, with data at 0x12010160 and bss at 0x12010170, in @value{GDBN}, type: -@example +@smallexample (gdbslet) load prog 0x12010000 Loading section .text, size 0xdb0 vma 0x12010000 -@end example +@end smallexample If the code is loaded at a different address then what the program was linked to, you may need to use the @code{section} and @code{add-symbol-file} commands @@ -11996,7 +11996,7 @@ You can now begin debugging the task using @value{GDBN}'s execution control commands, @code{b}, @code{step}, @code{run}, etc. See the @value{GDBN} manual for the list of commands. -@example +@smallexample (gdbslet) b main Breakpoint 1 at 0x12010000: file prog.c, line 3. (gdbslet) run @@ -12006,7 +12006,7 @@ Breakpoint 1, main (argc=1, argv=0xeffff21c) at prog.c:3 (gdbslet) step 4 char *execarg = "hello!"; (gdbslet) -@end example +@end smallexample @node Sparclite @subsection Fujitsu Sparclite @@ -12031,9 +12031,9 @@ STDBUG protocol. To connect your ST2000 to the host system, see the manufacturer's manual. Once the ST2000 is physically attached, you can run: -@example +@smallexample target st2000 @var{dev} @var{speed} -@end example +@end smallexample @noindent to establish it as your debugging environment. @var{dev} is normally @@ -12509,11 +12509,11 @@ By default, @value{GDBN} is cautious, and asks what sometimes seems to be a lot of stupid questions to confirm certain commands. For example, if you try to run a program which is already running: -@example +@smallexample (@value{GDBP}) run The program being debugged has been started already. Start it from the beginning? (y or n) -@end example +@end smallexample If you are willing to unflinchingly face the consequences of your own commands, you can disable this ``feature'': @@ -12753,7 +12753,7 @@ For example, to ignore @code{SIGALRM} signals while single-stepping, but treat them normally during normal execution, you could define: -@example +@smallexample define hook-stop handle SIGALRM nopass end @@ -12765,13 +12765,13 @@ end define hook-continue handle SIGLARM pass end -@end example +@end smallexample As a further example, to hook at the begining and end of the @code{echo} command, and to add extra text to the beginning and end of the message, you could define: -@example +@smallexample define hook-echo echo <<<--- end @@ -12784,7 +12784,7 @@ end <<<---Hello World--->>> (@value{GDBP}) -@end example +@end smallexample You can define a hook for any single-word command in @value{GDBN}, but not for command aliases; you should define a hook for the basic command @@ -12882,9 +12882,9 @@ standard error. Errors in a command file supplied on standard input do not terminate execution of the command file --- execution continues with the next command. -@example +@smallexample gdb < cmds > log 2>&1 -@end example +@end smallexample (The syntax above will vary depending on the shell used.) This example will execute commands from the file @file{cmds}. All output and errors @@ -12917,19 +12917,19 @@ To print @samp{@w{ }and foo =@w{ }}, use the command A backslash at the end of @var{text} can be used, as in C, to continue the command onto subsequent lines. For example, -@example +@smallexample echo This is some text\n\ which is continued\n\ onto several lines.\n -@end example +@end smallexample produces the same output as -@example +@smallexample echo This is some text\n echo which is continued\n echo onto several lines.\n -@end example +@end smallexample @kindex output @item output @var{expression} @@ -12955,9 +12955,9 @@ subroutine @c Either this is a bug, or the manual should document what formats are @c supported. -@example +@smallexample printf (@var{string}, @var{expressions}@dots{}); -@end example +@end smallexample For example, you can print two values in hex like this: @@ -13325,9 +13325,9 @@ you need to call @value{GDBN} by a different name (for example, if you keep several configurations around, with different names) you can set the Emacs variable @code{gdb-command-name}; for example, -@example +@smallexample (setq gdb-command-name "mygdb") -@end example +@end smallexample @noindent (preceded by @kbd{M-:} or @kbd{ESC :}, or typed in the @code{*scratch*} buffer, or @@ -13500,9 +13500,9 @@ distribution. In any event, we also recommend that you send bug reports for @value{GDBN} to this addresses: -@example +@smallexample bug-gdb@@gnu.org -@end example +@end smallexample @strong{Do not send bug reports to @samp{info-gdb}, or to @samp{help-gdb}, or to any newsgroups.} Most users of @value{GDBN} do @@ -13520,13 +13520,13 @@ bug reports to the mailing list. As a last resort, send bug reports on paper to: -@example +@smallexample @sc{gnu} Debugger Bugs Free Software Foundation Inc. 59 Temple Place - Suite 330 Boston, MA 02111-1307 USA -@end example +@end smallexample The fundamental principle of reporting bugs usefully is this: @strong{report all the facts}. If you are not sure whether to state a @@ -13691,9 +13691,9 @@ you can print the reference card immediately with @file{refcard.ps}. The release also includes the source for the reference card. You can format it, using @TeX{}, by typing: -@example +@smallexample make refcard.dvi -@end example +@end smallexample The @value{GDBN} reference card is designed to print in @dfn{landscape} mode on US ``letter'' size paper; @@ -13727,10 +13727,10 @@ If you have @code{makeinfo} installed, and are in the top level @value{GDBN} source directory (@file{gdb-@value{GDBVN}}, in the case of version @value{GDBVN}), you can make the Info file by typing: -@example +@smallexample cd gdb make gdb.info -@end example +@end smallexample If you want to typeset and print copies of this manual, you need @TeX{}, a program to print its @sc{dvi} output files, and @file{texinfo.tex}, the @@ -13756,9 +13756,9 @@ typeset and print this manual. First switch to the the @file{gdb} subdirectory of the main source directory (for example, to @file{gdb-@value{GDBVN}/gdb}) and type: -@example +@smallexample make gdb.dvi -@end example +@end smallexample Then give @file{gdb.dvi} to your @sc{dvi} printing program. @@ -13824,11 +13824,11 @@ argument. For example: -@example +@smallexample cd gdb-@value{GDBVN} ./configure @var{host} make -@end example +@end smallexample @noindent where @var{host} is an identifier such as @samp{sun4} or @@ -13846,9 +13846,9 @@ binaries, are left in the corresponding source directories. system does not recognize this automatically when you run a different shell, you may need to run @code{sh} on it explicitly: -@example +@smallexample sh configure @var{host} -@end example +@end smallexample If you run @code{configure} from a directory that contains source directories for multiple libraries or programs, such as the @@ -13863,12 +13863,12 @@ configure that subdirectory, but be sure to specify a path to it. For example, with version @value{GDBVN}, type the following to configure only the @code{bfd} subdirectory: -@example +@smallexample @group cd gdb-@value{GDBVN}/bfd ../configure @var{host} @end group -@end example +@end smallexample You can install @code{@value{GDBP}} anywhere; it has no hardwired paths. However, you should make sure that the shell on your path (named by @@ -13904,7 +13904,7 @@ the @samp{--srcdir} option; it is assumed.) For example, with version @value{GDBVN}, you can build @value{GDBN} in a separate directory for a Sun 4 like this: -@example +@smallexample @group cd gdb-@value{GDBVN} mkdir ../gdb-sun4 @@ -13912,7 +13912,7 @@ cd ../gdb-sun4 ../gdb-@value{GDBVN}/configure sun4 make @end group -@end example +@end smallexample When @code{configure} builds a configuration using a remote source directory, it creates a tree for the binaries with the same structure @@ -13951,9 +13951,9 @@ script are based on a three-part naming scheme, but some short predefined aliases are also supported. The full naming scheme encodes three pieces of information in the following pattern: -@example +@smallexample @var{architecture}-@var{vendor}-@var{os} -@end example +@end smallexample For example, you can use the alias @code{sun4} as a @var{host} argument, or as the value for @var{target} in a @code{--target=@var{target}} @@ -13993,7 +13993,7 @@ are most often useful for building @value{GDBN}. @code{configure} also has several other options not listed here. @inforef{What Configure Does,,configure.info}, for a full explanation of @code{configure}. -@example +@smallexample configure @r{[}--help@r{]} @r{[}--prefix=@var{dir}@r{]} @r{[}--exec-prefix=@var{dir}@r{]} @@ -14001,7 +14001,7 @@ configure @r{[}--help@r{]} @r{[}--norecursion@r{]} @r{[}--rm@r{]} @r{[}--target=@var{target}@r{]} @var{host} -@end example +@end smallexample @noindent You may introduce options with a single @samp{-} rather than @@ -14119,9 +14119,9 @@ sent as a @var{packet}. A @var{packet} is introduced with the character @samp{$}, the actual @var{packet-data}, and the terminating character @samp{#} followed by a two-digit @var{checksum}: -@example +@smallexample @code{$}@var{packet-data}@code{#}@var{checksum} -@end example +@end smallexample @noindent @cindex checksum, for @value{GDBN} remote @@ -14133,9 +14133,9 @@ eight bit unsigned checksum). Implementors should note that prior to @value{GDBN} 5.0 the protocol specification also included an optional two-digit @var{sequence-id}: -@example +@smallexample @code{$}@var{sequence-id}@code{:}@var{packet-data}@code{#}@var{checksum} -@end example +@end smallexample @cindex sequence-id, for @value{GDBN} remote @noindent @@ -14149,10 +14149,10 @@ response expected is an acknowledgment: either @samp{+} (to indicate the package was received correctly) or @samp{-} (to request retransmission): -@example +@smallexample <- @code{$}@var{packet-data}@code{#}@var{checksum} -> @code{+} -@end example +@end smallexample @noindent The host (@value{GDBN}) sends @var{command}s, and the target (the @@ -14185,9 +14185,9 @@ loosely refered to as the cisco encoding. Following the @samp{*} character are two hex digits that indicate the size of the packet. So: -@example +@smallexample "@code{0* }" -@end example +@end smallexample @noindent means the same as "0000". @@ -14923,7 +14923,7 @@ as @code{MIPS32}. Example sequence of a target being re-started. Notice how the restart does not get any direct output: -@example +@smallexample <- @code{R00} -> @code{+} @emph{target restarts} @@ -14931,11 +14931,11 @@ does not get any direct output: -> @code{+} -> @code{T001:1234123412341234} <- @code{+} -@end example +@end smallexample Example sequence of a target being stepped by a single instruction: -@example +@smallexample <- @code{G1445...} -> @code{+} <- @code{s} @@ -14947,7 +14947,7 @@ Example sequence of a target being stepped by a single instruction: -> @code{+} -> @code{1455...} <- @code{+} -@end example +@end smallexample @include gpl.texi diff --git a/gdb/doc/gdbint.texinfo b/gdb/doc/gdbint.texinfo index 9a47976..f21721d 100644 --- a/gdb/doc/gdbint.texinfo +++ b/gdb/doc/gdbint.texinfo @@ -239,9 +239,9 @@ and called functions. machine-independent part of @value{GDBN}, 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 +@smallexample +create_new_frame (read_register (FP_REGNUM), read_pc ())); +@end smallexample @cindex frame pointer register Other than that, all the meaning imparted to @code{FP_REGNUM} is @@ -453,7 +453,7 @@ Insert or remove a hardware watchpoint starting at @var{addr}, for possible values of the enumerated data type @code{target_hw_bp_type}, defined by @file{breakpoint.h} as follows: -@example +@smallexample enum target_hw_bp_type @{ hw_write = 0, /* Common (write) HW watchpoint */ @@ -461,7 +461,7 @@ defined by @file{breakpoint.h} as follows: hw_access = 2, /* Access (read or write) HW watchpoint */ hw_execute = 3 /* Execute HW breakpoint */ @}; -@end example +@end smallexample @noindent These two macros should return 0 for success, non-zero for failure. @@ -863,7 +863,7 @@ maximum of five levels. The overall structure of the table output code is something like this: -@example +@smallexample ui_out_table_begin ui_out_table_header @dots{} @@ -874,7 +874,7 @@ The overall structure of the table output code is something like this: ui_out_tuple_end @dots{} ui_out_table_end -@end example +@end smallexample Here is the description of table-, tuple- and list-related @code{ui_out} functions: @@ -1139,7 +1139,7 @@ produce a table. The original code was: -@example +@smallexample if (!found_a_breakpoint++) @{ annotate_breakpoints_headers (); @@ -1162,11 +1162,11 @@ The original code was: annotate_breakpoints_table (); @} -@end example +@end smallexample Here's the new version: -@example +@smallexample nr_printable_breakpoints = @dots{}; if (addressprint) @@ -1203,13 +1203,13 @@ Here's the new version: ui_out_table_body (uiout); if (nr_printable_breakpoints > 0) annotate_breakpoints_table (); -@end example +@end smallexample This example, from the @code{print_one_breakpoint} function, shows how to produce the actual data for the table whose structure was defined in the above example. The original code was: -@example +@smallexample annotate_record (); annotate_field (0); printf_filtered ("%-3d ", b->number); @@ -1224,11 +1224,11 @@ in the above example. The original code was: annotate_field (3); printf_filtered ("%-3c ", bpenables[(int)b->enable]); @dots{} -@end example +@end smallexample This is the new version: -@example +@smallexample annotate_record (); ui_out_tuple_begin (uiout, "bkpt"); annotate_field (0); @@ -1244,44 +1244,44 @@ This is the new version: annotate_field (3); ui_out_field_fmt (uiout, "enabled", "%c", bpenables[(int)b->enable]); @dots{} -@end example +@end smallexample This example, also from @code{print_one_breakpoint}, shows how to produce a complicated output field using the @code{print_expression} functions which requires a stream to be passed. It also shows how to automate stream destruction with cleanups. The original code was: -@example +@smallexample annotate_field (5); print_expression (b->exp, gdb_stdout); -@end example +@end smallexample The new version is: -@example +@smallexample struct ui_stream *stb = ui_out_stream_new (uiout); struct cleanup *old_chain = make_cleanup_ui_out_stream_delete (stb); ... annotate_field (5); print_expression (b->exp, stb->stream); ui_out_field_stream (uiout, "what", local_stream); -@end example +@end smallexample This example, also from @code{print_one_breakpoint}, shows how to use @code{ui_out_text} and @code{ui_out_field_string}. The original code was: -@example +@smallexample annotate_field (5); if (b->dll_pathname == NULL) printf_filtered ("<any library> "); else printf_filtered ("library \"%s\" ", b->dll_pathname); -@end example +@end smallexample It became: -@example +@smallexample annotate_field (5); if (b->dll_pathname == NULL) @{ @@ -1294,21 +1294,21 @@ It became: ui_out_field_string (uiout, "what", b->dll_pathname); ui_out_text (uiout, "\" "); @} -@end example +@end smallexample The following example from @code{print_one_breakpoint} shows how to use @code{ui_out_field_int} and @code{ui_out_spaces}. The original code was: -@example +@smallexample annotate_field (5); if (b->forked_inferior_pid != 0) printf_filtered ("process %d ", b->forked_inferior_pid); -@end example +@end smallexample It became: -@example +@smallexample annotate_field (5); if (b->forked_inferior_pid != 0) @{ @@ -1316,20 +1316,20 @@ It became: ui_out_field_int (uiout, "what", b->forked_inferior_pid); ui_out_spaces (uiout, 1); @} -@end example +@end smallexample Here's an example of using @code{ui_out_field_string}. The original code was: -@example +@smallexample annotate_field (5); if (b->exec_pathname != NULL) printf_filtered ("program \"%s\" ", b->exec_pathname); -@end example +@end smallexample It became: -@example +@smallexample annotate_field (5); if (b->exec_pathname != NULL) @{ @@ -1337,22 +1337,22 @@ It became: ui_out_field_string (uiout, "what", b->exec_pathname); ui_out_text (uiout, "\" "); @} -@end example +@end smallexample Finally, here's an example of printing an address. The original code: -@example +@smallexample annotate_field (4); printf_filtered ("%s ", local_hex_string_custom ((unsigned long) b->address, "08l")); -@end example +@end smallexample It became: -@example +@smallexample annotate_field (4); ui_out_field_core_addr (uiout, "Address", b->address); -@end example +@end smallexample @section Console Printing @@ -1904,7 +1904,7 @@ parsers that define a bunch of global names, the following lines @strong{must} be included at the top of the YACC parser, to prevent the various parsers from defining the same global names: -@example +@smallexample #define yyparse @var{lang}_parse #define yylex @var{lang}_lex #define yyerror @var{lang}_error @@ -1921,7 +1921,7 @@ various parsers from defining the same global names: #define yyexca @var{lang}_exca #define yyerrflag @var{lang}_errflag #define yynerrs @var{lang}_nerrs -@end example +@end smallexample At the bottom of your parser, define a @code{struct language_defn} and initialize it with the right values for your language. Define an @@ -4185,7 +4185,7 @@ Cleanups are implemented as a chain. The handle returned by later cleanups appended to the chain (but not yet discarded or performed). E.g.: -@example +@smallexample make_cleanup (a, 0); @{ struct cleanup *old = make_cleanup (b, 0); @@ -4193,7 +4193,7 @@ make_cleanup (a, 0); ... do_cleanups (old); @} -@end example +@end smallexample @noindent will call @code{c()} and @code{b()} but will not call @code{a()}. The @@ -4212,13 +4212,13 @@ code-segment avoids a memory leak problem (even when @code{error} is called and a forced stack unwind occurs) by ensuring that the @code{xfree} will always be called: -@example +@smallexample struct cleanup *old = make_cleanup (null_cleanup, 0); data = xmalloc (sizeof blah); make_cleanup (xfree, data); ... blah blah ... do_cleanups (old); -@end example +@end smallexample The second style is try/except. Before it exits, your code-block calls @code{discard_cleanups} with the old cleanup chain and thus ensures that @@ -4226,13 +4226,13 @@ any created cleanups are not performed. For instance, the following code segment, ensures that the file will be closed but only if there is an error: -@example +@smallexample FILE *file = fopen ("afile", "r"); struct cleanup *old = make_cleanup (close_file, file); ... blah blah ... discard_cleanups (old); return file; -@end example +@end smallexample Some functions, e.g. @code{fputs_filtered()} or @code{error()}, specify that they ``should not be called when cleanups are not in place''. This @@ -4389,7 +4389,7 @@ strictly. A function declaration should not have its name in column zero. A function definition should have its name in column zero. -@example +@smallexample /* Declaration */ static void foo (void); /* Definition */ @@ -4397,7 +4397,7 @@ void foo (void) @{ @} -@end example +@end smallexample @emph{Pragmatics: This simplifies scripting. Function definitions can be found using @samp{^function-name}.} @@ -4415,17 +4415,17 @@ for @code{diff} and @code{patch} utilities. Pointers are declared using the traditional K&R C style: -@example +@smallexample void *foo; -@end example +@end smallexample @noindent and not: -@example +@smallexample void * foo; void* foo; -@end example +@end smallexample @subsection Comments @@ -4435,13 +4435,13 @@ The standard GNU requirements on comments must be followed strictly. Block comments must appear in the following form, with no @code{/*}- or @code{*/}-only lines, and no leading @code{*}: -@example +@smallexample /* Wait for control to return from inferior to debugger. If inferior gets a signal, we may decide to start it up again instead of returning. That is why there is a loop in this function. When this function actually returns it means the inferior should be left stopped and @value{GDBN} should read more commands. */ -@end example +@end smallexample (Note that this format is encouraged by Emacs; tabbing for a multi-line comment works correctly, and @kbd{M-q} fills the block consistently.) @@ -4558,12 +4558,12 @@ a header file should explicitly include the header declaring any All include files should be wrapped in: -@example +@smallexample #ifndef INCLUDE_FILE_NAME_H #define INCLUDE_FILE_NAME_H header body #endif -@end example +@end smallexample @subsection Clean Design and Portable Implementation @@ -4723,16 +4723,16 @@ vendors, and operating systems near the bottom of the file. Also, add @code{@var{arch}-@var{xvend}-@var{xos}}. You can test your changes by running -@example +@smallexample ./config.sub @var{xyz} -@end example +@end smallexample @noindent and -@example +@smallexample ./config.sub @code{@var{arch}-@var{xvend}-@var{xos}} -@end example +@end smallexample @noindent which should both respond with @code{@var{arch}-@var{xvend}-@var{xos}} @@ -4769,9 +4769,9 @@ configuration. From the top level directory (containing @file{gdb}, @file{bfd}, @file{libiberty}, and so on): -@example +@smallexample make -f Makefile.in gdb.tar.gz -@end example +@end smallexample @noindent This will properly configure, clean, rebuild any files that are @@ -4903,19 +4903,19 @@ release from the head of the release branch). Releases 5.0 and 5.1 used branch and release tags of the form: -@example +@smallexample gdb_N_M-YYYY-MM-DD-branchpoint gdb_N_M-YYYY-MM-DD-branch gdb_M_N-YYYY-MM-DD-release -@end example +@end smallexample Release 5.2 is trialing the branch and release tags: -@example +@smallexample gdb_N_M-YYYY-MM-DD-branchpoint gdb_N_M-branch gdb_M_N-YYYY-MM-DD-release -@end example +@end smallexample @emph{Pragmatics: The branchpoint and release tags need to identify when a branch and release are made. The branch tag, denoting the head of the @@ -5022,9 +5022,9 @@ start enjoying all the fun @end itemize As an aside, the branch tag name is probably regrettable vis: -@example +@smallexample gdb_N_M-YYYY-MM-DD-@{branch,branchpoint@} -@end example +@end smallexample @subheading Refresh any imported files. @@ -5062,7 +5062,7 @@ There shouldn't be any regressions. I think something like the below was used: -@example +@smallexample $ d=`date -u +%Y-%m-%d` $ echo $d 2002-01-24 @@ -5071,7 +5071,7 @@ gdb_5_1-$d-branchpoint insight+dejagnu $ cvs -f -d /cvs/src rtag -b -r gdb_V_V-$d-branchpoint \ gdb_5_1-$d-branch insight+dejagnu $ -@end example +@end smallexample @itemize @bullet @item @@ -5099,7 +5099,7 @@ releases. With a beta many of the steps can be skipped. @subheading Establish a few defaults. -@example +@smallexample $ b=gdb_5_1-2001-07-29-branch $ v=5.1.1 $ t=/sourceware/snapshot-tmp/gdbadmin-tmp @@ -5111,7 +5111,7 @@ $ pwd $ which autoconf /home/gdbadmin/bin/autoconf $ -@end example +@end smallexample NB: Check the autoconf version carefully. You want to be using the version taken from the binutils snapshot directory. It is most likely @@ -5120,13 +5120,13 @@ correct. @subheading Check out the relevant modules: -@example +@smallexample $ for m in gdb insight dejagnu do ( mkdir -p $m && cd $m && cvs -q -f -d /cvs/src co -P -r $b $m ) done $ -@end example +@end smallexample NB: The reading of @file{.cvsrc} is disabled (@file{-f}) so that there isn't any confusion between what is written here and what your local CVS @@ -5141,7 +5141,7 @@ releases should probably mention any significant bugs that were fixed. Don't forget to update the ChangeLog. -@example +@smallexample $ emacs gdb/src/gdb/NEWS ... c-x 4 a @@ -5149,13 +5149,13 @@ c-x 4 a c-x c-s c-x c-c $ cp gdb/src/gdb/NEWS insight/src/gdb/NEWS $ cp gdb/src/gdb/ChangeLog insight/src/gdb/ChangeLog -@end example +@end smallexample @subsubheading @file{gdb/README} You'll need to update: the version, the update date, and who did it. -@example +@smallexample $ emacs gdb/src/gdb/README ... c-x 4 a @@ -5163,7 +5163,7 @@ c-x 4 a c-x c-s c-x c-c $ cp gdb/src/gdb/README insight/src/gdb/README $ cp gdb/src/gdb/ChangeLog insight/src/gdb/ChangeLog -@end example +@end smallexample @emph{Maintainer note: Hopefully the README file was reviewed before the initial branch was cut so just a simple substitute is needed to get it @@ -5175,7 +5175,7 @@ pursuing.} @subsubheading @file{gdb/version.in} -@example +@smallexample $ echo $v > gdb/src/gdb/version.in $ emacs gdb/src/gdb/version.in ... @@ -5184,7 +5184,7 @@ c-x 4 a c-x c-s c-x c-c $ cp gdb/src/gdb/version.in insight/src/gdb/version.in $ cp gdb/src/gdb/ChangeLog insight/src/gdb/ChangeLog -@end example +@end smallexample @subsubheading @file{dejagnu/src/dejagnu/configure.in} @@ -5200,12 +5200,12 @@ Add a ChangeLog. This is identical to the process used when creating the daily snapshot. -@example +@smallexample $ for m in gdb insight dejagnu do ( cd $m/src && gmake -f Makefile.in $m.tar.bz2 ) done -@end example +@end smallexample @subheading Check the source files @@ -5213,7 +5213,7 @@ You're looking for files that have mysteriously disappeared as the @kbd{distclean} has the habit of deleting files it shouldn't. Watch out for the @file{version.in} update @kbd{cronjob}. -@example +@smallexample $ ( cd gdb/src && cvs -f -q -n update ) M djunpack.bat ? proto-toplev @@ -5231,7 +5231,7 @@ M gdb/version.in ? gdb/doc/gdbint.info-4 ? gdb/doc/gdbint.info-5 $ -@end example +@end smallexample @emph{Don't worry about the @file{gdb.info-??} or @file{gdb/p-exp.tab.c}. They were generated (and yes @file{gdb.info-1} @@ -5240,11 +5240,11 @@ didn't get supressed). Fixing it would be nice though.} @subheading Re-pack the release with @code{gzip} -@example +@smallexample $ cp */*/*.bz2 . $ bunzip2 -k -v *.bz2 $ gzip -9 -v *.tar -@end example +@end smallexample NB: A pipe such as @kbd{bunzip2 < xxx.bz2 | gzip -9 > xxx.gz} shouldn't be used since, in that mode, gzip doesn't know the file name information @@ -5276,9 +5276,9 @@ This is where, unfortunately, the notes just get vague. @subheading Install on sware -@example +@smallexample $ cp *.bz2 *.gz ~ftp/pub/gdb/releases -@end example +@end smallexample @subheading Create and update the web pages. @@ -5319,13 +5319,13 @@ docs from the @file{.tar.bz2}. The best way is to look in the output from one of the nightly cronjobs and then just edit accordingly. Something like: -@example +@smallexample $ ~/ss/update-web-docs \ ~ftp/pub/gdb/releases/gdb-5.1.1.tar.bz2 \ $PWD/www \ /www/sourceware/htdocs/gdb/5.1.1/onlinedocs \ gdb -@end example +@end smallexample @subheading Something about @file{ANNOUNCEMENT} @@ -5365,13 +5365,13 @@ In particular you'll need to commit the changes to: Something like: -@example +@smallexample $ d=`date -u +%Y-%m-%d` $ echo $d 2002-01-24 $ ( cd insight/src/gdb && cvs -f -q update ) $ ( cd insight/src && cvs -f -q tag gdb_5_1_1-$d-release ) -@end example +@end smallexample Insight is used since that contains more of the release than GDB (yes dejagnu doesn't get tagged but I think we can live with that.). @@ -5421,7 +5421,7 @@ the testsuite is running, you'll get mentions of which test file is in use, and a mention of any unexpected passes or fails. When the testsuite is finished, you'll get a summary that looks like this: -@example +@smallexample === gdb Summary === # of expected passes 6016 @@ -5430,7 +5430,7 @@ finished, you'll get a summary that looks like this: # of expected failures 183 # of unresolved testcases 3 # of untested testcases 5 -@end example +@end smallexample The ideal test run consists of expected passes only; however, reality conspires to keep us from this ideal. Unexpected failures indicate |