Host I/O Packets (Debugging with GDB)
Next: Interrupts, Previous: Tracepoint Packets, Up: Remote Protocol [Contents][Index]
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. See 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 ofparameter
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 (see 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 (see 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 (see Binary Data). See the individual packet documentation for the interpretation ofresult
andattachment
.- ‘
’
- 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. Thefilename
is a string,flags
is an integer indicating a mask of open flags (see Open Flags), andmode
is an integer indicating a mask of mode bits to use if the file is created (see mode_t Values). See 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 tocount
bytes will be read from the file, starting atoffset
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 ifcount
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 tofd
. Start the write atoffset
from the start of the file. Unlike manywrite
system calls, there is no separatecount
argument; the length ofdata
in the packet is used. ‘vFile:pwrite
’ returns the number of bytes written, which may be shorter than the length ofdata
, 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. Thefilename
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 withfilename
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 processpid
. Ifpid
is zero, select the filesystem as seen by the remote stub. Return 0 on success, or -1 if an error occurs. IfvFile:setfs:
indicates success, the selected filesystem remains selected until the next successfulvFile:setfs:
operation.
Next: Interrupts, Previous: Tracepoint Packets, Up: Remote Protocol [Contents][Index]