[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
D.1 Overview D.2 Packets D.3 Stop Reply Packets D.4 General Query Packets D.5 Register Packet Format D.6 Examples D.7 File-I/O remote protocol extension
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
There may be occasions when you need to know something about the protocol--for example, if there is only one serial port to your target machine, you might want your program to do something special if it recognizes a packet meant for GDB.
In the examples below, `->' and `<-' are used to indicate transmitted and received data respectfully.
All GDB commands and responses (other than acknowledgments) are sent as a packet. A packet is introduced with the character `$', the actual packet-data, and the terminating character `#' followed by a two-digit checksum:
|
The two-digit checksum is computed as the modulo 256 sum of all characters between the leading `$' and the trailing `#' (an eight bit unsigned checksum).
Implementors should note that prior to GDB 5.0 the protocol specification also included an optional two-digit sequence-id:
|
That sequence-id was appended to the acknowledgment. GDB has never output sequence-ids. Stubs that handle packets added since GDB 5.0 must not accept sequence-id.
When either the host or the target machine receives a packet, the first response expected is an acknowledgment: either `+' (to indicate the package was received correctly) or `-' (to request retransmission):
-> |
The host (GDB) sends commands, and the target (the debugging stub incorporated in your program) sends a response. In the case of step and continue commands, the response is only sent when the operation has completed (the target has again stopped).
packet-data consists of a sequence of characters with the exception of `#' and `$' (see `X' packet for additional exceptions).
Fields within the packet should be separated using `,' `;' or `:'. Except where otherwise noted all numbers are represented in HEX with leading zeros suppressed.
Implementors should note that prior to GDB 5.0, the character `:' could not appear as the third character in a packet (as it would potentially conflict with the sequence-id).
Response data can be run-length encoded to save space. A `*'
means that the next character is an ASCII encoding giving a repeat count
which stands for that many repetitions of the character preceding the
`*'. The encoding is n+29
, yielding a printable character
where n >=3
(which is where rle starts to win). The printable
characters `$', `#', `+' and `-' or with a numeric
value greater than 126 should not be used.
So:
" |
The error response returned for some packets includes a two character error number. That number is not well defined.
For any command not supported by the stub, an empty response (`$#00') should be returned. That way it is possible to extend the protocol. A newer GDB can tell if a packet is supported based on that response.
A stub is required to support the `g', `G', `m', `M', `c', and `s' commands. All other commands are optional.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
The following table provides a complete list of all currently defined commands and their corresponding response data.
!
-- extended mode
Enable extended mode. In extended mode, the remote server is made persistent. The `R' packet is used to restart the program being debugged.
Reply:
?
-- last signal
Indicate the reason the target halted. The reply is the same as for step and continue.
Reply: See section D.3 Stop Reply Packets, for the reply specifications.
a
-- reserved
Reserved for future use.
A
arglen,
argnum,
arg,...
-- set program arguments (reserved)
Initialized `argv[]' array passed into program. arglen
specifies the number of bytes in the hex encoded byte stream arg.
See gdbserver
for more details.
Reply:
b
baud -- set baud (deprecated)
Change the serial line speed to baud.
JTC: When does the transport layer state change? When it's received, or after the ACK is transmitted. In either case, there are problems if the command or the acknowledgment packet is dropped.
Stan: If people really wanted to add something like this, and get it working for the first time, they ought to modify ser-unix.c to send some kind of out-of-band message to a specially-setup stub and have the switch happen "in between" packets, so that from remote protocol's point of view, nothing actually happened.
B
addr,mode -- set breakpoint (deprecated)
Set (mode is `S') or clear (mode is `C') a breakpoint at addr.
This packet has been replaced by the `Z' and `z' packets (see insert breakpoint or watchpoint packet).
c
addr -- continue
addr is address to resume. If addr is omitted, resume at current address.
Reply: See section D.3 Stop Reply Packets, for the reply specifications.
C
sig;
addr -- continue with signal
Continue with signal sig (hex signal number). If
;
addr is omitted, resume at same address.
Reply: See section D.3 Stop Reply Packets, for the reply specifications.
d
-- toggle debug (deprecated)
Toggle debug flag.
D
-- detach
Detach GDB from the remote system. Sent to the remote target
before GDB disconnects via the detach
command.
Reply:
e
-- reserved
Reserved for future use.
E
-- reserved
Reserved for future use.
f
-- reserved
Reserved for future use.
F
RC,
EE,
CF;
XX -- Reply to target's F packet.
This packet is send by GDB as reply to a F
request packet
sent by the target. This is part of the File-I/O protocol extension.
See section D.7 File-I/O remote protocol extension, for the specification.
g
-- read registers
Read general registers.
Reply:
g
packets is specified below.
G
XX... -- write regs
See read registers packet, for a description of the XX... data.
Reply:
h
-- reserved
Reserved for future use.
H
ct... -- set thread
Set thread for subsequent operations (`m', `M', `g', `G', et.al.). c depends on the operation to be performed: it should be `c' for step and continue operations, `g' for other operations. The thread designator t... may be -1, meaning all the threads, a thread number, or zero which means pick any thread.
Reply:
i
addr,
nnn -- cycle step (draft)
Step the remote target by a single clock cycle. If ,
nnn is
present, cycle step nnn cycles. If addr is present, cycle
step starting at that address.
I
-- signal then cycle step (reserved)
See step with signal packet. See cycle step packet.
j
-- reserved
Reserved for future use.
J
-- reserved
Reserved for future use.
k
-- kill request
FIXME: There is no description of how to operate when a specific thread context has been selected (i.e. does 'k' kill only that thread?).
K
-- reserved
Reserved for future use.
l
-- reserved
Reserved for future use.
L
-- reserved
Reserved for future use.
m
addr,
length -- read memory
Read length bytes of memory starting at address addr. Neither GDB nor the stub assume that sized memory transfers are assumed using word aligned accesses. FIXME: A word aligned memory transfer mechanism is needed.
Reply:
M
addr,length:
XX... -- write mem
Write length bytes of memory starting at address addr. XX... is the data.
Reply:
n
-- reserved
Reserved for future use.
N
-- reserved
Reserved for future use.
o
-- reserved
Reserved for future use.
O
-- reserved
p
hex number of register -- read register packet
See read registers packet, for a description of how the returned register value is encoded.
Reply:
P
n...=
r... -- write register
Write register n... with value r..., which contains two hex digits for each byte in the register (target byte order).
Reply:
q
query -- general query
Request info about query. In general GDB queries have a leading upper case letter. Custom vendor queries should use a company prefix (in lower case) ex: `qfsf.var'. query may optionally be followed by a `,' or `;' separated list. Stubs must ensure that they match the full query name.
Reply:
Q
var=
val -- general set
Set value of var to val.
See general query packet, for a discussion of naming conventions.
r
-- reset (deprecated)
Reset the entire system.
R
XX -- remote restart
Restart the program being debugged. XX, while needed, is ignored. This packet is only available in extended mode.
Reply:
s
addr -- step
addr is address to resume. If addr is omitted, resume at same address.
Reply: See section D.3 Stop Reply Packets, for the reply specifications.
S
sig;
addr -- step with signal
Like `C' but step not continue.
Reply: See section D.3 Stop Reply Packets, for the reply specifications.
t
addr:
PP,
MM -- search
Search backwards starting at address addr for a match with pattern PP and mask MM. PP and MM are 4 bytes. addr must be at least 3 digits.
T
XX -- thread alive
Find out if the thread XX is alive.
Reply:
u
-- reserved
Reserved for future use.
U
-- reserved
Reserved for future use.
v
-- verbose packet prefix
Packets starting with v
are identified by a multi-letter name,
up to the first ;
or ?
(or the end of the packet).
vCont
[;action[:
tid]]... -- extended resume
Resume the inferior. Different actions may be specified for each thread. If an action is specified with no tid, then it is applied to any threads that don't have a specific action specified; if no default action is specified then other threads should remain stopped. Specifying multiple default actions is an error; specifying no actions is also an error. Thread IDs are specified in hexadecimal. Currently supported actions are:
c
Csig
s
Ssig
The optional addr argument normally associated with these packets is
not supported in vCont
.
Reply: See section D.3 Stop Reply Packets, for the reply specifications.
vCont?
-- extended resume query
Query support for the vCont
packet.
Reply:
vCont
[;action]...'
vCont
packet is supported. Each action is a supported
command in the vCont
packet.
vCont
packet is not supported.
V
-- reserved
Reserved for future use.
w
-- reserved
Reserved for future use.
W
-- reserved
Reserved for future use.
x
-- reserved
Reserved for future use.
X
addr,
length:XX... -- write mem (binary)
addr is address, length is number of bytes, XX...
is binary data. The characters $
, #
, and 0x7d
are
escaped using 0x7d
.
Reply:
y
-- reserved
Reserved for future use.
Y
reserved
Reserved for future use.
z
type,
addr,
length -- remove breakpoint or watchpoint (draft)
Z
type,
addr,
length -- insert breakpoint or watchpoint (draft)
Insert (Z
) or remove (z
) a type breakpoint or
watchpoint starting at address address and covering the next
length bytes.
Each breakpoint and watchpoint packet type is documented separately.
Implementation notes: A remote target shall return an empty string
for an unrecognized breakpoint or watchpoint packet type. A
remote target shall support either both or neither of a given
Z
type... and z
type... packet pair. To
avoid potential problems with duplicate packets, the operations should
be implemented in an idempotent way.
z
0
,
addr,
length -- remove memory breakpoint (draft)
Z
0
,
addr,
length -- insert memory breakpoint (draft)
Insert (Z0
) or remove (z0
) a memory breakpoint at address
addr
of size length
.
A memory breakpoint is implemented by replacing the instruction at
addr with a software breakpoint or trap instruction. The
length
is used by targets that indicates the size of the
breakpoint (in bytes) that should be inserted (e.g., the ARM and
MIPS can insert either a 2 or 4 byte breakpoint).
Implementation note: It is possible for a target to copy or move code that contains memory breakpoints (e.g., when implementing overlays). The behavior of this packet, in the presence of such a target, is not defined.
Reply:
z
1
,
addr,
length -- remove hardware breakpoint (draft)
Z
1
,
addr,
length -- insert hardware breakpoint (draft)
Insert (Z1
) or remove (z1
) a hardware breakpoint at
address addr
of size length
.
A hardware breakpoint is implemented using a mechanism that is not dependant on being able to modify the target's memory.
Implementation note: A hardware breakpoint is not affected by code movement.
Reply:
z
2
,
addr,
length -- remove write watchpoint (draft)
Z
2
,
addr,
length -- insert write watchpoint (draft)
Insert (Z2
) or remove (z2
) a write watchpoint.
Reply:
z
3
,
addr,
length -- remove read watchpoint (draft)
Z
3
,
addr,
length -- insert read watchpoint (draft)
Insert (Z3
) or remove (z3
) a read watchpoint.
Reply:
z
4
,
addr,
length -- remove access watchpoint (draft)
Z
4
,
addr,
length -- insert access watchpoint (draft)
Insert (Z4
) or remove (z4
) an access watchpoint.
Reply:
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
The `C', `c', `S', `s' and `?' packets can receive any of the below as a reply. In the case of the `C', `c', `S' and `s' packets, that reply is only returned when the target halts. In the below the exact meaning of `signal number' is poorly defined. In general one of the UNIX signal numbering conventions is used.
T
AAn...:
r...;
n...:
r...;
n...:
r...;
'
AA = two hex digit signal number; n... = register number
(hex), r... = target byte ordered register contents, size defined
by DEPRECATED_REGISTER_RAW_SIZE
; n... = `thread',
r... = thread process ID, this is a hex integer; n... =
(`watch' | `rwatch' | `awatch', r... = data
address, this is a hex integer; n... = other string not starting
with valid hex digit. GDB should ignore this n...,
r... pair and go on to the next. This way we can extend the
protocol.
The process exited, and AA is the exit status. This is only applicable to certain targets.
The process terminated with signal AA.
XX... is hex encoding of ASCII data. This can happen at any time while the program is running and the debugger should continue to wait for `W', `T', etc.
,
parameter...'
call-id is the identifier which says which host system call should be called. This is just the name of the function. Translation into the correct system call is only applicable as it's defined in GDB. See section D.7 File-I/O remote protocol extension, for a list of implemented system calls.
parameter... is a list of parameters as defined for this very system call.
The target replies with this packet when it expects GDB to call
a host system call on behalf of the target. GDB replies with
an appropriate F
packet and keeps up waiting for the next reply
packet from the target. The latest `C', `c', `S' or
`s' action is expected to be continued.
See section D.7 File-I/O remote protocol extension, for more details.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
The following set and query packets have already been defined.
q
C
-- current thread
Return the current thread id.
Reply:
QC
pid'
q
fThreadInfo
-- all thread ids
q
sThreadInfo
Obtain a list of active thread ids from the target (OS). Since there
may be too many active threads to fit into one reply packet, this query
works iteratively: it may require more than one query/reply sequence to
obtain the entire list of threads. The first query of the sequence will
be the qf
ThreadInfo
query; subsequent queries in the
sequence will be the qs
ThreadInfo
query.
NOTE: replaces the qL
query (see below).
Reply:
m
id'
m
id,id...'
l
'
In response to each query, the target will reply with a list of one or
more thread ids, in big-endian hex, separated by commas. GDB
will respond to each reply with a request for more thread ids (using the
qs
form of the query), until the target responds with l
(lower-case el, for 'last'
).
q
ThreadExtraInfo
,
id -- extra thread info
Where 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 GDB to tell the user about the thread. The string is displayed in GDB's `info threads' display. Some examples of possible thread extra info strings are "Runnable", or "Blocked on Mutex".
Reply:
q
L
startflagthreadcountnextthread -- query LIST or threadLIST (deprecated)
Obtain thread information from RTOS. Where: startflag (one hex digit) is one to indicate the first query and zero to indicate a subsequent query; threadcount (two hex digits) is the maximum number of threads the response packet can contain; and nextthread (eight hex digits), for subsequent queries (startflag is zero), is returned in the response as argthread.
NOTE: this query is replaced by the q
fThreadInfo
query
(see above).
Reply:
q
M
countdoneargthreadthread...'
remote.c:parse_threadlist_response()
.
q
CRC:
addr,
length -- compute CRC of memory block
Reply:
E
NN'
C
CRC32'
q
Offsets
-- query sect offs
Get section offsets that the target used when re-locating the downloaded
image. Note: while a Bss
offset is included in the
response, GDB ignores this and instead applies the Data
offset to the Bss
section.
Reply:
Text=
xxx;Data=
yyy;Bss=
zzz'
q
P
modethreadid -- thread info request
Returns information on threadid. Where: mode is a hex encoded 32 bit mode; threadid is a hex encoded 64 bit thread ID.
Reply:
See remote.c:remote_unpack_thread_info_response()
.
q
Rcmd,
command -- remote command
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 O
output console output packets.
Implementors should note that providing access to a stubs's
interpreter may have security implications.
Reply:
E
NN'
qSymbol::
-- symbol lookup
Notify the target that GDB is prepared to serve symbol lookup requests. Accept requests from the target for the values of symbols.
Reply:
OK
'
qSymbol:
sym_name'
qSymbol:
sym_value:sym_name message, described below.
qSymbol:
sym_value:sym_name -- symbol value
Set the value of sym_name to sym_value.
sym_name (hex encoded) is the name of a symbol whose value the target has previously requested.
sym_value (hex) is the value for symbol sym_name. If GDB cannot supply a value for sym_name, then this field will be empty.
Reply:
OK
'
qSymbol:
sym_name'
qPart
:object:read
:annex:offset,length -- read special data
Read uninterpreted bytes from the target's special data area
identified by the keyword object
.
Request length bytes starting at offset bytes into the data.
The content and encoding of annex is specific to the object;
it can supply additional details about what data to access.
Here are the specific requests of this form defined so far.
All `qPart
:object:read
:...'
requests use the same reply formats, listed below.
qPart
:auxv
:read
::offset,length
Reply:
OK
E00
E
nn
errno
value.
""
(empty)
qPart
:object:write
:annex:offset:data...
Write uninterpreted bytes into the target's special data area
identified by the keyword object
,
starting at offset bytes into the data.
data... is the hex-encoded data to be written.
The content and encoding of annex is specific to the object;
it can supply additional details about what data to access.
No requests of this form are presently in use. This specification serves as a placeholder to document the common format that new specific request specifications ought to use.
Reply:
E00
E
nn
errno
value.
""
(empty)
qPart
:object:operation:...
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
The following `g'/`G' packets have previously been defined. In the below, some thirty-two bit registers are transferred as sixty-four bits. Those registers should be zero/sign extended (which?) to fill the space allocated. Register bytes are transfered in target byte order. The two nibbles within a register byte are transfered most-significant - least-significant.
All registers are transfered as thirty-two bit quantities in the order: 32 general-purpose; sr; lo; hi; bad; cause; pc; 32 floating-point registers; fsr; fir; fp.
All registers are transfered as sixty-four bit quantities (including
thirty-two bit registers such as sr
). The ordering is the same
as MIPS32
.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Example sequence of a target being re-started. Notice how the restart does not get any direct output:
-> |
Example sequence of a target being stepped by a single instruction:
-> |
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
The File I/O remote protocol extension (short: File-I/O) allows the target to use the hosts file system and console I/O when calling various system calls. System calls on the target system are translated into a remote protocol packet to the host system which then performs the needed actions and returns with an adequate response packet to the target system. This simulates file system operations even on targets that lack file systems.
The protocol is defined host- and target-system independent. It uses it's own independent representation of datatypes and values. Both, GDB and the target's GDB stub are responsible for translating the system dependent values into the unified protocol values when data is transmitted.
The communication is synchronous. A system call is possible only when GDB is waiting for the `C', `c', `S' or `s' packets. While GDB handles the request for a system call, the target is stopped to allow deterministic access to the target's memory. Therefore File-I/O is not interuptible by target signals. It is possible to interrupt File-I/O by a user interrupt (Ctrl-C), though.
The target's request to perform a host system call does not finish the latest `C', `c', `S' or `s' action. That means, after finishing the system call, the target returns to continuing the previous activity (continue, step). No additional continue or step request from GDB is required.
(gdb) continue <- target requests 'system call X' target is stopped, GDB executes system call -> GDB returns result ... target continues, GDB returns to wait for the target <- target hits breakpoint and sends a Txx packet |
The protocol is only used for files on the host file system and for I/O on the console. Character or block special devices, pipes, named pipes or sockets or any other communication method on the host system are not supported by this protocol.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
The File-I/O protocol uses the F
packet, as request as well
as as reply packet. Since a File-I/O system call can only occur when
GDB is waiting for the continuing or stepping target, the
File-I/O request is a reply that GDB has to expect as a result
of a former `C', `c', `S' or `s' packet.
This F
packet contains all information needed to allow GDB
to call the appropriate host system call:
At that point GDB has to perform the following actions.
m
packet request. This additional communication has to be
expected by the target implementation and is handled as any other m
packet.
M
or X
packet. This packet has to be expected
by the target implementation and is handled as any other M
or X
packet.
Eventually GDB replies with another F
packet which contains all
necessary information for the target to continue. This at least contains
errno
, if has been changed by the system call.
After having done the needed type and value coercion, the target continues the latest continue or step action.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
F
request packet
The F
request packet has the following format:
|
Parameters are hexadecimal integer values, either the real values in case of scalar datatypes, as pointers to target buffer space in case of compound datatypes and unspecified memory areas or as pointer/length pairs in case of string parameters. These are appended to the call-id, each separated from its predecessor by a comma. All values are transmitted in ASCII string representation, pointer/length pairs separated by a slash.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
F
reply packet
The F
reply packet has the following format:
|
F0,0,C |
F-1,4,C |
EINTR
.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Structured data which is transferred using a memory read or write as e.g.
a struct stat
is expected to be in a protocol specific format with
all scalar multibyte datatypes being big endian. This should be done by
the target before the F
packet is sent resp. by GDB before
it transfers memory to the target. Transferred pointers to structured
data should point to the already coerced data at any time.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
A special case is, if the Ctrl-C flag is set in the GDB
reply packet. In this case the target should behave, as if it had
gotten a break message. The meaning for the target is "system call
interupted by SIGINT
". Consequentially, the target should actually stop
(as with a break message) and return to GDB with a T02
packet. In this case, it's important for the target to know, in which
state the system call was interrupted. Since this action is by design
not an atomic operation, we have to differ between two cases:
These two states can be distinguished by the target by the value of the
returned errno
. If it's the protocol representation of EINTR
, the system
call hasn't been performed. This is equivalent to the EINTR
handling
on POSIX systems. In any other case, the target may presume that the
system call has been finished -- successful or not -- and should behave
as if the break message arrived right after the system call.
GDB must behave reliable. If the system call has not been called
yet, GDB may send the F
reply immediately, setting EINTR
as
errno
in the packet. If the system call on the host has been finished
before the user requests a break, the full action must be finshed by
GDB. This requires sending M
or X
packets as they fit.
The F
packet may only be send when either nothing has happened
or the full action has been completed.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
By default and if not explicitely closed by the target system, the file
descriptors 0, 1 and 2 are connected to the GDB console. Output
on the GDB console is handled as any other file output operation
(write(1, ...)
or write(2, ...)
). Console input is handled
by GDB so that after the target read request from file descriptor
0 all following typing is buffered until either one of the following
conditions is met:
read
system call is treated as finished.
If the user has typed more characters as fit in the buffer given to
the read call, the trailing characters are buffered in GDB until
either another read(0, ...)
is requested by the target or debugging
is stopped on users request.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
A special case in this protocol is the library call isatty
which
is implemented as it's own call inside of this protocol. It returns
1 to the target if the file descriptor given as parameter is attached
to the GDB console, 0 otherwise. Implementing through system calls
would require implementing ioctl
and would be more complex than
needed.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
The other special case in this protocol is the system
call which
is implemented as it's own call, too. GDB is taking over the full
task of calling the necessary host calls to perform the system
call. The return value of system
is simplified before it's returned
to the target. Basically, the only signal transmitted back is EINTR
in case the user pressed Ctrl-C. Otherwise the return value consists
entirely of the exit status of the called command.
Due to security concerns, the system
call is refused to be called
by GDB by default. The user has to allow this call explicitly by
entering
set remote system-call-allowed 1
'
Disabling the system
call is done by
set remote system-call-allowed 0
'
The current setting is shown by typing
show remote system-call-allowed
'
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
open close read write lseek rename unlink stat/fstat gettimeofday isatty system
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Synopsis: int open(const char *pathname, int flags); int open(const char *pathname, int flags, mode_t mode); Request: Fopen,pathptr/len,flags,mode |
flags
is the bitwise or of the following values:
O_CREAT
O_EXCL
O_TRUNC
O_APPEND
O_RDONLY
O_WRONLY
O_RDWR
Each other bit is silently ignored.
mode
is the bitwise or of the following values:
S_IRUSR
S_IWUSR
S_IRGRP
S_IWGRP
S_IROTH
S_IWOTH
Each other bit is silently ignored.
Return value: open returns the new file descriptor or -1 if an error occured. Errors: |
EEXIST
EISDIR
EACCES
ENAMETOOLONG
ENOENT
ENODEV
EROFS
EFAULT
ENOSPC
EMFILE
ENFILE
EINTR
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Synopsis: int close(int fd); Request: Fclose,fd Return value: close returns zero on success, or -1 if an error occurred. Errors: |
EBADF
EINTR
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Synopsis: int read(int fd, void *buf, unsigned int count); Request: Fread,fd,bufptr,count Return value: On success, the number of bytes read is returned. Zero indicates end of file. If count is zero, read returns zero as well. On error, -1 is returned. Errors: |
EBADF
EFAULT
EINTR
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Synopsis: int write(int fd, const void *buf, unsigned int count); Request: Fwrite,fd,bufptr,count Return value: On success, the number of bytes written are returned. Zero indicates nothing was written. On error, -1 is returned. Errors: |
EBADF
EFAULT
EFBIG
ENOSPC
EINTR
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Synopsis: long lseek (int fd, long offset, int flag); Request: Flseek,fd,offset,flag |
flag
is one of:
SEEK_SET
SEEK_CUR
SEEK_END
Return value: On success, the resulting unsigned offset in bytes from the beginning of the file is returned. Otherwise, a value of -1 is returned. Errors: |
EBADF
ESPIPE
EINVAL
EINTR
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Synopsis: int rename(const char *oldpath, const char *newpath); Request: Frename,oldpathptr/len,newpathptr/len Return value: On success, zero is returned. On error, -1 is returned. Errors: |
EISDIR
EEXIST
EBUSY
EINVAL
ENOTDIR
EFAULT
EACCES
ENAMETOOLONG
oldpath or newpath was too long.
ENOENT
EROFS
ENOSPC
EINTR
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Synopsis: int unlink(const char *pathname); Request: Funlink,pathnameptr/len Return value: On success, zero is returned. On error, -1 is returned. Errors: |
EACCES
EPERM
EBUSY
EFAULT
ENAMETOOLONG
ENOENT
ENOTDIR
EROFS
EINTR
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Synopsis: int stat(const char *pathname, struct stat *buf); int fstat(int fd, struct stat *buf); Request: Fstat,pathnameptr/len,bufptr Ffstat,fd,bufptr Return value: On success, zero is returned. On error, -1 is returned. Errors: |
EBADF
ENOENT
ENOTDIR
EFAULT
EACCES
ENAMETOOLONG
EINTR
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Synopsis: int gettimeofday(struct timeval *tv, void *tz); Request: Fgettimeofday,tvptr,tzptr Return value: On success, 0 is returned, -1 otherwise. Errors: |
EINVAL
EFAULT
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Synopsis: int isatty(int fd); Request: Fisatty,fd Return value: Returns 1 if fd refers to the GDB console, 0 otherwise. Errors: |
EINTR
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Synopsis: int system(const char *command); Request: Fsystem,commandptr/len Return value: The value returned is -1 on error and the return status of the command otherwise. Only the exit status of the command is returned, which is extracted from the hosts system return value by calling WEXITSTATUS(retval). In case /bin/sh could not be executed, 127 is returned. Errors: |
EINTR
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Integral datatypes Pointer values struct stat struct timeval
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
The integral datatypes used in the system calls are
int, unsigned int, long, unsigned long, mode_t and time_t |
Int
, unsigned int
, mode_t
and time_t
are
implemented as 32 bit values in this protocol.
Long
and unsigned long
are implemented as 64 bit types.
See section Limits, for corresponding MIN and MAX values (similar to those in `limits.h') to allow range checking on host and target.
time_t
datatypes are defined as seconds since the Epoch.
All integral datatypes transferred as part of a memory read or write of a
structured datatype e.g. a struct stat
have to be given in big endian
byte order.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Pointers to target data are transmitted as they are. An exception is made for pointers to buffers for which the length isn't transmitted as part of the function call, namely strings. Strings are transmitted as a pointer/length pair, both as hex values, e.g.
|
which is a pointer to data of length 18 bytes at position 0x1aaf. The length is defined as the full string length in bytes, including the trailing null byte. Example:
``hello, world'' at address 0x123456 |
is transmitted as
|
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
The buffer of type struct stat used by the target and GDB is defined as follows:
struct stat { unsigned int st_dev; /* device */ unsigned int st_ino; /* inode */ mode_t st_mode; /* protection */ unsigned int st_nlink; /* number of hard links */ unsigned int st_uid; /* user ID of owner */ unsigned int st_gid; /* group ID of owner */ unsigned int st_rdev; /* device type (if inode device) */ unsigned long st_size; /* total size, in bytes */ unsigned long st_blksize; /* blocksize for filesystem I/O */ unsigned long st_blocks; /* number of blocks allocated */ time_t st_atime; /* time of last access */ time_t st_mtime; /* time of last modification */ time_t st_ctime; /* time of last change */ }; |
The integral datatypes are conforming to the definitions given in the approriate section (see Integral datatypes, for details) so this structure is of size 64 bytes.
The values of several fields have a restricted meaning and/or range of values.
st_dev: 0 file 1 console st_ino: No valid meaning for the target. Transmitted unchanged. st_mode: Valid mode bits are described in Appendix C. Any other bits have currently no meaning for the target. st_uid: No valid meaning for the target. Transmitted unchanged. st_gid: No valid meaning for the target. Transmitted unchanged. st_rdev: No valid meaning for the target. Transmitted unchanged. st_atime, st_mtime, st_ctime: These values have a host and file system dependent accuracy. Especially on Windows hosts the file systems don't support exact timing values. |
The target gets a struct stat of the above representation and is responsible to coerce it to the target representation before continuing.
Note that due to size differences between the host and target representation of stat members, these members could eventually get truncated on the target.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
The buffer of type struct timeval used by the target and GDB is defined as follows:
struct timeval { time_t tv_sec; /* second */ long tv_usec; /* microsecond */ }; |
The integral datatypes are conforming to the definitions given in the approriate section (see Integral datatypes, for details) so this structure is of size 8 bytes.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
The following values are used for the constants inside of the protocol. GDB and target are resposible to translate these values before and after the call as needed.
Open flags mode_t values Errno values Lseek flags Limits
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
All values are given in hexadecimal representation.
O_RDONLY 0x0 O_WRONLY 0x1 O_RDWR 0x2 O_APPEND 0x8 O_CREAT 0x200 O_TRUNC 0x400 O_EXCL 0x800 |
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
All values are given in octal representation.
S_IFREG 0100000 S_IFDIR 040000 S_IRUSR 0400 S_IWUSR 0200 S_IXUSR 0100 S_IRGRP 040 S_IWGRP 020 S_IXGRP 010 S_IROTH 04 S_IWOTH 02 S_IXOTH 01 |
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
All values are given in decimal representation.
EPERM 1 ENOENT 2 EINTR 4 EBADF 9 EACCES 13 EFAULT 14 EBUSY 16 EEXIST 17 ENODEV 19 ENOTDIR 20 EISDIR 21 EINVAL 22 ENFILE 23 EMFILE 24 EFBIG 27 ENOSPC 28 ESPIPE 29 EROFS 30 ENAMETOOLONG 91 EUNKNOWN 9999 |
EUNKNOWN is used as a fallback error value if a host system returns any error value not in the list of supported error numbers.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
SEEK_SET 0 SEEK_CUR 1 SEEK_END 2 |
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
All values are given in decimal representation.
INT_MIN -2147483648 INT_MAX 2147483647 UINT_MAX 4294967295 LONG_MIN -9223372036854775808 LONG_MAX 9223372036854775807 ULONG_MAX 18446744073709551615 |
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Example sequence of a write call, file descriptor 3, buffer is at target address 0x1234, 6 bytes should be written:
<- |
Example sequence of a read call, file descriptor 3, buffer is at target address 0x1234, 6 bytes should be read:
<- |
Example sequence of a read call, call fails on the host due to invalid file descriptor (EBADF):
<- |
Example sequence of a read call, user presses Ctrl-C before syscall on host is called:
<- |
Example sequence of a read call, user presses Ctrl-C after syscall on host is called:
<- |
[ << ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |