Index: doc/gdb.texinfo =================================================================== RCS file: /cvs/src/src/gdb/doc/gdb.texinfo,v retrieving revision 1.131 diff -u -p -r1.131 gdb.texinfo --- doc/gdb.texinfo 11 Oct 2002 16:13:15 -0000 1.131 +++ doc/gdb.texinfo 21 Nov 2002 08:42:04 -0000 @@ -14838,6 +14838,7 @@ Takes an optional file parameter. * Stop Reply Packets:: * General Query Packets:: * Register Packet Format:: +* File-I/O remote protocol extension:: * Examples:: @end menu @@ -15063,9 +15064,12 @@ Reserved for future use. Reserved for future use. -@item @code{F} --- reserved +@item @code{F}@var{RC}@code{,}@var{EE}@code{,}@var{CF}@code{;}@var{XX} --- Reply to target's F packet. +@cindex @code{F} packet -Reserved for future use. +This packet is send by @value{GDBN} as reply to a @code{F} request packet +sent by the target. This is part of the File-I/O protocol extension. +@xref{File-I/O remote protocol extension}, for the specification. @item @code{g} --- read registers @anchor{read registers packet} @@ -15564,6 +15568,24 @@ is a query initiated by the host debugge any time while the program is running and the debugger should continue to wait for @samp{W}, @samp{T}, etc. +@item F@var{call-id}@code{,}@var{parameter@dots{}} + +@var{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 @value{GDBN}. +@xref{File-I/O remote protocol extension}, for a list of implemented +system calls. + +@var{parameter@dots{}} is a list of parameters as defined for this very +system call. + +The target replies with this packet when it expects @value{GDBN} to call +a host system call on behalf of the target. @value{GDBN} replies with +an appropriate @code{F} packet and keeps up waiting for the next reply +packet from the target. The latest @samp{C}, @samp{c}, @samp{S} or +@samp{s} action is expected to be continued. +@xref{File-I/O remote protocol extension}, for more details. + @end table @node General Query Packets @@ -15773,6 +15795,892 @@ thirty-two bit registers such as @code{s as @code{MIPS32}. @end table + +@node File-I/O remote protocol extension +@section File-I/O remote protocol extension + +@menu +* File-I/O Overview:: +* Protocol basics:: +* The @code{F} request packet:: +* The @code{F} reply packet:: +* Memory transfer:: +* The Ctrl-C message:: +* Console I/O:: +* The isatty(3) call:: +* The system(3) call:: +* List of supported calls:: +* Protocol specific representation of datatypes:: +* Constants:: +@end menu + +@node File-I/O Overview +@subsection File-I/O Overview + +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 file system-less targets. + +The protocol is defined host- and target-system independent. It uses +it's own independent representation of datatypes and values. Both, +@value{GDBN} and the target's @value{GDBN} 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 @samp{C}, @samp{c}, @samp{S} or @samp{s} +packets. While @value{GDBN} 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 @samp{C}, @samp{c}, @samp{S} or @samp{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 @value{GDBN} is required. + +@smallexample +(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 +@end smallexample + +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. + +@node Protocol basics +@subsection Protocol basics + +The File-I/O protocol uses the @code{F} packet, as request as well +as as reply packet. Since a File-I/O system call can only occur when +@value{GDBN} is waiting for the continuing or stepping target, the +File-I/O request is a reply that @value{GDBN} has to expect as a result +of a former @samp{C}, @samp{c}, @samp{S} or @samp{s} packet. +This @code{F} packet contains all information needed to allow @value{GDBN} +to call the appropriate host system call: + +@itemize @bullet +@item +A unique identifier for the requested system call. + +@item +All parameters to the system call. Pointers are given as addresses +into the target memory. Pointers to strings are given as pointer/length +pair. Numerical values are given as they are. Numerical control values +are given in a protocol specific representation. + +@end itemize + +At that point @value{GDBN} has to perform the following actions. + +@itemize @bullet +@item +If parameter pointer values are given, which point to data needed as input +to a system call, @value{GDBN} requests this data from the target with a +standard @code{m} packet request. This additional communication has to be +expected by the target implementation and is handled as any other @code{m} +packet. + +@item +Translating all values from protocol representation to host representation +as needed. Datatypes are coerced into the host types. + +@item +Call system call. + +@item +Coerce datatypes back to protocol representation. + +@item +If pointer parameters in the request packet point to buffer space in which +a system call is expected to copy data to, the data is transmitted to the +target using a @code{M} packet. This packet has to be expected by the +target implementation and is handled as any other @code{M} packet. + +@end itemize + +Eventually GDB replies with another @code{F} packet which contains all +necessary information for the target to continue. This at least contains + +@itemize @bullet +@item +Return value. + +@item +Errno, if has been changed by the system call. + +@item +"Ctrl-C" flag. + +@end itemize + +After having done the needed type and value coercion, the target continues +the latest continue or step action. + +@node The @code{F} request packet +@subsection The @code{F} request packet + +The @code{F} request packet has the following format: + +@table @samp +@item @code{F}@var{call-id}@code{,}@var{parameter@dots{}} + +@var{call-id} is the identifier to indicate the host system call to be called. +This is just the name of the function. + +@var{parameter@dots{}} are the parameters to the system call. + +@end table + +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. + +@node The @code{F} reply packet +@subsection The @code{F} reply packet + +The @code{F} reply packet has the following format: +@table @samp +@item @code{F}@var{retcode}@code{,}@var{errno}@code{,}@var{Ctrl-C flag}@code{;}@var{call specific attachment} + +@var{retcode} is the return code of the system call as hexadecimal value. + +@var{errno} is the errno set by the call, in protocol specific representation. +This parameter can be omitted if the call was successful. + +@var{Ctrl-C flag} is only send if the user requested a break. In this +case, @var{errno} must be send as well, even if the call was successful. +The @var{Ctrl-C flag} itself consists of the character 'C': + +@smallexample +F0,0,C +@end smallexample + +or, if the call was interupted before the host call has been performed: + +@smallexample +F-1,4,C +@end smallexample + +assuming 4 is the protocol specific representation of EINTR. + +@end table + +@node Memory transfer +@subsection Memory transfer + +Structured data which is transferred using a memory read or write as e. g. +a @code{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 @code{F} packet is sent resp. by @value{GDBN} before +it transfers memory to the target. Transferred pointers to structured +data should point to the already coerced data at any time. + +@node The Ctrl-C message +@subsection The Ctrl-C message + +A special case is, if the @var{Ctrl-C flag} is set in the @value{GDBN} +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 @value{GDBN} with a @code{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: + +@itemize @bullet +@item +The system call hasn't been performed on the host yet. + +@item The system call on the host has been finished. + +@end itemize + +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. + +@value{GDBN} must behave reliable. If the system call has not been called +yet, @value{GDBN} 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 +@value{GDBN}. This requires sending @code{M} packets as they fit. +The @code{F} packet may only be send when either nothing has happened +or the full action has been completed. + +@node Console I/O +@subsection Console I/O + +By default and if not explicitely closed by the target system, the file +descriptors 0, 1 and 2 are connected to the @value{GDBN} console. Output +on the @value{GDBN} console is handled as any other file output operation +(@code{write(1, ...)} or @code{write(2, ...)}). Console input is handled +by @value{GDBN} 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: + +@itemize @bullet +@item +The user presses Ctrl-C. The behaviour is as explained above, the read() +system call is treated as finished. + +@item +The user presses . This is treated as end of input with a trailing +line feed. + +@item +The user presses Ctrl-D. This is treated as end of input. No trailing +character, especially no Ctrl-D is appended to the input. + +@end itemize + +If the user has typed more characters as fit in the buffer given to +the read call, the trailing characters are buffered in @value{GDBN} until +either another @code{read(0, ...)} is requested by the target or debugging +is stopped on users request. + +@node The isatty(3) call +@subsection The isatty(3) call + +A special case in this protocol is the library call isatty(3) 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. + +@node The system(3) call +@subsection The system(3) call + +The other special case in this protocol is the system(3) call which +is implemented as it's own call, too. @value{GDBN} is taking over the full +task of calling the necessary host calls to perform the system(3) +call. The return value of system(3) 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(3) call is refused to be called +by @value{GDBN}. The user has to allow this call explicitely by +entering + +@table @samp +@item @code{set remote system-call-allowed 1} +@end table + +Disabling the system(3) call is done by + +@table @samp +@item @code{set remote system-call-allowed 0} +@end table + +The current setting is shown by typing + +@table @samp +@item @code{show remote system-call-allowed} +@end table + +@node List of supported calls +@subsection List of supported calls + +@menu +* open:: +* close:: +* read:: +* write:: +* lseek:: +* rename:: +* unlink:: +* stat/fstat:: +* gettimeofday:: +* isatty:: +* system:: +@end menu + +@node open +@unnumberedsubsubsec open + +@smallexample +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 If the file does not exist it will be created. The host + rules apply as far as file ownership and time stamps + are concerned. + + O_EXCL When used with O_CREAT, if the file already exists it is + an error and open() fails. + + O_TRUNC If the file already exists and the open mode allows + writing (O_RDWR or O_WRONLY is given) it will be + truncated to length 0. + + O_APPEND The file is opened in append mode. + + O_RDONLY The file is opened for reading only. + + O_WRONLY The file is opened for writing only. + + O_RDWR The file is opened for reading and writing. + + Each other bit is silently ignored. + + `mode' is the bitwise or of the following values: + + S_IRUSR User has read permission. + + S_IWUSR User has write permission. + + S_IRGRP Group has read permission. + + S_IWGRP Group has write permission. + + S_IROTH Others have read permission. + + S_IWOTH Others have write permission. + + Each other bit is silently ignored. + +Return value: open returns the new file descriptor or -1 if an error + occured. + +Errors: + + EEXIST pathname already exists and O_CREAT and O_EXCL were used. + + EISDIR pathname refers to a directory. + + EACCES The requested access is not allowed. + + ENAMETOOLONG + pathname was too long. + + ENOENT A directory component in pathname does not exist. + + ENODEV pathname refers to a device, pipe, named pipe or socket. + + EROFS pathname refers to a file on a read-only filesystem and + write access was requested. + + EFAULT pathname is an invalid pointer value. + + ENOSPC No space on device to create the file. + + EMFILE The process already has the maximum number of files open. + + ENFILE The limit on the total number of files open on the system + has been reached. + + EINTR The call was interrupted by the user. +@end smallexample + +@node close +@unnumberedsubsubsec close + +@smallexample +Synopsis: int close(int fd); + +Request: Fclose,fd + +Return value: close returns zero on success, or -1 if an error occurred. + +Errors: + + EBADF fd isn't a valid open file descriptor. + + EINTR The call was interrupted by the user. +@end smallexample + +@node read +@unnumberedsubsubsec read + +@smallexample +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 fd is not a valid file descriptor or is not open for + reading. + + EFAULT buf is an invalid pointer value. + + EINTR The call was interrupted by the user. +@end smallexample + +@node write +@unnumberedsubsubsec write + +@smallexample +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 fd is not a valid file descriptor or is not open for + writing. + + EFAULT buf is an invalid pointer value. + + EFBIG An attempt was made to write a file that exceeds the + host specific maximum file size allowed. + + ENOSPC No space on device to write the data. + + EINTR The call was interrupted by the user. +@end smallexample + +@node lseek +@unnumberedsubsubsec lseek + +@smallexample +Synopsis: long lseek (int fd, long offset, int flag); + +Request: Flseek,fd,offset,flag + +`flag' is one of: + + SEEK_SET The offset is set to offset bytes. + + SEEK_CUR The offset is set to its current location plus offset + bytes. + + SEEK_END The offset is set to the size of the file plus offset + bytes. + +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 fd is not a valid open file descriptor. + + ESPIPE fd is associated with the GDB console. + + EINVAL flag is not a proper value. + + EINTR The call was interrupted by the user. +@end smallexample + +@node rename +@unnumberedsubsubsec rename + +@smallexample +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 newpath is an existing directory, but oldpath is not a + directory. + + EEXIST newpath is a non-empty directory. + + EBUSY oldpath or newpath is a directory that is in use by some + process. + + EINVAL An attempt was made to make a directory a subdirectory + of itself. + + ENOTDIR A component used as a directory in oldpath or new + path is not a directory. Or oldpath is a directory + and newpath exists but is not a directory. + + EFAULT oldpathptr or newpathptr are invalid pointer values. + + EACCES No access to the file or the path of the file. + + ENAMETOOLONG + oldpath or newpath was too long. + + ENOENT A directory component in oldpath or newpath does not exist. + + EROFS The file is on a read-only filesystem. + + ENOSPC The device containing the file has no room for the new + directory entry. + + EINTR The call was interrupted by the user. +@end smallexample + +@node unlink +@unnumberedsubsubsec unlink + +@smallexample +Synopsis: int unlink(const char *pathname); + +Request: Funlink,pathnameptr/len + +Return value: On success, zero is returned. On error, -1 is returned. + +Errors: + + EACCES No access to the file or the path of the file. + + EPERM The system does not allow unlinking of directories. + + EBUSY The file pathname cannot be unlinked because it's + being used by another process. + + EFAULT pathnameptr is an invalid pointer value. + + ENAMETOOLONG + pathname was too long. + + ENOENT A directory component in pathname does not exist. + + ENOTDIR A component of the path is not a directory. + + EROFS The file is on a read-only filesystem. + + EINTR The call was interrupted by the user. +@end smallexample + +@node stat/fstat +@unnumberedsubsubsec stat/fstat + +@smallexample +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 fd is not a valid open file. + + ENOENT A directory component in pathname does not exist or the + path is an empty string. + + ENOTDIR A component of the path is not a directory. + + EFAULT pathnameptr is an invalid pointer value. + + EACCES No access to the file or the path of the file. + + ENAMETOOLONG + pathname was too long. + + EINTR The call was interrupted by the user. +@end smallexample + +@node gettimeofday +@unnumberedsubsubsec gettimeofday + +@smallexample +Synopsis: int gettimeofday(struct timeval *tv, void *tz); + +Request: Fgettimeofday,tvptr,tzptr + +Return value: On success, 0 is returned, -1 otherwise. + +Errors: + + EINVAL tz is a non-NULL pointer. + + EFAULT tvptr and/or tzptr is an invalid pointer value. +@end smallexample + +@node isatty +@unnumberedsubsubsec isatty + +@smallexample +Synopsis: int isatty(int fd); + +Request: Fisatty,fd + +Return value: Returns 1 if fd refers to the GDB console, 0 otherwise. + +Errors: + + EINTR The call was interrupted by the user. +@end smallexample + +@node system +@unnumberedsubsubsec system + +@smallexample +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 The call was interrupted by the user. +@end smallexample + +@node Protocol specific representation of datatypes +@subsection Protocol specific representation of datatypes + +@menu +* Integral datatypes:: +* Pointer values:: +* struct stat:: +* struct timeval:: +@end menu + +@node Integral datatypes +@unnumberedsubsubsec Integral datatypes + +The integral datatypes used in the system calls are + +@smallexample +int, unsigned int, long, unsigned long, mode_t and time_t +@end smallexample + +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. + +@xref{Limits}, for corresponding MIN and MAX values (similar to those +in limits.h) to allow range checking on host and target. + +@node Pointer values +@unnumberedsubsubsec Pointer values + +Pointers to target data is transmitted as they are. A difference +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. + +@smallexample +@code{1aaf/12} +@end smallexample + +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: + +@smallexample +"hello, world" at address 0x123456 +@end smallexample + +is transmitted as + +@smallexample +@code{123456/d} +@end smallexample + +@node struct stat +@unnumberedsubsubsec struct stat + +The buffer of type struct stat used by the target and GDB is defined +as follows: + +@smallexample +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 */ +@}; +@end smallexample + +The integral datatypes are conforming to the definition in B.1 so this +structure is of size 64 bytes. + +The values of several fields have a restricted meaning and/or +range of values. + +@smallexample +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. +@end smallexample + +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. + +@node struct timeval +@unnumberedsubsubsec struct timeval + +The buffer of type struct timeval used by the target and GDB is defined +as follows: + +@smallexample +struct timeval @{ + time_t tv_sec; /* second */ + long tv_usec; /* microsecond */ +@}; +@end smallexample + +The integral datatypes are conforming to the definition in B.1 so this +structure is of size 8 bytes. + +@node Constants +@subsection Constants + +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. + +@menu +* Open flags:: +* mode_t values:: +* Errno values:: +* Lseek flags:: +* Limits:: +@end menu + +@node Open flags +@unnumberedsubsubsec Open flags + +All values are given in hexadecimal representation. + +@smallexample + O_RDONLY 0 + O_WRONLY 1 + O_RDWR 2 + O_APPEND 8 + O_CREAT 200 + O_TRUNC 400 + O_EXCL 800 +@end smallexample + +@node mode_t values +@unnumberedsubsubsec mode_t values + +All values are given in octal representation. + +@smallexample + S_IFREG 100000 + S_IFDIR 40000 + S_IRUSR 400 + S_IWUSR 200 + S_IXUSR 100 + S_IRGRP 40 + S_IWGRP 20 + S_IXGRP 10 + S_IROTH 4 + S_IWOTH 2 + S_IXOTH 1 +@end smallexample + +@node Errno values +@unnumberedsubsubsec Errno values + +All values are given in decimal representation. + +@smallexample + 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 +@end smallexample + + EUNKNOWN is used as a fallback error value if a host system returns + any error value not in the list of supported error numbers. + +@node Lseek flags +@unnumberedsubsubsec Lseek flags + +@smallexample + SEEK_SET 0 + SEEK_CUR 1 + SEEK_END 2 +@end smallexample + +@node Limits +@unnumberedsubsubsec Limits + +All values are given in decimal representation. + +@smallexample + INT_MIN -2147483648 + INT_MAX 2147483647 + UINT_MAX 4294967295 + LONG_MIN -9223372036854775808 + LONG_MAX 9223372036854775807 + ULONG_MAX 18446744073709551615 +@end smallexample @node Examples @section Examples