gdb: Host I/O Packets
E.7 Host I/O Packets
====================
The "Host I/O" packets allow GDB 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 GDB, and the target's memory is not involved. 
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:
'vFile:OPERATION: PARAMETER...'
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 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 (Binary Data).
The valid responses to Host I/O packets are:
'F RESULT [, ERRNO] [; ATTACHMENT]'
RESULT is the integer value returned by this operation, usually
non-negative for success and -1 for errors. If an error has
occured, ERRNO will be included in the result specifying a value
defined by the File-I/O protocol (Errno Values). For
operations which return data, ATTACHMENT supplies the data as a
binary buffer. Binary buffers in response packets are escaped in
the normal way (Binary Data). See the individual packet
documentation for the interpretation of RESULT and ATTACHMENT.
''
An empty response indicates that this operation is not recognized.
These are the supported Host I/O operations:
'vFile:open: FILENAME, FLAGS, MODE'
Open a file at FILENAME and return a file descriptor for it, or
return -1 if an error occurs. The FILENAME is a string, FLAGS is
an integer indicating a mask of open flags (Open Flags),
and MODE is an integer indicating a mask of mode bits to use if the
file is created (mode_t Values). open, for details
of the open flags and mode values.
'vFile:close: FD'
Close the open file corresponding to FD and return 0, or -1 if an
error occurs.
'vFile:pread: FD, COUNT, OFFSET'
Read data from the open file corresponding to FD. Up to COUNT
bytes will be read from the file, starting at 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 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.
'vFile:pwrite: FD, OFFSET, DATA'
Write DATA (a binary buffer) to the open file corresponding to FD.
Start the write at OFFSET from the start of the file. Unlike many
'write' system calls, there is no separate COUNT argument; the
length of DATA in the packet is used. 'vFile:write' returns the
number of bytes written, which may be shorter than the length of
DATA, or -1 if an error occurred.
'vFile:fstat: FD'
Get information about the open file corresponding to FD. On
success the information is returned as a binary attachment and the
return value is the size of this attachment in bytes. If an error
occurs the return value is -1. The format of the returned binary
attachment is as described in struct stat.
'vFile:unlink: FILENAME'
Delete the file at FILENAME on the target. Return 0, or -1 if an
error occurs. The FILENAME is a string.
'vFile:readlink: FILENAME'
Read value of symbolic link FILENAME on the target. Return the
number of bytes read, or -1 if an error occurs.
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.
'vFile:setfs: PID'
Select the filesystem on which 'vFile' operations with FILENAME
arguments will operate. This is required for GDB to be able to
access files on remote targets where the remote stub does not share
a common filesystem with the inferior(s).
If PID is nonzero, select the filesystem as seen by process PID.
If PID is zero, select the filesystem as seen by the remote stub.
Return 0 on success, or -1 if an error occurs. If 'vFile:setfs:'
indicates success, the selected filesystem remains selected until
the next successful 'vFile:setfs:' operation.
Info Catalog
gdb: Tracepoint Packets
gdb: Remote Protocol
gdb: Interrupts