* gdb.texinfo (Fortran): Add some words about Fortran debugging.

2 files changed, 169 insertions, 117 deletions

diff --git a/gdb/doc/ChangeLog b/gdb/doc/ChangeLog
index cce8e6f..7343e2a 100644
--- a/gdb/doc/ChangeLog
+++ b/gdb/doc/ChangeLog
@@ -1,3 +1,7 @@
+2005-11-14  Wu Zhou  <woodzltc@cn.ibm.com>
+
+	* gdb.texinfo (Fortran): Add some words about Fortran debugging.
+
 2005-11-12  Jim Blandy  <jimb@redhat.com>
 
 	* gdb.texinfo (General Query Packets): Put packets in alphabetical
diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
index 16cb84a..1f1e726 100644
--- a/gdb/doc/gdb.texinfo
+++ b/gdb/doc/gdb.texinfo
@@ -9124,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
@@ -9134,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
 
@@ -22762,17 +22810,6 @@ Where @var{pid} is an unsigned hexidecimal process id.
 Any other reply implies the old pid.
 @end table
 
-@item @code{q}@code{CRC:}@var{addr}@code{,}@var{length} --- compute CRC of memory block
-@cindex CRC of memory block, remote request
-@cindex @code{qCRC} packet
-Reply:
-@table @samp
-@item @code{E}@var{NN}
-An error (such as memory fault)
-@item @code{C}@var{CRC32}
-A 32 bit cyclic redundancy check of the specified memory region.
-@end table
-
 @item @code{q}@code{fThreadInfo} -- all thread ids
 @cindex list active threads, remote request
 @cindex @code{qfThreadInfo} packet
@@ -22803,43 +22840,25 @@ more thread ids, in big-endian unsigned hex, separated by commas.
 ids (using the @code{qs} form of the query), until the target responds
 with @code{l} (lower-case el, for @code{'last'}).
 
-@item @code{qGetTLSAddr}:@var{thread-id},@var{offset},@var{lm} --- get thread local storage address
-@cindex get thread-local storage address, remote request
-@cindex @code{qGetTLSAddr} packet
-Fetch the address associated with thread local storage specified
-by @var{thread-id}, @var{offset}, and @var{lm}.
-
-@var{thread-id} is the (big endian, hex encoded) thread id associated with the
-thread for which to fetch the TLS address.
-
-@var{offset} is the (big endian, hex encoded) offset associated with the
-thread local variable.  (This offset is obtained from the debug
-information associated with the variable.)
-
-@var{lm} is the (big endian, hex encoded) OS/ABI specific encoding of the
-the load module associated with the thread local storage.  For example,
-a @sc{gnu}/Linux system will pass the link map address of the shared
-object associated with the thread local storage under consideration. 
-Other operating environments may choose to represent the load module
-differently, so the precise meaning of this parameter will vary.
+@item @code{q}@code{ThreadExtraInfo}@code{,}@var{id} --- extra thread info
+@cindex thread attributes info, remote request
+@cindex @code{qThreadExtraInfo} packet
+Where @var{id} is a thread-id in big-endian hex.  Obtain a printable
+string description of a thread's attributes from the target OS.  This
+string may contain anything that the target OS thinks is interesting for
+@value{GDBN} to tell the user about the thread.  The string is displayed
+in @value{GDBN}'s @samp{info threads} display.  Some examples of
+possible thread extra info strings are ``Runnable'', or ``Blocked on
+Mutex''.
 
 Reply:
-@table @asis
+@table @samp
 @item @var{XX@dots{}}
-Hex encoded (big endian) bytes representing the address of the thread
-local storage requested.
-
-@item @code{E}@var{nn} (where @var{nn} are hex digits)
-An error occurred.
-
-@item @code{""} (empty)
-An empty reply indicates that @code{qGetTLSAddr} is not supported by the stub.
+Where @var{XX@dots{}} is a hex encoding of @sc{ascii} data, comprising
+the printable string containing the extra information about the thread's
+attributes.
 @end table
 
-Use of this request packet is controlled by the @code{set remote
-get-thread-local-storage-address} command (@pxref{Remote
-configuration, set remote get-thread-local-storage-address}).
-
 @item @code{q}@code{L}@var{startflag}@var{threadcount}@var{nextthread} --- query @var{LIST} or @var{threadLIST} @strong{(deprecated)}
 
 Obtain thread information from RTOS.  Where: @var{startflag} (one hex
@@ -22863,6 +22882,17 @@ is a sequence of thread IDs from the target.  @var{threadid} (eight hex
 digits).  See @code{remote.c:parse_threadlist_response()}.
 @end table
 
+@item @code{q}@code{CRC:}@var{addr}@code{,}@var{length} --- compute CRC of memory block
+@cindex CRC of memory block, remote request
+@cindex @code{qCRC} packet
+Reply:
+@table @samp
+@item @code{E}@var{NN}
+An error (such as memory fault)
+@item @code{C}@var{CRC32}
+A 32 bit cyclic redundancy check of the specified memory region.
+@end table
+
 @item @code{q}@code{Offsets} --- query sect offs
 @cindex section offsets, remote request
 @cindex @code{qOffsets} packet
@@ -22889,6 +22919,65 @@ Reply:
 
 See @code{remote.c:remote_unpack_thread_info_response()}.
 
+@item @code{q}@code{Rcmd,}@var{command} --- remote command
+@cindex execute remote command, remote request
+@cindex @code{qRcmd} packet
+@var{command} (hex encoded) is passed to the local interpreter for
+execution.  Invalid commands should be reported using the output string.
+Before the final result packet, the target may also respond with a
+number of intermediate @code{O}@var{output} console output packets.
+@emph{Implementors should note that providing access to a stubs's
+interpreter may have security implications}.
+
+Reply:
+@table @samp
+@item OK
+A command response with no output.
+@item @var{OUTPUT}
+A command response with the hex encoded output string @var{OUTPUT}.
+@item @code{E}@var{NN}
+Indicate a badly formed request.
+@item @samp{}
+When @samp{q}@samp{Rcmd} is not recognized.
+@end table
+z
+@item @code{qSymbol::} --- symbol lookup
+@cindex symbol lookup, remote request
+@cindex @code{qSymbol} packet
+Notify the target that @value{GDBN} is prepared to serve symbol lookup
+requests.  Accept requests from the target for the values of symbols.
+
+Reply:
+@table @samp
+@item @code{OK}
+The target does not need to look up any (more) symbols.
+@item @code{qSymbol:}@var{sym_name}
+The target requests the value of symbol @var{sym_name} (hex encoded).
+@value{GDBN} may provide the value by using the
+@code{qSymbol:}@var{sym_value}:@var{sym_name} message, described below.
+@end table
+
+@item @code{qSymbol:}@var{sym_value}:@var{sym_name} --- symbol value
+
+Set the value of @var{sym_name} to @var{sym_value}.
+
+@var{sym_name} (hex encoded) is the name of a symbol whose value the
+target has previously requested.
+
+@var{sym_value} (hex) is the value for symbol @var{sym_name}.  If
+@value{GDBN} cannot supply a value for @var{sym_name}, then this field
+will be empty.
+
+Reply:
+@table @samp
+@item @code{OK}
+The target does not need to look up any (more) symbols.
+@item @code{qSymbol:}@var{sym_name}
+The target requests the value of a new symbol @var{sym_name} (hex
+encoded).  @value{GDBN} will continue to supply the values of symbols
+(if available), until the target ceases to request them.
+@end table
+
 @item @code{qPart}:@var{object}:@code{read}:@var{annex}:@var{offset},@var{length} --- read special data
 @cindex read special object, remote request
 @cindex @code{qPart} packet
@@ -22968,84 +23057,43 @@ not recognize the @var{object} keyword, or its support for
 @var{object} does not recognize the @var{operation} keyword,
 the stub must respond with an empty packet.
 
-@item @code{q}@code{Rcmd,}@var{command} --- remote command
-@cindex execute remote command, remote request
-@cindex @code{qRcmd} packet
-@var{command} (hex encoded) is passed to the local interpreter for
-execution.  Invalid commands should be reported using the output string.
-Before the final result packet, the target may also respond with a
-number of intermediate @code{O}@var{output} console output packets.
-@emph{Implementors should note that providing access to a stubs's
-interpreter may have security implications}.
-
-Reply:
-@table @samp
-@item OK
-A command response with no output.
-@item @var{OUTPUT}
-A command response with the hex encoded output string @var{OUTPUT}.
-@item @code{E}@var{NN}
-Indicate a badly formed request.
-@item @samp{}
-When @samp{q}@samp{Rcmd} is not recognized.
-@end table
-
-@item @code{qSymbol::} --- symbol lookup
-@cindex symbol lookup, remote request
-@cindex @code{qSymbol} packet
-Notify the target that @value{GDBN} is prepared to serve symbol lookup
-requests.  Accept requests from the target for the values of symbols.
-
-Reply:
-@table @samp
-@item @code{OK}
-The target does not need to look up any (more) symbols.
-@item @code{qSymbol:}@var{sym_name}
-The target requests the value of symbol @var{sym_name} (hex encoded).
-@value{GDBN} may provide the value by using the
-@code{qSymbol:}@var{sym_value}:@var{sym_name} message, described below.
-@end table
-
-@item @code{qSymbol:}@var{sym_value}:@var{sym_name} --- symbol value
+@item @code{qGetTLSAddr}:@var{thread-id},@var{offset},@var{lm} --- get thread local storage address
+@cindex get thread-local storage address, remote request
+@cindex @code{qGetTLSAddr} packet
+Fetch the address associated with thread local storage specified
+by @var{thread-id}, @var{offset}, and @var{lm}.
 
-Set the value of @var{sym_name} to @var{sym_value}.
+@var{thread-id} is the (big endian, hex encoded) thread id associated with the
+thread for which to fetch the TLS address.
 
-@var{sym_name} (hex encoded) is the name of a symbol whose value the
-target has previously requested.
+@var{offset} is the (big endian, hex encoded) offset associated with the
+thread local variable.  (This offset is obtained from the debug
+information associated with the variable.)
 
-@var{sym_value} (hex) is the value for symbol @var{sym_name}.  If
-@value{GDBN} cannot supply a value for @var{sym_name}, then this field
-will be empty.
+@var{lm} is the (big endian, hex encoded) OS/ABI specific encoding of the
+the load module associated with the thread local storage.  For example,
+a @sc{gnu}/Linux system will pass the link map address of the shared
+object associated with the thread local storage under consideration. 
+Other operating environments may choose to represent the load module
+differently, so the precise meaning of this parameter will vary.
 
 Reply:
-@table @samp
-@item @code{OK}
-The target does not need to look up any (more) symbols.
-@item @code{qSymbol:}@var{sym_name}
-The target requests the value of a new symbol @var{sym_name} (hex
-encoded).  @value{GDBN} will continue to supply the values of symbols
-(if available), until the target ceases to request them.
-@end table
+@table @asis
+@item @var{XX@dots{}}
+Hex encoded (big endian) bytes representing the address of the thread
+local storage requested.
 
-@item @code{q}@code{ThreadExtraInfo}@code{,}@var{id} --- extra thread info
-@cindex thread attributes info, remote request
-@cindex @code{qThreadExtraInfo} packet
-Where @var{id} is a thread-id in big-endian hex.  Obtain a printable
-string description of a thread's attributes from the target OS.  This
-string may contain anything that the target OS thinks is interesting for
-@value{GDBN} to tell the user about the thread.  The string is displayed
-in @value{GDBN}'s @samp{info threads} display.  Some examples of
-possible thread extra info strings are ``Runnable'', or ``Blocked on
-Mutex''.
+@item @code{E}@var{nn} (where @var{nn} are hex digits)
+An error occurred.
 
-Reply:
-@table @samp
-@item @var{XX@dots{}}
-Where @var{XX@dots{}} is a hex encoding of @sc{ascii} data, comprising
-the printable string containing the extra information about the thread's
-attributes.
+@item @code{""} (empty)
+An empty reply indicates that @code{qGetTLSAddr} is not supported by the stub.
 @end table
 
+Use of this request packet is controlled by the @code{set remote
+get-thread-local-storage-address} command (@pxref{Remote
+configuration, set remote get-thread-local-storage-address}).
+
 @end table
 
 @node Register Packet Format