This is the mail archive of the gdb-patches@sourceware.org mailing list for the GDB project.


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]
Other format: [Raw text]

PATCH: copy-edit File-I/O section of manual


When I was implementing the File-I/O protocol recently, I noticed a lot of spelling and grammatical mistakes in that section of the manual. Here's a patch to clean it up.

2006-05-13  Sandra Loosemore  <sandra@codesourcery.com>
	* gdb.texinfo (File-I/O remote protocol extension): General
	copy-editing to fix spelling, grammar, formatting issues.
	Moved a few paragraphs around to more logical places.

-Sandra

Index: gdb.texinfo
===================================================================
RCS file: /cvs/src/src/gdb/doc/gdb.texinfo,v
retrieving revision 1.328
diff -c -3 -p -r1.328 gdb.texinfo
*** gdb.texinfo	5 May 2006 22:48:14 -0000	1.328
--- gdb.texinfo	13 May 2006 14:10:54 -0000
*************** program is considered running after the 
*** 12414,12420 ****
  @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
--- 12414,12420 ----
  @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
*** 23700,23710 ****
  * 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::
--- 23700,23707 ----
*************** Example sequence of a target being stepp
*** 23716,23739 ****
  @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,
--- 23713,23737 ----
  @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.
*** 23750,23769 ****
    <- 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:
  
--- 23748,23767 ----
    <- 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 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
*** 23775,23790 ****
  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.
--- 23773,23788 ----
  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.
*** 23794,23807 ****
  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.
--- 23792,23805 ----
  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.
*** 23834,23857 ****
  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
--- 23832,23853 ----
  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
*** 23862,23886 ****
  
  @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
--- 23858,23880 ----
  
  @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
*** 23891,23919 ****
  
  @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
--- 23885,23904 ----
  
  @end table
  
  
  @node The Ctrl-C message
  @subsection The Ctrl-C message
  @cindex ctrl-c message, in file-i/o protocol
  
! If the @var{Ctrl-C flag} is set in the @value{GDBN}
! 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
*** 23928,23942 ****
  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
--- 23913,23927 ----
  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:
*** 23953,24015 ****
  
  @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
--- 23938,23962 ----
  
  @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.
*** 24033,24049 ****
  @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
--- 23980,23995 ----
  @unnumberedsubsubsec open
  @cindex open, file-i/o system call
  
! @table @asis
! @item Synopsis:
! @code{int open(const char *pathname, int flags);}@*
! @code{int open(const char *pathname, int flags, mode_t mode);}
  
! @item Request:
! @code{Fopen,@var{pathptr}/@var{len},@var{flags},@var{mode}}
  
  @noindent
! @var{flags} is the bitwise or of the following values:
  
  @table @code
  @item O_CREAT
*************** rules apply as far as file ownership and
*** 24052,24063 ****
  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
--- 23998,24009 ----
  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 length 0.
  
  @item O_APPEND
*************** The file is opened for writing only.
*** 24071,24084 ****
  
  @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
--- 24017,24030 ----
  
  @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 or of the following values:
  
  @table @code
  @item S_IRUSR
*************** Others have read permission.
*** 24098,24142 ****
  
  @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.
--- 24044,24086 ----
  
  @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.
*** 24152,24239 ****
  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
--- 24096,24186 ----
  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:
! @code{int close(int fd);}
  
! @item Request:
! @code{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:
! @code{int read(int fd, void *buf, unsigned int count);}
  
! @item Request:
! @code{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:
! @code{int write(int fd, const void *buf, unsigned int count);}
  
! @item Request:
! @code{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.
*** 24246,24328 ****
  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
--- 24193,24275 ----
  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:
! @code{long lseek (int fd, long offset, int flag);}
  
! @item Request:
! @code{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:
! @code{int rename(const char *oldpath, const char *newpath);}
  
! @item Request:
! @code{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 
*** 24330,24351 ****
  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.
--- 24277,24298 ----
  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.
*** 24358,24379 ****
  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
--- 24305,24327 ----
  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:
! @code{int unlink(const char *pathname);}
  
! @item Request:
! @code{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
*** 24383,24399 ****
  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.
--- 24331,24347 ----
  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.
*** 24405,24527 ****
  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
--- 24353,24511 ----
  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:
! @code{int stat(const char *pathname, struct stat *buf);}@*
! @code{int fstat(int fd, struct stat *buf);}
! 
! @item Request:
! @code{Fstat,@var{pathnameptr}/@var{len},@var{bufptr}}@*
! @code{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:
! @code{int gettimeofday(struct timeval *tv, void *tz);}
  
! @item Request:
! @code{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:
! @code{int isatty(int fd);}
  
! @item Request:
! @code{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:
! @code{int system(const char *command);}
  
! @item Request:
! @code{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 @code{/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.  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
+ @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 the current setting of system calls for the remote 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.
*** 24529,24534 ****
--- 24513,24519 ----
  @menu
  * Integral datatypes::
  * Pointer values::
+ * Memory transfer::
  * struct stat::
  * struct timeval::
  @end menu
*************** The call was interrupted by the user.
*** 24537,24552 ****
  @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.
--- 24522,24535 ----
  @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
*** 24573,24597 ****
  @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 @{
--- 24556,24587 ----
  @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 @{
*** 24611,24657 ****
  @};
  @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
--- 24601,24653 ----
  @};
  @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
! No valid meaning for the target.  Transmitted unchanged.
  
! @itemx st_gid
! No valid meaning for the target.  Transmitted unchanged.
  
! @item st_rdev
! No valid meaning for the target.  Transmitted unchanged.
! 
! @item st_atime, st_mtime, 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 @{
*** 24661,24668 ****
  @};
  @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
--- 24657,24664 ----
  @};
  @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.
*** 24670,24676 ****
  @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
--- 24666,24672 ----
  @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
*** 24746,24752 ****
    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
--- 24742,24748 ----
    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:
*** 24802,24808 ****
  @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}
--- 24798,24804 ----
  @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}

Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]