X-Git-Url: http://drtracing.org/?a=blobdiff_plain;f=gdb%2Fdoc%2Fgdb.texinfo;h=1f1e7269a7f8bf7f05293075b5b0e1a08a8dec16;hb=814e32d7206260dc9d783e28ac2e82d6bda632f0;hp=4a8ada9b5a33d908d538c791c7e6bbd27b682efc;hpb=dcaaae044f52934d5196477f452194ba7f10ad68;p=deliverable%2Fbinutils-gdb.git

diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
index 4a8ada9b5a..1f1e7269a7 100644
--- a/gdb/doc/gdb.texinfo
+++ b/gdb/doc/gdb.texinfo
@@ -349,7 +349,7 @@ omitted from this list, we would like to add your names!
 So that they may not regard their many labors as thankless, we
 particularly thank those who shepherded @value{GDBN} through major
 releases:
-Andrew Cagney (releases 6.1, 6.0, 5.3, 5.2, 5.1 and 5.0);
+Andrew Cagney (releases 6.3, 6.2, 6.1, 6.0, 5.3, 5.2, 5.1 and 5.0);
 Jim Blandy (release 4.18);
 Jason Molenda (release 4.17);
 Stan Shebs (release 4.14);
@@ -932,31 +932,26 @@ file named @var{number}.
 Execute @value{GDBN} commands from file @var{file}.  @xref{Command
 Files,, Command files}.
 
+@item -eval-command @var{command}
+@itemx -ex @var{command}
+@cindex @code{--eval-command}
+@cindex @code{-ex}
+Execute a single @value{GDBN} command.
+
+This option may be used multiple times to call multiple commands.  It may
+also be interleaved with @samp{-command} as required.
+
+@smallexample
+@value{GDBP} -ex 'target sim' -ex 'load' \
+   -x setbreakpoints -ex 'run' a.out
+@end smallexample
+
 @item -directory @var{directory}
 @itemx -d @var{directory}
 @cindex @code{--directory}
 @cindex @code{-d}
 Add @var{directory} to the path to search for source files.
 
-@item -m
-@itemx -mapped
-@cindex @code{--mapped}
-@cindex @code{-m}
-@emph{Warning: this option depends on operating system facilities that are not
-supported on all systems.}@*
-If memory-mapped files are available on your system through the @code{mmap}
-system call, you can use this option
-to have @value{GDBN} write the symbols from your
-program into a reusable file in the current directory.  If the program you are debugging is
-called @file{/tmp/fred}, the mapped symbol file is @file{/tmp/fred.syms}.
-Future @value{GDBN} debugging sessions notice the presence of this file,
-and can quickly map in symbol information from it, rather than reading
-the symbol table from the executable program.
-
-The @file{.syms} file is specific to the host machine where @value{GDBN}
-is run.  It holds an exact image of the internal @value{GDBN} symbol
-table.  It cannot be shared across multiple host platforms.
-
 @item -r
 @itemx -readnow
 @cindex @code{--readnow}
@@ -967,16 +962,6 @@ This makes startup slower, but makes future operations faster.
 
 @end table
 
-You typically combine the @code{-mapped} and @code{-readnow} options in
-order to build a @file{.syms} file that contains complete symbol
-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:
-
-@smallexample
-gdb -batch -nx -mapped -readnow programname
-@end smallexample
-
 @node Mode Options
 @subsection Choosing modes
 
@@ -1023,6 +1008,40 @@ Program exited normally.
 @value{GDBN} control terminates) is not issued when running in batch
 mode.
 
+@item -batch-silent
+@cindex @code{--batch-silent}
+Run in batch mode exactly like @samp{-batch}, but totally silently.  All
+@value{GDBN} output to @code{stdout} is prevented (@code{stderr} is
+unaffected).  This is much quieter than @samp{-silent} and would be useless
+for an interactive session.
+
+This is particularly useful when using targets that give @samp{Loading section}
+messages, for example.
+
+Note that targets that give their output via @value{GDBN}, as opposed to
+writing directly to @code{stdout}, will also be made silent.
+
+@item -return-child-result
+@cindex @code{--return-child-result}
+The return code from @value{GDBN} will be the return code from the child
+process (the process being debugged), with the following exceptions:
+
+@itemize @bullet
+@item
+@value{GDBN} exits abnormally.  E.g., due to an incorrect argument or an
+internal error.  In this case the exit code is the same as it would have been
+without @samp{-return-child-result}.
+@item
+The user quits with an explicit value.  E.g., @samp{quit 1}.
+@item
+The child process never runs, or is not allowed to terminate, in which case
+the exit code will be -1.
+@end itemize
+
+This option is useful in conjunction with @samp{-batch} or @samp{-batch-silent},
+when @value{GDBN} is being used as a remote program loader or simulator
+interface.
+
 @item -nowindows
 @itemx -nw
 @cindex @code{--nowindows}
@@ -1075,7 +1094,7 @@ normal, level 1 is for use when @value{GDBN} is run as a subprocess of
 @sc{gnu} Emacs, level 3 is the maximum annotation suitable for programs
 that control @value{GDBN}, and level 2 has been deprecated.
 
-The annotation mechanism has largely been superseeded by @sc{gdb/mi}
+The annotation mechanism has largely been superseded by @sc{gdb/mi}
 (@pxref{GDB/MI}).
 
 @item --args
@@ -1188,7 +1207,7 @@ Files}, for more details about @value{GDBN} command files.
 
 @item
 Reads the command history recorded in the @dfn{history file}.
-@xref{History}, for more details about the command history and the
+@xref{Command History}, for more details about the command history and the
 files where @value{GDBN} records it.
 @end enumerate
 
@@ -2095,7 +2114,24 @@ terminal.
 
 When you use the @code{tty} command or redirect input in the @code{run}
 command, only the input @emph{for your program} is affected.  The input
-for @value{GDBN} still comes from your terminal.
+for @value{GDBN} still comes from your terminal.  @code{tty} is an alias
+for @code{set inferior-tty}.
+
+@cindex inferior tty
+@cindex set inferior controlling terminal
+You can use the @code{show inferior-tty} command to tell @value{GDBN} to
+display the name of the terminal that will be used for future runs of your
+program.
+
+@table @code
+@item set inferior-tty /dev/ttyb
+@kindex set inferior-tty
+Set the tty for the program being debugged to /dev/ttyb.
+
+@item show inferior-tty
+@kindex show inferior-tty
+Show the current tty for the program being debugged.
+@end table
 
 @node Attach
 @section Debugging an already-running process
@@ -4382,9 +4418,6 @@ pointer and a program counter.
 
 On the 29k architecture, it needs three addresses: a register stack
 pointer, a program counter, and a memory stack pointer.
-@c note to future updaters: this is conditioned on a flag
-@c SETUP_ARBITRARY_FRAME in the tm-*.h files.  The above is up to date
-@c as of 27 Jan 1994.
 
 @kindex up
 @item up @var{n}
@@ -5194,6 +5227,11 @@ for Debugging Your Program or @sc{gnu} CC, gcc.info, Using @sc{gnu} CC}.
 @xref{C, , Debugging C++}, for more info about debug info formats
 that are best suited to C@t{++} programs.
 
+If you ask to print an object whose contents are unknown to
+@value{GDBN}, e.g., because its data type is not completely specified
+by the debug information, @value{GDBN} will say @samp{<incomplete
+type>}.  @xref{Symbols, incomplete type}, for more about this.
+
 @node Arrays
 @section Artificial arrays
 
@@ -5702,6 +5740,20 @@ Return to compressed format for arrays.
 Show whether compressed or pretty format is selected for displaying
 arrays.
 
+@cindex print array indexes
+@item set print array-indexes
+@itemx set print array-indexes on
+Print the index of each element when displaying arrays.  May be more
+convenient to locate a given element in the array or quickly find the
+index of a given element in that printed array.  The default is off.
+
+@item set print array-indexes off
+Stop printing element indexes when displaying arrays.
+
+@item show print array-indexes
+Show whether the index of each element is printed when displaying
+arrays.
+
 @item set print elements @var{number-of-elements}
 @cindex number of array elements to print
 @cindex limit on number of printed array elements
@@ -9072,6 +9124,59 @@ function, @code{_NSPrintForDebugger}, defined.
 @subsection Fortran
 @cindex Fortran-specific support in @value{GDBN}
 
+@value{GDBN} can be used to debug programs written in Fortran, but it
+currently supports only the features of Fortran 77 language.
+
+@cindex trailing underscore, in Fortran symbols
+Some Fortran compilers (@sc{gnu} Fortran 77 and Fortran 95 compilers
+among them) append an underscore to the names of variables and
+functions.  When you debug programs compiled by those compilers, you
+will need to refer to variables and functions with a trailing
+underscore.
+
+@menu
+* Fortran Operators::           Fortran operators and expressions
+* Fortran Defaults::            Default settings for Fortran
+* Special Fortran commands::    Special @value{GDBN} commands for Fortran
+@end menu
+
+@node Fortran Operators
+@subsubsection Fortran operators and expressions
+
+@cindex Fortran operators and expressions
+
+Operators must be defined on values of specific types.  For instance,
+@code{+} is defined on numbers, but not on characters or other non-
+arithmetic types.  Operators are often defined on groups of types. 
+
+@table @code
+@item **
+The exponentiation operator. It raises the first operand to the power
+of the second one.
+
+@item :
+The range operator.  Normally used in the form of array(low:high) to
+represent a section of array.
+@end table
+
+@node Fortran Defaults
+@subsubsection Fortran Defaults
+
+@cindex Fortran Defaults
+
+Fortran symbols are usually case-insensitive, so @value{GDBN} by
+default uses case-insensitive matches for Fortran symbols.  You can
+change that with the @samp{set case-insensitive} command, see
+@ref{Symbols}, for the details.
+
+@node Special Fortran commands
+@subsubsection Special Fortran commands
+
+@cindex Special Fortran commands
+
+@value{GDBN} had some commands to support Fortran specific feature,
+such as common block displaying.
+
 @table @code
 @cindex @code{COMMON} blocks, Fortran
 @kindex info common
@@ -9082,11 +9187,6 @@ all @code{COMMON} blocks visible at current program location are
 printed.
 @end table
 
-Fortran symbols are usually case-insensitive, so @value{GDBN} by
-default uses case-insensitive matches for Fortran symbols.  You can
-change that with the @samp{set case-insensitive} command, see
-@ref{Symbols}, for the details.
-
 @node Pascal
 @subsection Pascal
 
@@ -10023,6 +10123,30 @@ type = struct complex @{
 As with @code{whatis}, using @code{ptype} without an argument refers to
 the type of @code{$}, the last value in the value history.
 
+@cindex incomplete type
+Sometimes, programs use opaque data types or incomplete specifications
+of complex data structure.  If the debug information included in the
+program does not allow @value{GDBN} to display a full declaration of
+the data type, it will say @samp{<incomplete type>}.  For example,
+given these declarations:
+
+@smallexample
+    struct foo;
+    struct foo *fooptr;
+@end smallexample
+
+@noindent
+but no definition for @code{struct foo} itself, @value{GDBN} will say:
+
+@smallexample
+  (gdb) ptype foo
+  $1 = <incomplete type>
+@end smallexample
+
+@noindent
+``Incomplete type'' is C terminology for data types that are not
+completely specified.
+
 @kindex info types
 @item info types @var{regexp}
 @itemx info types
@@ -10652,15 +10776,6 @@ directories to search, just as the shell does when looking for a program
 to run.  You can change the value of this variable, for both @value{GDBN}
 and your program, using the @code{path} command.
 
-On systems with memory-mapped files, an auxiliary file named
-@file{@var{filename}.syms} may hold symbol table information for
-@var{filename}.  If so, @value{GDBN} maps in the symbol table from
-@file{@var{filename}.syms}, starting up more quickly.  See the
-descriptions of the file options @samp{-mapped} and @samp{-readnow}
-(available on the command line, see @ref{File Options, , -readnow},
-and with the commands @code{file}, @code{symbol-file}, or
-@code{add-symbol-file}, described below), for more information.
-
 @cindex unlinked object files
 @cindex patching object files
 You can load unlinked object @file{.o} files into @value{GDBN} using
@@ -10731,38 +10846,13 @@ in stabs format.
 @kindex readnow
 @cindex reading symbols immediately
 @cindex symbols, reading immediately
-@kindex mapped
-@cindex memory-mapped symbol file
-@cindex saving symbol table
-@item symbol-file @var{filename} @r{[} -readnow @r{]} @r{[} -mapped @r{]}
-@itemx file @var{filename} @r{[} -readnow @r{]} @r{[} -mapped @r{]}
+@item symbol-file @var{filename} @r{[} -readnow @r{]}
+@itemx file @var{filename} @r{[} -readnow @r{]}
 You can override the @value{GDBN} two-stage strategy for reading symbol
 tables by using the @samp{-readnow} option with any of the commands that
 load symbol table information, if you want to be sure @value{GDBN} has the
 entire symbol table available.
 
-If memory-mapped files are available on your system through the
-@code{mmap} system call, you can use another option, @samp{-mapped}, to
-cause @value{GDBN} to write the symbols for your program into a reusable
-file.  Future @value{GDBN} debugging sessions map in symbol information
-from this auxiliary symbol file (if the program has not changed), rather
-than spending time reading the symbol table from the executable
-program.  Using the @samp{-mapped} option has the same effect as
-starting @value{GDBN} with the @samp{-mapped} command-line option.
-
-You can use both options together, to make sure the auxiliary symbol
-file has all the symbol information for your program.
-
-The auxiliary symbol file for a program called @var{myprog} is called
-@samp{@var{myprog}.syms}.  Once this file exists (so long as it is newer
-than the corresponding executable), @value{GDBN} always attempts to use
-it when you debug @var{myprog}; no special options or commands are
-needed.
-
-The @file{.syms} file is specific to the host machine where you run
-@value{GDBN}.  It holds an exact image of the internal @value{GDBN}
-symbol table.  It cannot be shared across multiple host platforms.
-
 @c FIXME: for now no mention of directories, since this seems to be in
 @c flux.  13mar1992 status is that in theory GDB would look either in
 @c current dir or in same dir as myprog; but issues like competing
@@ -10791,7 +10881,7 @@ the program is running.  To do this, use the @code{kill} command
 @kindex add-symbol-file
 @cindex dynamic linking
 @item add-symbol-file @var{filename} @var{address}
-@itemx add-symbol-file @var{filename} @var{address} @r{[} -readnow @r{]} @r{[} -mapped @r{]}
+@itemx add-symbol-file @var{filename} @var{address} @r{[} -readnow @r{]}
 @itemx add-symbol-file @var{filename} @r{-s}@var{section} @var{address} @dots{}
 The @code{add-symbol-file} command reads additional symbol table
 information from the file @var{filename}.  You would use this command
@@ -10845,10 +10935,6 @@ way.
 
 @code{add-symbol-file} does not repeat if you press @key{RET} after using it.
 
-You can use the @samp{-mapped} and @samp{-readnow} options just as with
-the @code{symbol-file} command, to change how @value{GDBN} manages the symbol
-table information for @var{filename}.
-
 @kindex add-symbol-file-from-memory
 @cindex @code{syscall DSO}
 @cindex load symbols from memory
@@ -15023,7 +15109,7 @@ described here.
 @menu
 * Prompt::                      Prompt
 * Editing::                     Command editing
-* History::                     Command history
+* Command History::             Command history
 * Screen Size::                 Screen size
 * Numbers::                     Numbers
 * ABI::                         Configuring the current ABI
@@ -15091,7 +15177,7 @@ Show whether command line editing is enabled.
 interface.  Users unfamiliar with @sc{gnu} Emacs or @code{vi} are
 encouraged to read that chapter.
 
-@node History
+@node Command History
 @section Command history
 @cindex command history
 
@@ -15104,6 +15190,17 @@ history facility.
 package, to provide the history facility.  @xref{Using History
 Interactively}, for the detailed description of the History library.
 
+To issue a command to @value{GDBN} without affecting certain aspects of
+the state which is seen by users, prefix it with @samp{server }.  This
+means that this command will not affect the command history, nor will it
+affect @value{GDBN}'s notion of which command to repeat if @key{RET} is
+pressed on a line by itself.
+
+@cindex @code{server}, command prefix
+The server prefix does not affect the recording of values into the value
+history; to print a value without recording it into the value history,
+use the @code{output} command instead of the @code{print} command.
+
 Here is the description of @value{GDBN} commands related to command
 history.
 
@@ -17083,19 +17180,14 @@ For each command in the block, the following is described:
  -command @var{args}@dots{}
 @end smallexample
 
-@subsubheading @value{GDBN} Command
-
-The corresponding @value{GDBN} CLI command.
-
 @subsubheading Result
 
-@subsubheading Out-of-band
+@subsubheading @value{GDBN} Command
 
-@subsubheading Notes
+The corresponding @value{GDBN} CLI command(s), if any.
 
 @subsubheading Example
 
-
 @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 @node GDB/MI Breakpoint Table Commands
 @section @sc{gdb/mi} Breakpoint table commands
@@ -19170,6 +19262,57 @@ The corresponding @value{GDBN} command is @samp{interpreter-exec}.
 (@value{GDBP})
 @end smallexample
 
+@subheading The @code{-inferior-tty-set} Command
+@findex -inferior-tty-set
+
+@subheading Synopsis
+
+@smallexample
+-inferior-tty-set /dev/pts/1
+@end smallexample
+
+Set terminal for future runs of the program being debugged.
+
+@subheading @value{GDBN} Command
+
+The corresponding @value{GDBN} command is @samp{set inferior-tty /dev/pts/1}.
+
+@subheading Example
+
+@smallexample
+(@value{GDBP})
+-inferior-tty-set /dev/pts/1
+^done
+(@value{GDBP})
+@end smallexample
+
+@subheading The @code{-inferior-tty-show} Command
+@findex -inferior-tty-show
+
+@subheading Synopsis
+
+@smallexample
+-inferior-tty-show
+@end smallexample
+
+Show terminal for future runs of program being debugged.
+
+@subheading @value{GDBN} Command
+
+The corresponding @value{GDBN} command is @samp{show inferior-tty}.
+
+@subheading Example
+
+@smallexample
+(@value{GDBP})
+-inferior-tty-set /dev/pts/1
+^done
+(@value{GDBP})
+-inferior-tty-show
+^done,inferior_tty_terminal="/dev/pts/1"
+(@value{GDBP})
+@end smallexample
+
 @ignore
 @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 @node GDB/MI Kod Commands
@@ -19480,14 +19623,14 @@ Show a single frame:
  -stack-list-locals @var{print-values}
 @end smallexample
 
-Display the local variable names for the current frame.  With an
-argument of 0 or @code{--no-values}, prints only the names of the variables.
-With argument of 1 or @code{--all-values}, prints also their values.  With
-argument of 2 or @code{--simple-values}, prints the name, type and value for
-simple data types and the name and type for arrays, structures and
-unions.  In this last case, the idea is that the user can see the
-value of simple data types immediately and he can create variable
-objects for other data types if he wishes to explore their values in
+Display the local variable names for the selected frame.  If
+@var{print-values} is 0 or @code{--no-values}, print only the names of
+the variables; if it is 1 or @code{--all-values}, print also their
+values; and if it is 2 or @code{--simple-values}, print the name,
+type and value for simple data types and the name and type for arrays,
+structures and unions.  In this last case, a frontend can immediately
+display the value of simple data types and create variable objects for
+other data types when the the user wishes to explore their values in
 more detail.
 
 @subsubheading @value{GDBN} Command
@@ -19520,7 +19663,7 @@ more detail.
  -stack-select-frame @var{framenum}
 @end smallexample
 
-Change the current frame.  Select a different frame @var{framenum} on
+Change the selected frame.  Select a different frame @var{framenum} on
 the stack.
 
 @subsubheading @value{GDBN} Command
@@ -20452,23 +20595,27 @@ Returns the number of children of a variable object @var{name}:
 @smallexample
  -var-list-children [@var{print-values}] @var{name}
 @end smallexample
+@anchor{-var-list-children} 
 
-Returns a list of the children of the specified variable object.  With
-just the variable object name as an argument or with an optional
-preceding argument of 0 or @code{--no-values}, prints only the names of the
-variables.  With an optional preceding argument of 1 or @code{--all-values},
-also prints their values.
+Return a list of the children of the specified variable object and
+create variable objects for them, if they do not already exist.  With
+a single argument or if @var{print-values} has a value for of 0 or
+@code{--no-values}, print only the names of the variables; if
+@var{print-values} is 1 or @code{--all-values}, also print their
+values; and if it is 2 or @code{--simple-values} print the name and
+value for simple data types and just the name for arrays, structures
+and unions.
 
 @subsubheading Example
 
 @smallexample
 (@value{GDBP})
  -var-list-children n
- numchild=@var{n},children=[@{name=@var{name},
+ ^done,numchild=@var{n},children=[@{name=@var{name},
  numchild=@var{n},type=@var{type}@},@r{(repeats N times)}]
 (@value{GDBP})
  -var-list-children --all-values n
- numchild=@var{n},children=[@{name=@var{name},
+ ^done,numchild=@var{n},children=[@{name=@var{name},
  numchild=@var{n},value=@var{value},type=@var{type}@},@r{(repeats N times)}]
 @end smallexample
 
@@ -20579,13 +20726,28 @@ subsequent @code{-var-update} list.
 @subsubheading Synopsis
 
 @smallexample
- -var-update @{@var{name} | "*"@}
+ -var-update [@var{print-values}] @{@var{name} | "*"@}
 @end smallexample
 
 Update the value of the variable object @var{name} by evaluating its
 expression after fetching all the new values from memory or registers.
-A @samp{*} causes all existing variable objects to be updated.
+A @samp{*} causes all existing variable objects to be updated.  The
+option @var{print-values} determines whether names both and values, or
+just names are printed in the manner described for
+@code{-var-list-children} (@pxref{-var-list-children}).
 
+@subsubheading Example
+
+@smallexample
+(@value{GDBP})
+-var-assign var1 3
+^done,value="3"
+(@value{GDBP})
+-var-update --all-values var1
+^done,changelist=[@{name="var1",value="3",in_scope="true",
+type_changed="false"@}]
+(@value{GDBP})
+@end smallexample
 
 @node Annotations
 @chapter @value{GDBN} Annotations
@@ -20604,7 +20766,6 @@ This is Edition @value{EDITION}, @value{DATE}.
 
 @menu
 * Annotations Overview::  What annotations are; the general syntax.
-* Server Prefix::       Issuing a command without affecting user state.
 * Prompting::           Annotations marking @value{GDBN}'s need for input.
 * Errors::              Annotations for error messages.
 * Invalidation::        Some annotations describe things now invalid.
@@ -20683,20 +20844,6 @@ Here @samp{quit} is input to @value{GDBN}; the rest is output from
 denotes a @samp{control-z} character) are annotations; the rest is
 output from @value{GDBN}.
 
-@node Server Prefix
-@section The Server Prefix
-@cindex server prefix for annotations
-
-To issue a command to @value{GDBN} without affecting certain aspects of
-the state which is seen by users, prefix it with @samp{server }.  This
-means that this command will not affect the command history, nor will it
-affect @value{GDBN}'s notion of which command to repeat if @key{RET} is
-pressed on a line by itself.
-
-The server prefix does not affect the recording of values into the value
-history; to print a value without recording it into the value history,
-use the @code{output} command instead of the @code{print} command.
-
 @node Prompting
 @section Annotation for @value{GDBN} Input
 
@@ -22062,8 +22209,10 @@ before @value{GDBN} disconnects via the @code{detach} command.
 
 Reply:
 @table @samp
-@item @emph{no response}
-@value{GDBN} does not check for any response after sending this packet.
+@item OK
+for success
+@item E@var{NN}
+for an error
 @end table
 
 @item @code{e} --- reserved