On some systems, @value{GDBN} provides support for debugging programs that
create additional processes using the @code{fork} or @code{vfork} functions.
Currently, the only platforms with this feature are HP-UX (11.x and later
-only?) and GNU/Linux (kernel version 2.5.60 and later).
+only?) and @sc{gnu}/Linux (kernel version 2.5.60 and later).
By default, when a program forks, @value{GDBN} will continue to debug
the parent process and the child process will run unimpeded.
@item Enabled or Disabled
Enabled breakpoints are marked with @samp{y}. @samp{n} marks breakpoints
that are not enabled. An optional @samp{(p)} suffix marks pending
-breakpoints --- breakpoints for which address is either not yet
+breakpoints---breakpoints for which address is either not yet
resolved, pending load of a shared library, or for which address was
in a shared library that was since unloaded. Such breakpoint won't
fire until a shared library that has the symbol or line referred by
Where the breakpoint is in your program, as a memory address. For a
pending breakpoint whose address is not yet known, this field will
contain @samp{<PENDING>}. A breakpoint with several locations will
-have @samp{<MULTIPLE>} in this field --- see below for details.
+have @samp{<MULTIPLE>} in this field---see below for details.
@item What
Where the breakpoint is in the source for your program, as a file and
line number. For a pending breakpoint, the original string passed to
In all those cases, @value{GDBN} will insert a breakpoint at all
the relevant locations.
-A breakpoint with multiple locations is displayed in the
-breakpoint table using several rows --- one header row, followed
-by one row for each breakpoint location. The header row
-has @samp{<MULTIPLE>} in the address column. The rows for
-individual locations contain the actual addresses for locations,
-and say what functions those locations are in. The number
-column for a location has number in the format
+A breakpoint with multiple locations is displayed in the breakpoint
+table using several rows---one header row, followed by one row for
+each breakpoint location. The header row has @samp{<MULTIPLE>} in the
+address column. The rows for individual locations contain the actual
+addresses for locations, and show the functions to which those
+locations belong. The number column for a location is of the form
@var{breakpoint-number}.@var{location-number}.
For example:
+
@smallexample
Num Type Disp Enb Address What
1 breakpoint keep y <MULTIPLE>
Each location can be individually enabled or disabled by passing
@var{breakpoint-number}.@var{location-number} as argument to the
-@code{enable} and @code{disable} commands.
+@code{enable} and @code{disable} commands. Note that you cannot
+delete the individual locations from the list, you can only delete the
+entire list of locations that belong to their parent breakpoint (with
+the @kbd{delete @var{num}} command, where @var{num} is the number of
+the parent breakpoint, 1 in the above example). Disabling or enabling
+the parent breakpoint (@pxref{Disabling}) affects all of the locations
+that belong to that breakpoint.
@cindex pending breakpoints
It's quite common to have a breakpoint inside a shared library.
-The shared library may be loaded and unloaded explicitly,
+Shared libraries can be loaded and unloaded explicitly,
and possibly repeatedly, as the program is executed. To support
this use case, @value{GDBN} updates breakpoint locations whenever
any shared library is loaded or unloaded. Typically, you would
debugging session, when the library is not loaded, and when the
symbols from the library are not available. When you try to set
breakpoint, @value{GDBN} will ask you if you want to set
-a so called @dfn{pending breakpoint} --- breakpoint whose address
+a so called @dfn{pending breakpoint}---breakpoint whose address
is not yet resolved.
After the program is run, whenever a new shared library is loaded,
catch errors where you have no clue what part of your program is the
culprit.)
-On some systems, such as HP-UX, @sc{gnu}/Linux and most other
+On some systems, such as HP-UX, PowerPC, @sc{gnu}/Linux and most other
x86-based targets, @value{GDBN} includes support for hardware
watchpoints, which do not slow down the running of your program.
In multi-threaded programs, watchpoints will detect changes to the
watched expression from every thread.
+@kindex watch thread thread_num
+@item watch @var{expr} thread @var{threadnum}
+Set a watchpoint that will break when @var{expr} is either read from
+or written into by the thread identified by @var{threadnum}. If @var{expr}
+is modified by any other threads not matching @var{threadnum}, @value{GDBN}
+will not break. Note that this will only work with Hardware Watchpoints.
+
@quotation
@emph{Warning:} In multi-threaded programs, software watchpoints
have only limited usefulness. If @value{GDBN} creates a software
@code{info watch} to print a list of breakpoints, watchpoints, and
catchpoints if you do not know which numbers to use.
+Disabling and enabling a breakpoint that has multiple locations
+affects all of its locations.
+
A breakpoint, watchpoint, or catchpoint can have any of four different
states of enablement:
to be defined several times, for application in different contexts.
This is called @dfn{overloading}. When a function name is overloaded,
@samp{break @var{function}} is not enough to tell @value{GDBN} where you want
-a breakpoint. If you realize this is a problem, you can use
-something like @samp{break @var{function}(@var{types})} to specify which
+a breakpoint. You can use explicit signature of the function, as in
+@samp{break @var{function}(@var{types})}, to specify which
particular version of the function you want. Otherwise, @value{GDBN} offers
you a menu of numbered choices for different possible breakpoints, and
waits for your selection with the prompt @samp{>}. The first two
dirname (null)
fullname (null)
blockvector ((struct blockvector *) 0x86c1bd0) (primary)
+ linetable ((struct linetable *) 0x8370fa0)
debugformat DWARF 2
@}
@}
@menu
* Connecting:: Connecting to a remote target
+* File Transfer:: Sending files to a remote system
* Server:: Using the gdbserver program
* Remote Configuration:: Remote configuration
* Remote Stub:: Implementing a remote stub
and implement.
@end table
+@node File Transfer
+@section Sending files to a remote system
+@cindex remote target, file transfer
+@cindex file transfer
+@cindex sending files to remote systems
+
+Some remote targets offer the ability to transfer files over the same
+connection used to communicate with @value{GDBN}. This is convenient
+for targets accessible through other means, e.g.@: @sc{gnu}/Linux systems
+running @code{gdbserver} over a network interface. For other targets,
+e.g.@: embedded devices with only a single serial port, this may be
+the only way to upload or download files.
+
+Not all remote targets support these commands.
+
+@table @code
+@kindex remote put
+@item remote put @var{hostfile} @var{targetfile}
+Copy file @var{hostfile} from the host system (the machine running
+@value{GDBN}) to @var{targetfile} on the target system.
+
+@kindex remote get
+@item remote get @var{targetfile} @var{hostfile}
+Copy file @var{targetfile} from the target system to @var{hostfile}
+on the host system.
+
+@kindex remote delete
+@item remote delete @var{targetfile}
+Delete @var{targetfile} from the target system.
+
+@end table
+
@node Server
@section Using the @code{gdbserver} Program
@tab @code{QPassSignals}
@tab @code{handle @var{signal}}
+@item @code{hostio-close-packet}
+@tab @code{vFile:close}
+@tab @code{remote get}, @code{remote put}
+
+@item @code{hostio-open-packet}
+@tab @code{vFile:open}
+@tab @code{remote get}, @code{remote put}
+
+@item @code{hostio-pread-packet}
+@tab @code{vFile:pread}
+@tab @code{remote get}, @code{remote put}
+
+@item @code{hostio-pwrite-packet}
+@tab @code{vFile:pwrite}
+@tab @code{remote get}, @code{remote put}
+
+@item @code{hostio-unlink-packet}
+@tab @code{vFile:unlink}
+@tab @code{remote delete}
@end multitable
@node Remote Stub
If the underlying @code{C} implementation used to build @value{GDBN} has
support for the three conversion letters for DFP types, other modifiers
-such as width and precision will also be available for @value{GDB} to use.
+such as width and precision will also be available for @value{GDBN} to use.
In case there is no such @code{C} support, no additional modifiers will be
available and the value will be printed in the standard way.
* GDB/MI Signal Handling Commands::
@end ignore
* GDB/MI Target Manipulation::
+* GDB/MI File Transfer Commands::
* GDB/MI Miscellaneous Commands::
@end menu
@subsubheading Synopsis
@smallexample
- -break-insert [ -t ] [ -h ] [ -r ]
+ -break-insert [ -t ] [ -h ] [ -f ]
[ -c @var{condition} ] [ -i @var{ignore-count} ]
- [ -p @var{thread} ] [ @var{line} | @var{addr} ]
+ [ -p @var{thread} ] [ @var{location} ]
@end smallexample
@noindent
-If specified, @var{line}, can be one of:
+If specified, @var{location}, can be one of:
@itemize @bullet
@item function
Make the breakpoint conditional on @var{condition}.
@item -i @var{ignore-count}
Initialize the @var{ignore-count}.
-@item -r
-Insert a regular breakpoint in all the functions whose names match the
-given regular expression. Other flags are not applicable to regular
-expressions.
+@item -f
+If @var{location} cannot be parsed (for example if it
+refers to unknown files or functions), create a pending
+breakpoint. Without this flag, @value{GDBN} will report
+an error, and won't create a breakpoint, if @var{location}
+cannot be parsed.
@end table
@subsubheading Result
(gdb)
@end smallexample
+@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+@node GDB/MI File Transfer Commands
+@section @sc{gdb/mi} File Transfer Commands
+
+
+@subheading The @code{-target-file-put} Command
+@findex -target-file-put
+
+@subsubheading Synopsis
+
+@smallexample
+ -target-file-put @var{hostfile} @var{targetfile}
+@end smallexample
+
+Copy file @var{hostfile} from the host system (the machine running
+@value{GDBN}) to @var{targetfile} on the target system.
+
+@subsubheading @value{GDBN} Command
+
+The corresponding @value{GDBN} command is @samp{remote put}.
+
+@subsubheading Example
+
+@smallexample
+(gdb)
+-target-file-put localfile remotefile
+^done
+(gdb)
+@end smallexample
+
+
+@subheading The @code{-target-file-put} Command
+@findex -target-file-get
+
+@subsubheading Synopsis
+
+@smallexample
+ -target-file-get @var{targetfile} @var{hostfile}
+@end smallexample
+
+Copy file @var{targetfile} from the target system to @var{hostfile}
+on the host system.
+
+@subsubheading @value{GDBN} Command
+
+The corresponding @value{GDBN} command is @samp{remote get}.
+
+@subsubheading Example
+
+@smallexample
+(gdb)
+-target-file-get remotefile localfile
+^done
+(gdb)
+@end smallexample
+
+
+@subheading The @code{-target-file-delete} Command
+@findex -target-file-delete
+
+@subsubheading Synopsis
+
+@smallexample
+ -target-file-delete @var{targetfile}
+@end smallexample
+
+Delete @var{targetfile} from the target system.
+
+@subsubheading @value{GDBN} Command
+
+The corresponding @value{GDBN} command is @samp{remote delete}.
+
+@subsubheading Example
+
+@smallexample
+(gdb)
+-target-file-delete remotefile
+^done
+(gdb)
+@end smallexample
+
+
@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
@node GDB/MI Miscellaneous Commands
@section Miscellaneous @sc{gdb/mi} Commands
* General Query Packets::
* Register Packet Format::
* Tracepoint Packets::
+* Host I/O Packets::
* Interrupts::
* Examples::
* File-I/O Remote Protocol Extension::
is not interpreted as the start of a run-length encoded sequence
(described next).
-Response @var{data} can be run-length encoded to save space. A @samp{*}
-means that the next character is an @sc{ascii} encoding giving a repeat count
-which stands for that many repetitions of the character preceding the
-@samp{*}. The encoding is @code{n+29}, yielding a printable character
-where @code{n >=3} (which is where rle starts to win). The printable
-characters @samp{$}, @samp{#}, @samp{+} and @samp{-} or with a numeric
-value greater than 126 should not be used.
-
-So:
-@smallexample
-"@code{0* }"
-@end smallexample
-@noindent
-means the same as "0000".
+Response @var{data} can be run-length encoded to save space.
+Run-length encoding replaces runs of identical characters with one
+instance of the repeated character, followed by a @samp{*} and a
+repeat count. The repeat count is itself sent encoded, to avoid
+binary characters in @var{data}: a value of @var{n} is sent as
+@code{@var{n}+29}. For a repeat count greater or equal to 3, this
+produces a printable @sc{ascii} character, e.g.@: a space (@sc{ascii}
+code 32) for a repeat count of 3. (This is because run-length
+encoding starts to win for counts 3 or more.) Thus, for example,
+@samp{0* } is a run-length encoding of ``0000'': the space character
+after @samp{*} means repeat the leading @code{0} @w{@code{32 - 29 =
+3}} more times.
+
+The printable characters @samp{#} and @samp{$} or with a numeric value
+greater than 126 must not be used. Runs of six repeats (@samp{#}) or
+seven repeats (@samp{$}) can be expanded using a repeat count of only
+five (@samp{"}). For example, @samp{00000000} can be encoded as
+@samp{0*"00}.
The error response returned for some packets includes a two character
error number. That number is not well defined.
The @samp{vCont} packet is not supported.
@end table
+@item vFile:@var{operation}:@var{parameter}@dots{}
+@cindex @samp{vFile} packet
+Perform a file operation on the target system. For details,
+see @ref{Host I/O Packets}.
+
@item vFlashErase:@var{addr},@var{length}
@cindex @samp{vFlashErase} packet
Direct the stub to erase @var{length} bytes of flash starting at
@end table
+@node Host I/O Packets
+@section Host I/O Packets
+@cindex Host I/O, remote protocol
+@cindex file transfer, remote protocol
+
+The @dfn{Host I/O} packets allow @value{GDBN} to perform I/O
+operations on the far side of a remote link. For example, Host I/O is
+used to upload and download files to a remote target with its own
+filesystem. Host I/O uses the same constant values and data structure
+layout as the target-initiated File-I/O protocol. However, the
+Host I/O packets are structured differently. The target-initiated
+protocol relies on target memory to store parameters and buffers.
+Host I/O requests are initiated by @value{GDBN}, and the
+target's memory is not involved. @xref{File-I/O Remote Protocol
+Extension}, for more details on the target-initiated protocol.
+
+The Host I/O request packets all encode a single operation along with
+its arguments. They have this format:
+
+@table @samp
+
+@item vFile:@var{operation}: @var{parameter}@dots{}
+@var{operation} is the name of the particular request; the target
+should compare the entire packet name up to the second colon when checking
+for a supported operation. The format of @var{parameter} depends on
+the operation. Numbers are always passed in hexadecimal. Negative
+numbers have an explicit minus sign (i.e.@: two's complement is not
+used). Strings (e.g.@: filenames) are encoded as a series of
+hexadecimal bytes. The last argument to a system call may be a
+buffer of escaped binary data (@pxref{Binary Data}).
+
+@end table
+
+The valid responses to Host I/O packets are:
+
+@table @samp
+
+@item F @var{result} [, @var{errno}] [; @var{attachment}]
+@var{result} is the integer value returned by this operation, usually
+non-negative for success and -1 for errors. If an error has occured,
+@var{errno} will be included in the result. @var{errno} will have a
+value defined by the File-I/O protocol (@pxref{Errno Values}). For
+operations which return data, @var{attachment} supplies the data as a
+binary buffer. Binary buffers in response packets are escaped in the
+normal way (@pxref{Binary Data}). See the individual packet
+documentation for the interpretation of @var{result} and
+@var{attachment}.
+
+@item
+An empty response indicates that this operation is not recognized.
+
+@end table
+
+These are the supported Host I/O operations:
+
+@table @samp
+@item vFile:open: @var{pathname}, @var{flags}, @var{mode}
+Open a file at @var{pathname} and return a file descriptor for it, or
+return -1 if an error occurs. @var{pathname} is a string,
+@var{flags} is an integer indicating a mask of open flags
+(@pxref{Open Flags}), and @var{mode} is an integer indicating a mask
+of mode bits to use if the file is created (@pxref{mode_t Values}).
+@xref{open}, for details of the open flags and mode values.
+
+@item vFile:close: @var{fd}
+Close the open file corresponding to @var{fd} and return 0, or
+-1 if an error occurs.
+
+@item vFile:pread: @var{fd}, @var{count}, @var{offset}
+Read data from the open file corresponding to @var{fd}. Up to
+@var{count} bytes will be read from the file, starting at @var{offset}
+relative to the start of the file. The target may read fewer bytes;
+common reasons include packet size limits and an end-of-file
+condition. The number of bytes read is returned. Zero should only be
+returned for a successful read at the end of the file, or if
+@var{count} was zero.
+
+The data read should be returned as a binary attachment on success.
+If zero bytes were read, the response should include an empty binary
+attachment (i.e.@: a trailing semicolon). The return value is the
+number of target bytes read; the binary attachment may be longer if
+some characters were escaped.
+
+@item vFile:pwrite: @var{fd}, @var{offset}, @var{data}
+Write @var{data} (a binary buffer) to the open file corresponding
+to @var{fd}. Start the write at @var{offset} from the start of the
+file. Unlike many @code{write} system calls, there is no
+separate @var{count} argument; the length of @var{data} in the
+packet is used. @samp{vFile:write} returns the number of bytes written,
+which may be shorter than the length of @var{data}, or -1 if an
+error occurred.
+
+@item vFile:unlink: @var{pathname}
+Delete the file at @var{pathname} on the target. Return 0,
+or -1 if an error occurs. @var{pathname} is a string.
+
+@end table
+
@node Interrupts
@section Interrupts
@cindex interrupts (remote protocol)
projects / binutils.git / blobdiff