? gdb.bt Index: gdb.texinfo =================================================================== RCS file: /cvs/src/src/gdb/doc/gdb.texinfo,v retrieving revision 1.337 diff -c -3 -p -r1.337 gdb.texinfo *** gdb.texinfo 9 Jun 2006 22:37:47 -0000 1.337 --- gdb.texinfo 10 Jun 2006 17:48:35 -0000 *************** program is considered running after the *** 12579,12585 **** @kindex show remote This section documents the configuration options available when debugging remote programs. For the options related to the File I/O ! extensions of the remote protocol, see @ref{The system call, system-call-allowed}. @table @code --- 12579,12585 ---- @kindex show remote This section documents the configuration options available when debugging remote programs. For the options related to the File I/O ! extensions of the remote protocol, see @ref{system, system-call-allowed}. @table @code *************** Example sequence of a target being stepp *** 23961,23971 **** * Protocol basics:: * The F request packet:: * The F reply packet:: - * Memory transfer:: * The Ctrl-C message:: * Console I/O:: - * The isatty call:: - * The system call:: * List of supported calls:: * Protocol specific representation of datatypes:: * Constants:: --- 23961,23968 ---- *************** Example sequence of a target being stepp *** 23977,24000 **** @cindex file-i/o overview The @dfn{File I/O remote protocol extension} (short: File-I/O) allows the ! target to use the host's 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 ! its 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, --- 23974,23998 ---- @cindex file-i/o overview The @dfn{File I/O remote protocol extension} (short: File-I/O) allows the ! target to use the host's file system and console I/O to perform 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 a response packet to the target system. This simulates file system operations even on targets that lack file systems. ! The protocol is defined to be independent of both the host and target systems. ! It uses its own internal representation of datatypes and values. Both @value{GDBN} and the target's @value{GDBN} stub are responsible for ! translating the system-dependent value representations into the internal ! protocol representations when data is transmitted. ! The communication is synchronous. A system call is possible only when ! @value{GDBN} is waiting for a response from 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 interruptible by target signals. On ! the other hand, it is possible to interrupt File-I/O by a user interrupt ! (Ctrl-C) within @value{GDBN}. 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, *************** request from @value{GDBN} is required. *** 24011,24030 **** <- 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 @cindex protocol basics, file-i/o ! 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: --- 24009,24028 ---- <- target hits breakpoint and sends a Txx packet @end smallexample ! The protocol only supports I/O on the console and to regular files on ! the host file system. Character or block special devices, pipes, ! named pipes, sockets or any other communication method on the host system are not supported by this protocol. @node Protocol basics @subsection Protocol basics @cindex protocol basics, file-i/o ! The File-I/O protocol uses the @code{F} packet as the request as well ! as reply packet. Since a File-I/O system call can only occur when ! @value{GDBN} is waiting for a response from the continuing or stepping target, ! the File-I/O request is a reply that @value{GDBN} has to expect as a result ! of a previous @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: *************** A unique identifier for the requested sy *** 24036,24051 **** All parameters to the system call. Pointers are given as addresses in the target memory address space. 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. --- 24034,24049 ---- All parameters to the system call. Pointers are given as addresses in the target memory address space. Pointers to strings are given as pointer/length pair. Numerical values are given as they are. ! Numerical control flags are given in a protocol specific representation. @end itemize ! At this point, @value{GDBN} has to perform the following actions. @itemize @bullet @item ! If the parameters include pointer values 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. *************** packet. *** 24055,24068 **** representation as needed. Datatypes are coerced into the host types. @item ! @value{GDBN} calls the system call @item It then coerces 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} or @code{X} packet. This packet has to be expected by the target implementation and is handled as any other @code{M} or @code{X} packet. --- 24053,24066 ---- representation as needed. Datatypes are coerced into the host types. @item ! @value{GDBN} calls the system call. @item It then coerces datatypes back to protocol representation. @item ! If the system call is expected to return data in buffer space specified ! by pointer parameters to the call, the data is transmitted to the target using a @code{M} or @code{X} packet. This packet has to be expected by the target implementation and is handled as any other @code{M} or @code{X} packet. *************** the latest continue or step action. *** 24095,24118 **** The @code{F} request packet has the following format: @table @samp ! ! @smallexample ! @code{F}@var{call-id}@code{,}@var{parameter@dots{}} ! @end smallexample @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 F reply packet @subsection The @code{F} reply packet --- 24093,24114 ---- The @code{F} request packet has the following format: @table @samp ! @item F@var{call-id},@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. ! Parameters are hexadecimal integer values, either the actual values in case ! of scalar datatypes, pointers to target buffer space in case of compound ! datatypes and unspecified memory areas, or pointer/length pairs in case ! of string parameters. These are appended to the @var{call-id} as a ! comma-delimited list. All values are transmitted in ASCII ! string representation, pointer/length pairs separated by a slash. @end table ! @node The F reply packet @subsection The @code{F} reply packet *************** The @code{F} reply packet has the follow *** 24123,24147 **** @table @samp ! @smallexample ! @code{F}@var{retcode}@code{,}@var{errno}@code{,}@var{Ctrl-C flag}@code{;}@var{call specific attachment} ! @end smallexample @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 @noindent ! or, if the call was interupted before the host call has been performed: @smallexample F-1,4,C --- 24119,24141 ---- @table @samp ! @item F@var{retcode},@var{errno},@var{Ctrl-C flag};@var{call specific attachment} @var{retcode} is the return code of the system call as hexadecimal value. ! @var{errno} is the @code{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 sent if the user requested a break. In this ! case, @var{errno} must be sent as well, even if the call was successful. ! The @var{Ctrl-C flag} itself consists of the character @samp{C}: @smallexample F0,0,C @end smallexample @noindent ! or, if the call was interrupted before the host call has been performed: @smallexample F-1,4,C *************** assuming 4 is the protocol specific repr *** 24152,24180 **** @end table - @node Memory transfer - @subsection Memory transfer - @cindex memory transfer, in file-i/o protocol - - 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 @cindex ctrl-c message, in file-i/o protocol ! 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 @code{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 --- 24146,24166 ---- @end table @node The Ctrl-C message @subsection The Ctrl-C message @cindex ctrl-c message, in file-i/o protocol ! If the Ctrl-C flag is set in the @value{GDBN} ! reply packet (@pxref{The F reply packet}), ! the target should behave as if it had gotten a break message. The meaning for the target is ``system call ! interrupted by @code{SIGINT}''. Consequentially, the target should actually stop (as with a break message) and return to @value{GDBN} with a @code{T02} ! packet. ! ! It's important for the target to know in which ! state the system call was interrupted. There are two possible cases: @itemize @bullet @item *************** These two states can be distinguished by *** 24189,24203 **** returned @code{errno}. If it's the protocol representation of @code{EINTR}, the system call hasn't been performed. This is equivalent to the @code{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 @code{F} reply immediately, setting @code{EINTR} as @code{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} or @code{X} 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 --- 24175,24189 ---- returned @code{errno}. If it's the protocol representation of @code{EINTR}, the system call hasn't been performed. This is equivalent to the @code{EINTR} handling on POSIX systems. In any other case, the target may presume that the ! system call has been finished --- successfully or not --- and should behave as if the break message arrived right after the system call. ! @value{GDBN} must behave reliably. If the system call has not been called yet, @value{GDBN} may send the @code{F} reply immediately, setting @code{EINTR} as @code{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 finished by ! @value{GDBN}. This requires sending @code{M} or @code{X} packets as necessary. ! The @code{F} packet may only be sent when either nothing has happened or the full action has been completed. @node Console I/O *************** conditions is met: *** 24214,24276 **** @itemize @bullet @item ! The user presses @kbd{Ctrl-C}. The behaviour is as explained above, the @code{read} system call is treated as finished. @item The user presses @kbd{Enter}. This is treated as end of input with a trailing ! line feed. @item The user presses @kbd{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, @dots{})} is requested by the target or debugging ! is stopped on users request. ! ! @node The isatty call ! @subsection The @samp{isatty} function call ! @cindex isatty call, file-i/o protocol ! ! A special case in this protocol is the library call @code{isatty} which ! is implemented as its own call inside of this protocol. It returns ! 1 to the target if the file descriptor given as parameter is attached ! to the @value{GDBN} console, 0 otherwise. Implementing through system calls ! would require implementing @code{ioctl} and would be more complex than ! needed. - @node The system call - @subsection The @samp{system} function call - @cindex system call, file-i/o protocol - - The other special case in this protocol is the @code{system} call which - is implemented as its own call, too. @value{GDBN} is taking over the full - task of calling the necessary host calls to perform the @code{system} - call. The return value of @code{system} is simplified before it's returned - to the target. Basically, the only signal transmitted back is @code{EINTR} - in case the user pressed @kbd{Ctrl-C}. Otherwise the return value consists - entirely of the exit status of the called command. - - Due to security concerns, the @code{system} call is by default refused - by @value{GDBN}. The user has to allow this call explicitly with the - @kbd{set remote system-call-allowed 1} command. - - @table @code - @item set remote system-call-allowed - @kindex set remote system-call-allowed - Control whether to allow the @code{system} calls in the File I/O - protocol for the remote target. The default is zero (disabled). - - @item show remote system-call-allowed - @kindex show remote system-call-allowed - Show the current setting of system calls for the remote File I/O - protocol. - @end table @node List of supported calls @subsection List of supported calls --- 24200,24224 ---- @itemize @bullet @item ! The user presses @kbd{Ctrl-C}. The behaviour is as explained above, and the @code{read} system call is treated as finished. @item The user presses @kbd{Enter}. This is treated as end of input with a trailing ! newline. @item The user presses @kbd{Ctrl-D}. This is treated as end of input. No trailing ! character (neither newline nor Ctrl-D) is appended to the input. @end itemize ! If the user has typed more characters than fit in the buffer given to ! the @code{read} call, the trailing characters are buffered in @value{GDBN} until ! either another @code{read(0, @dots{})} is requested by the target, or debugging ! is stopped at the user's request. @node List of supported calls @subsection List of supported calls *************** protocol. *** 24294,24310 **** @unnumberedsubsubsec open @cindex open, file-i/o system call @smallexample - @exdent Synopsis: int open(const char *pathname, int flags); int open(const char *pathname, int flags, mode_t mode); - - @exdent Request: - Fopen,pathptr/len,flags,mode @end smallexample @noindent ! @code{flags} is the bitwise or of the following values: @table @code @item O_CREAT --- 24242,24259 ---- @unnumberedsubsubsec open @cindex open, file-i/o system call + @table @asis + @item Synopsis: @smallexample int open(const char *pathname, int flags); int open(const char *pathname, int flags, mode_t mode); @end smallexample + @item Request: + @samp{Fopen,@var{pathptr}/@var{len},@var{flags},@var{mode}} + @noindent ! @var{flags} is the bitwise @code{OR} of the following values: @table @code @item O_CREAT *************** rules apply as far as file ownership and *** 24313,24325 **** are concerned. @item O_EXCL ! When used with O_CREAT, if the file already exists it is an error and open() fails. @item 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. @item O_APPEND The file is opened in append mode. --- 24262,24274 ---- are concerned. @item O_EXCL ! When used with @code{O_CREAT}, if the file already exists it is an error and open() fails. @item O_TRUNC If the file already exists and the open mode allows ! writing (@code{O_RDWR} or @code{O_WRONLY} is given) it will be ! truncated to zero length. @item O_APPEND The file is opened in append mode. *************** The file is opened for writing only. *** 24332,24345 **** @item O_RDWR The file is opened for reading and writing. @noindent ! Each other bit is silently ignored. - @end table @noindent ! @code{mode} is the bitwise or of the following values: @table @code @item S_IRUSR --- 24281,24294 ---- @item O_RDWR The file is opened for reading and writing. + @end table @noindent ! Other bits are silently ignored. @noindent ! @var{mode} is the bitwise @code{OR} of the following values: @table @code @item S_IRUSR *************** Others have read permission. *** 24359,24403 **** @item S_IWOTH Others have write permission. @noindent ! Each other bit is silently ignored. - @end table ! @smallexample ! @exdent Return value: ! open returns the new file descriptor or -1 if an error ! occured. ! @exdent Errors: ! @end smallexample @table @code @item EEXIST ! pathname already exists and O_CREAT and O_EXCL were used. @item EISDIR ! pathname refers to a directory. @item EACCES The requested access is not allowed. @item ENAMETOOLONG ! pathname was too long. @item ENOENT ! A directory component in pathname does not exist. @item ENODEV ! pathname refers to a device, pipe, named pipe or socket. @item EROFS ! pathname refers to a file on a read-only filesystem and write access was requested. @item EFAULT ! pathname is an invalid pointer value. @item ENOSPC No space on device to create the file. --- 24308,24350 ---- @item S_IWOTH Others have write permission. + @end table @noindent ! Other bits are silently ignored. ! @item Return value: ! @code{open} returns the new file descriptor or -1 if an error ! occurred. ! @item Errors: @table @code @item EEXIST ! @var{pathname} already exists and @code{O_CREAT} and @code{O_EXCL} were used. @item EISDIR ! @var{pathname} refers to a directory. @item EACCES The requested access is not allowed. @item ENAMETOOLONG ! @var{pathname} was too long. @item ENOENT ! A directory component in @var{pathname} does not exist. @item ENODEV ! @var{pathname} refers to a device, pipe, named pipe or socket. @item EROFS ! @var{pathname} refers to a file on a read-only filesystem and write access was requested. @item EFAULT ! @var{pathname} is an invalid pointer value. @item ENOSPC No space on device to create the file. *************** has been reached. *** 24413,24500 **** The call was interrupted by the user. @end table @node close @unnumberedsubsubsec close @cindex close, file-i/o system call @smallexample - @exdent Synopsis: int close(int fd); ! @exdent Request: ! Fclose,fd ! @exdent Return value: ! close returns zero on success, or -1 if an error occurred. ! @exdent Errors: ! @end smallexample @table @code @item EBADF ! fd isn't a valid open file descriptor. @item EINTR The call was interrupted by the user. @end table @node read @unnumberedsubsubsec read @cindex read, file-i/o system call @smallexample - @exdent Synopsis: int read(int fd, void *buf, unsigned int count); ! @exdent Request: ! Fread,fd,bufptr,count ! @exdent 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. ! @exdent Errors: ! @end smallexample @table @code @item EBADF ! fd is not a valid file descriptor or is not open for reading. @item EFAULT ! buf is an invalid pointer value. @item EINTR The call was interrupted by the user. @end table @node write @unnumberedsubsubsec write @cindex write, file-i/o system call @smallexample - @exdent Synopsis: int write(int fd, const void *buf, unsigned int count); ! @exdent Request: ! Fwrite,fd,bufptr,count ! @exdent Return value: On success, the number of bytes written are returned. Zero indicates nothing was written. On error, -1 is returned. ! @exdent Errors: ! @end smallexample @table @code @item EBADF ! fd is not a valid file descriptor or is not open for writing. @item EFAULT ! buf is an invalid pointer value. @item EFBIG An attempt was made to write a file that exceeds the --- 24360,24456 ---- The call was interrupted by the user. @end table + @end table + @node close @unnumberedsubsubsec close @cindex close, file-i/o system call + @table @asis + @item Synopsis: @smallexample int close(int fd); + @end smallexample ! @item Request: ! @samp{Fclose,@var{fd}} ! @item Return value: ! @code{close} returns zero on success, or -1 if an error occurred. ! @item Errors: @table @code @item EBADF ! @var{fd} isn't a valid open file descriptor. @item EINTR The call was interrupted by the user. @end table + @end table + @node read @unnumberedsubsubsec read @cindex read, file-i/o system call + @table @asis + @item Synopsis: @smallexample int read(int fd, void *buf, unsigned int count); + @end smallexample ! @item Request: ! @samp{Fread,@var{fd},@var{bufptr},@var{count}} ! @item 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. ! @item Errors: @table @code @item EBADF ! @var{fd} is not a valid file descriptor or is not open for reading. @item EFAULT ! @var{bufptr} is an invalid pointer value. @item EINTR The call was interrupted by the user. @end table + @end table + @node write @unnumberedsubsubsec write @cindex write, file-i/o system call + @table @asis + @item Synopsis: @smallexample int write(int fd, const void *buf, unsigned int count); + @end smallexample ! @item Request: ! @samp{Fwrite,@var{fd},@var{bufptr},@var{count}} ! @item Return value: On success, the number of bytes written are returned. Zero indicates nothing was written. On error, -1 is returned. ! @item Errors: @table @code @item EBADF ! @var{fd} is not a valid file descriptor or is not open for writing. @item EFAULT ! @var{bufptr} is an invalid pointer value. @item EFBIG An attempt was made to write a file that exceeds the *************** No space on device to write the data. *** 24507,24589 **** The call was interrupted by the user. @end table @node lseek @unnumberedsubsubsec lseek @cindex lseek, file-i/o system call @smallexample - @exdent Synopsis: long lseek (int fd, long offset, int flag); - - @exdent Request: - Flseek,fd,offset,flag @end smallexample ! @code{flag} is one of: @table @code @item SEEK_SET ! The offset is set to offset bytes. @item SEEK_CUR ! The offset is set to its current location plus offset bytes. @item SEEK_END ! The offset is set to the size of the file plus offset bytes. @end table ! @smallexample ! @exdent 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. ! @exdent Errors: ! @end smallexample @table @code @item EBADF ! fd is not a valid open file descriptor. @item ESPIPE ! fd is associated with the @value{GDBN} console. @item EINVAL ! flag is not a proper value. @item EINTR The call was interrupted by the user. @end table @node rename @unnumberedsubsubsec rename @cindex rename, file-i/o system call @smallexample - @exdent Synopsis: int rename(const char *oldpath, const char *newpath); ! @exdent Request: ! Frename,oldpathptr/len,newpathptr/len ! @exdent Return value: On success, zero is returned. On error, -1 is returned. ! @exdent Errors: ! @end smallexample @table @code @item EISDIR ! newpath is an existing directory, but oldpath is not a directory. @item EEXIST ! newpath is a non-empty directory. @item EBUSY ! oldpath or newpath is a directory that is in use by some process. @item EINVAL --- 24463,24549 ---- The call was interrupted by the user. @end table + @end table + @node lseek @unnumberedsubsubsec lseek @cindex lseek, file-i/o system call + @table @asis + @item Synopsis: @smallexample long lseek (int fd, long offset, int flag); @end smallexample ! @item Request: ! @samp{Flseek,@var{fd},@var{offset},@var{flag}} ! ! @var{flag} is one of: @table @code @item SEEK_SET ! The offset is set to @var{offset} bytes. @item SEEK_CUR ! The offset is set to its current location plus @var{offset} bytes. @item SEEK_END ! The offset is set to the size of the file plus @var{offset} bytes. @end table ! @item 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. ! @item Errors: @table @code @item EBADF ! @var{fd} is not a valid open file descriptor. @item ESPIPE ! @var{fd} is associated with the @value{GDBN} console. @item EINVAL ! @var{flag} is not a proper value. @item EINTR The call was interrupted by the user. @end table + @end table + @node rename @unnumberedsubsubsec rename @cindex rename, file-i/o system call + @table @asis + @item Synopsis: @smallexample int rename(const char *oldpath, const char *newpath); + @end smallexample ! @item Request: ! @samp{Frename,@var{oldpathptr}/@var{len},@var{newpathptr}/@var{len}} ! @item Return value: On success, zero is returned. On error, -1 is returned. ! @item Errors: @table @code @item EISDIR ! @var{newpath} is an existing directory, but @var{oldpath} is not a directory. @item EEXIST ! @var{newpath} is a non-empty directory. @item EBUSY ! @var{oldpath} or @var{newpath} is a directory that is in use by some process. @item EINVAL *************** An attempt was made to make a directory *** 24591,24612 **** of itself. @item 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. @item EFAULT ! oldpathptr or newpathptr are invalid pointer values. @item EACCES No access to the file or the path of the file. @item ENAMETOOLONG ! oldpath or newpath was too long. @item ENOENT ! A directory component in oldpath or newpath does not exist. @item EROFS The file is on a read-only filesystem. --- 24551,24572 ---- of itself. @item ENOTDIR ! A component used as a directory in @var{oldpath} or new ! path is not a directory. Or @var{oldpath} is a directory ! and @var{newpath} exists but is not a directory. @item EFAULT ! @var{oldpathptr} or @var{newpathptr} are invalid pointer values. @item EACCES No access to the file or the path of the file. @item ENAMETOOLONG ! @var{oldpath} or @var{newpath} was too long. @item ENOENT ! A directory component in @var{oldpath} or @var{newpath} does not exist. @item EROFS The file is on a read-only filesystem. *************** directory entry. *** 24619,24640 **** The call was interrupted by the user. @end table @node unlink @unnumberedsubsubsec unlink @cindex unlink, file-i/o system call @smallexample - @exdent Synopsis: int unlink(const char *pathname); ! @exdent Request: ! Funlink,pathnameptr/len ! @exdent Return value: On success, zero is returned. On error, -1 is returned. ! @exdent Errors: ! @end smallexample @table @code @item EACCES --- 24579,24603 ---- The call was interrupted by the user. @end table + @end table + @node unlink @unnumberedsubsubsec unlink @cindex unlink, file-i/o system call + @table @asis + @item Synopsis: @smallexample int unlink(const char *pathname); + @end smallexample ! @item Request: ! @samp{Funlink,@var{pathnameptr}/@var{len}} ! @item Return value: On success, zero is returned. On error, -1 is returned. ! @item Errors: @table @code @item EACCES *************** No access to the file or the path of the *** 24644,24660 **** The system does not allow unlinking of directories. @item EBUSY ! The file pathname cannot be unlinked because it's being used by another process. @item EFAULT ! pathnameptr is an invalid pointer value. @item ENAMETOOLONG ! pathname was too long. @item ENOENT ! A directory component in pathname does not exist. @item ENOTDIR A component of the path is not a directory. --- 24607,24623 ---- The system does not allow unlinking of directories. @item EBUSY ! The file @var{pathname} cannot be unlinked because it's being used by another process. @item EFAULT ! @var{pathnameptr} is an invalid pointer value. @item ENAMETOOLONG ! @var{pathname} was too long. @item ENOENT ! A directory component in @var{pathname} does not exist. @item ENOTDIR A component of the path is not a directory. *************** The file is on a read-only filesystem. *** 24666,24788 **** The call was interrupted by the user. @end table @node stat/fstat @unnumberedsubsubsec stat/fstat @cindex fstat, file-i/o system call @cindex stat, file-i/o system call @smallexample - @exdent Synopsis: int stat(const char *pathname, struct stat *buf); int fstat(int fd, struct stat *buf); ! @exdent Request: ! Fstat,pathnameptr/len,bufptr ! Ffstat,fd,bufptr ! @exdent Return value: On success, zero is returned. On error, -1 is returned. ! @exdent Errors: ! @end smallexample @table @code @item EBADF ! fd is not a valid open file. @item ENOENT ! A directory component in pathname does not exist or the path is an empty string. @item ENOTDIR A component of the path is not a directory. @item EFAULT ! pathnameptr is an invalid pointer value. @item EACCES No access to the file or the path of the file. @item ENAMETOOLONG ! pathname was too long. @item EINTR The call was interrupted by the user. @end table @node gettimeofday @unnumberedsubsubsec gettimeofday @cindex gettimeofday, file-i/o system call @smallexample - @exdent Synopsis: int gettimeofday(struct timeval *tv, void *tz); ! @exdent Request: ! Fgettimeofday,tvptr,tzptr ! @exdent Return value: On success, 0 is returned, -1 otherwise. ! @exdent Errors: ! @end smallexample @table @code @item EINVAL ! tz is a non-NULL pointer. @item EFAULT ! tvptr and/or tzptr is an invalid pointer value. @end table @node isatty @unnumberedsubsubsec isatty @cindex isatty, file-i/o system call @smallexample - @exdent Synopsis: int isatty(int fd); ! @exdent Request: ! Fisatty,fd ! @exdent Return value: ! Returns 1 if fd refers to the @value{GDBN} console, 0 otherwise. ! @exdent Errors: ! @end smallexample @table @code @item EINTR The call was interrupted by the user. @end table @node system @unnumberedsubsubsec system @cindex system, file-i/o system call @smallexample - @exdent Synopsis: int system(const char *command); ! @exdent Request: ! Fsystem,commandptr/len ! @exdent 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. ! @exdent Errors: ! @end smallexample @table @code @item EINTR The call was interrupted by the user. @end table @node Protocol specific representation of datatypes @subsection Protocol specific representation of datatypes @cindex protocol specific representation of datatypes, in file-i/o protocol --- 24629,24795 ---- The call was interrupted by the user. @end table + @end table + @node stat/fstat @unnumberedsubsubsec stat/fstat @cindex fstat, file-i/o system call @cindex stat, file-i/o system call + @table @asis + @item Synopsis: @smallexample int stat(const char *pathname, struct stat *buf); int fstat(int fd, struct stat *buf); + @end smallexample ! @item Request: ! @samp{Fstat,@var{pathnameptr}/@var{len},@var{bufptr}}@* ! @samp{Ffstat,@var{fd},@var{bufptr}} ! @item Return value: On success, zero is returned. On error, -1 is returned. ! @item Errors: @table @code @item EBADF ! @var{fd} is not a valid open file. @item ENOENT ! A directory component in @var{pathname} does not exist or the path is an empty string. @item ENOTDIR A component of the path is not a directory. @item EFAULT ! @var{pathnameptr} is an invalid pointer value. @item EACCES No access to the file or the path of the file. @item ENAMETOOLONG ! @var{pathname} was too long. @item EINTR The call was interrupted by the user. @end table + @end table + @node gettimeofday @unnumberedsubsubsec gettimeofday @cindex gettimeofday, file-i/o system call + @table @asis + @item Synopsis: @smallexample int gettimeofday(struct timeval *tv, void *tz); + @end smallexample ! @item Request: ! @samp{Fgettimeofday,@var{tvptr},@var{tzptr}} ! @item Return value: On success, 0 is returned, -1 otherwise. ! @item Errors: @table @code @item EINVAL ! @var{tz} is a non-NULL pointer. @item EFAULT ! @var{tvptr} and/or @var{tzptr} is an invalid pointer value. ! @end table ! @end table @node isatty @unnumberedsubsubsec isatty @cindex isatty, file-i/o system call + @table @asis + @item Synopsis: @smallexample int isatty(int fd); + @end smallexample ! @item Request: ! @samp{Fisatty,@var{fd}} ! @item Return value: ! Returns 1 if @var{fd} refers to the @value{GDBN} console, 0 otherwise. ! @item Errors: @table @code @item EINTR The call was interrupted by the user. @end table + @end table + + Note that the @code{isatty} call is treated as a special case: it returns + 1 to the target if the file descriptor is attached + to the @value{GDBN} console, 0 otherwise. Implementing through system calls + would require implementing @code{ioctl} and would be more complex than + needed. + + @node system @unnumberedsubsubsec system @cindex system, file-i/o system call + @table @asis + @item Synopsis: @smallexample int system(const char *command); + @end smallexample ! @item Request: ! @samp{Fsystem,@var{commandptr}/@var{len}} ! @item 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 host's ! @code{system} return value by calling @code{WEXITSTATUS(retval)}. ! In case @file{/bin/sh} could not be executed, 127 is returned. ! @item Errors: @table @code @item EINTR The call was interrupted by the user. @end table + @end table + + @value{GDBN} takes over the full task of calling the necessary host calls + to perform the @code{system} call. The return value of @code{system} on + the host is simplified before it's returned + to the target. Any termination signal information from the child process + is discarded, and the return value consists + entirely of the exit status of the called command. + + Due to security concerns, the @code{system} call is by default refused + by @value{GDBN}. The user has to allow this call explicitly with the + @code{set remote system-call-allowed 1} command. + + @table @code + @item set remote system-call-allowed + @kindex set remote system-call-allowed + Control whether to allow the @code{system} calls in the File I/O + protocol for the remote target. The default is zero (disabled). + + @item show remote system-call-allowed + @kindex show remote system-call-allowed + Show whether the @code{system} calls are allowed in the File I/O + protocol. + @end table + @node Protocol specific representation of datatypes @subsection Protocol specific representation of datatypes @cindex protocol specific representation of datatypes, in file-i/o protocol *************** The call was interrupted by the user. *** 24790,24795 **** --- 24797,24803 ---- @menu * Integral datatypes:: * Pointer values:: + * Memory transfer:: * struct stat:: * struct timeval:: @end menu *************** The call was interrupted by the user. *** 24798,24813 **** @unnumberedsubsubsec Integral datatypes @cindex integral datatypes, in file-i/o protocol ! The integral datatypes used in the system calls are ! ! @smallexample ! int@r{,} unsigned int@r{,} long@r{,} unsigned long@r{,} mode_t @r{and} time_t ! @end smallexample ! @code{Int}, @code{unsigned int}, @code{mode_t} and @code{time_t} are implemented as 32 bit values in this protocol. ! @code{Long} and @code{unsigned long} are implemented as 64 bit types. @xref{Limits}, for corresponding MIN and MAX values (similar to those in @file{limits.h}) to allow range checking on host and target. --- 24806,24819 ---- @unnumberedsubsubsec Integral datatypes @cindex integral datatypes, in file-i/o protocol ! The integral datatypes used in the system calls are @code{int}, ! @code{unsigned int}, @code{long}, @code{unsigned long}, ! @code{mode_t}, and @code{time_t}. ! @code{int}, @code{unsigned int}, @code{mode_t} and @code{time_t} are implemented as 32 bit values in this protocol. ! @code{long} and @code{unsigned long} are implemented as 64 bit types. @xref{Limits}, for corresponding MIN and MAX values (similar to those in @file{limits.h}) to allow range checking on host and target. *************** are transmitted as a pointer/length pair *** 24834,24858 **** @noindent 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 ! @noindent ! is transmitted as - @smallexample - @code{123456/d} - @end smallexample @node struct stat @unnumberedsubsubsec struct stat @cindex struct stat, in file-i/o protocol ! The buffer of type struct stat used by the target and @value{GDBN} is defined ! as follows: @smallexample struct stat @{ --- 24840,24871 ---- @noindent 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. For example, the string @code{"hello world"} ! at address 0x123456 is transmitted as @smallexample ! @code{123456/d} @end smallexample ! @node Memory transfer ! @unnumberedsubsubsec Memory transfer ! @cindex memory transfer, in file-i/o protocol ! ! Structured data which is transferred using a memory read or write (for ! example, a @code{struct stat}) is expected to be in a protocol specific format ! with all scalar multibyte datatypes being big endian. Translation to ! this representation needs to be done both by the target before the @code{F} ! packet is sent, and 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 struct stat @unnumberedsubsubsec struct stat @cindex struct stat, in file-i/o protocol ! The buffer of type @code{struct stat} used by the target and @value{GDBN} ! is defined as follows: @smallexample struct stat @{ *************** struct stat @{ *** 24872,24918 **** @}; @end smallexample ! The integral datatypes are conforming to the definitions given in the ! approriate section (see @ref{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. ! @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 @cindex struct timeval, in file-i/o protocol ! The buffer of type struct timeval used by the target and @value{GDBN} is defined as follows: @smallexample --- 24885,24935 ---- @}; @end smallexample ! The integral datatypes conform to the definitions given in the ! appropriate section (see @ref{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. ! @table @code ! @item st_dev ! A value of 0 represents a file, 1 the console. ! @item st_ino ! No valid meaning for the target. Transmitted unchanged. ! @item st_mode ! Valid mode bits are described in @ref{Constants}. Any other ! bits have currently no meaning for the target. ! ! @item st_uid ! @itemx st_gid ! @itemx st_rdev ! No valid meaning for the target. Transmitted unchanged. ! ! @item st_atime ! @itemx st_mtime ! @itemx st_ctime ! These values have a host and file system dependent ! accuracy. Especially on Windows hosts, the file system may not ! support exact timing values. ! @end table ! The target gets a @code{struct stat} of the above representation and is ! responsible for coercing it to the target representation before continuing. ! Note that due to size differences between the host, target, and protocol ! representations of @code{struct stat} members, these members could eventually get truncated on the target. @node struct timeval @unnumberedsubsubsec struct timeval @cindex struct timeval, in file-i/o protocol ! The buffer of type @code{struct timeval} used by the File-I/O protocol is defined as follows: @smallexample *************** struct timeval @{ *** 24922,24929 **** @}; @end smallexample ! The integral datatypes are conforming to the definitions given in the ! approriate section (see @ref{Integral datatypes}, for details) so this structure is of size 8 bytes. @node Constants --- 24939,24946 ---- @}; @end smallexample ! The integral datatypes conform to the definitions given in the ! appropriate section (see @ref{Integral datatypes}, for details) so this structure is of size 8 bytes. @node Constants *************** structure is of size 8 bytes. *** 24931,24937 **** @cindex constants, in file-i/o protocol The following values are used for the constants inside of the ! protocol. @value{GDBN} and target are resposible to translate these values before and after the call as needed. @menu --- 24948,24954 ---- @cindex constants, in file-i/o protocol The following values are used for the constants inside of the ! protocol. @value{GDBN} and target are responsible for translating these values before and after the call as needed. @menu *************** All values are given in decimal represen *** 25007,25013 **** 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 --- 25024,25030 ---- EUNKNOWN 9999 @end smallexample ! @code{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 *************** address 0x1234, 6 bytes should be read: *** 25063,25069 **** @end smallexample Example sequence of a read call, call fails on the host due to invalid ! file descriptor (EBADF): @smallexample <- @code{Fread,3,1234,6} --- 25080,25086 ---- @end smallexample Example sequence of a read call, call fails on the host due to invalid ! file descriptor (@code{EBADF}): @smallexample <- @code{Fread,3,1234,6}