[RFA]: File-I/O patch, Documentation

[Corinna Vinschen <vinschen@redhat.com>]

[-- Attachment #1: Type: text/plain, Size: 271 bytes --]

Hi,

this is the patch containing the additional documentation for File-I/O.

Corinna

2002-11-21  Corinna Vinschen  <vinschen@redhat.com>

        * gdb.texinfo: Add File-I/O documentation.

-- 
Corinna Vinschen
Cygwin Developer
Red Hat, Inc.
mailto:vinschen@redhat.com

[-- Attachment #2: fileio-doc.patch --]
[-- Type: text/plain, Size: 29000 bytes --]

Index: doc/gdb.texinfo
===================================================================
RCS file: /cvs/src/src/gdb/doc/gdb.texinfo,v
retrieving revision 1.131
diff -u -p -r1.131 gdb.texinfo
--- doc/gdb.texinfo	11 Oct 2002 16:13:15 -0000	1.131
+++ doc/gdb.texinfo	21 Nov 2002 08:42:04 -0000
@@ -14838,6 +14838,7 @@ Takes an optional file parameter.
 * Stop Reply Packets::
 * General Query Packets::
 * Register Packet Format::
+* File-I/O remote protocol extension::
 * Examples::
 @end menu
 
@@ -15063,9 +15064,12 @@ Reserved for future use.
 
 Reserved for future use.
 
-@item @code{F} --- reserved
+@item @code{F}@var{RC}@code{,}@var{EE}@code{,}@var{CF}@code{;}@var{XX} --- Reply to target's F packet.
+@cindex @code{F} packet
 
-Reserved for future use.
+This packet is send by @value{GDBN} as reply to a @code{F} request packet
+sent by the target.  This is part of the File-I/O protocol extension.
+@xref{File-I/O remote protocol extension}, for the specification.
 
 @item @code{g} --- read registers
 @anchor{read registers packet}
@@ -15564,6 +15568,24 @@ is a query initiated by the host debugge
 any time while the program is running and the debugger should continue
 to wait for @samp{W}, @samp{T}, etc.
 
+@item F@var{call-id}@code{,}@var{parameter@dots{}}
+
+@var{call-id} is the identifier which says which host system call should
+be called.  This is just the name of the function.  Translation into the
+correct system call is only applicable as it's defined in @value{GDBN}.
+@xref{File-I/O remote protocol extension}, for a list of implemented
+system calls.
+
+@var{parameter@dots{}} is a list of parameters as defined for this very
+system call.
+
+The target replies with this packet when it expects @value{GDBN} to call
+a host system call on behalf of the target.  @value{GDBN} replies with
+an appropriate @code{F} packet and keeps up waiting for the next reply
+packet from the target.  The latest @samp{C}, @samp{c}, @samp{S} or
+@samp{s} action is expected to be continued.
+@xref{File-I/O remote protocol extension}, for more details.
+
 @end table
 
 @node General Query Packets
@@ -15773,6 +15795,892 @@ thirty-two bit registers such as @code{s
 as @code{MIPS32}.
 
 @end table
+
+@node File-I/O remote protocol extension
+@section File-I/O remote protocol extension
+
+@menu
+* File-I/O Overview::
+* Protocol basics::
+* The @code{F} request packet::
+* The @code{F} reply packet::
+* Memory transfer::
+* The Ctrl-C message::
+* Console I/O::
+* The isatty(3) call::
+* The system(3) call::
+* List of supported calls::
+* Protocol specific representation of datatypes::
+* Constants::
+@end menu
+
+@node File-I/O Overview
+@subsection File-I/O Overview
+
+The File I/O remote protocol extension (short: File-I/O) allows the
+target to use the hosts file system and console I/O when calling various
+system calls.  System calls on the target system are translated into a
+remote protocol packet to the host system which then performs the needed
+actions and returns with an adequate response packet to the target system.
+This simulates file system operations even on file system-less targets. 
+
+The protocol is defined host- and target-system independent.  It uses
+it's own independent representation of datatypes and values.  Both,
+@value{GDBN} and the target's @value{GDBN} stub are responsible for
+translating the system dependent values into the unified protocol values
+when data is transmitted.
+
+The communication is synchronous.  A system call is possible only
+when GDB is waiting for the @samp{C}, @samp{c}, @samp{S} or @samp{s}
+packets.  While @value{GDBN} handles the request for a system call,
+the target is stopped to allow deterministic access to the target's
+memory.  Therefore File-I/O is not interuptible by target signals.  It
+is possible to interrupt File-I/O by a user interrupt (Ctrl-C), though.
+
+The target's request to perform a host system call does not finish
+the latest @samp{C}, @samp{c}, @samp{S} or @samp{s} action.  That means,
+after finishing the system call, the target returns to continuing the
+previous activity (continue, step).  No additional continue or step
+request from @value{GDBN} is required.
+
+@smallexample
+(gdb) continue
+  <- target requests 'system call X'
+  target is stopped, GDB executes system call
+  -> GDB returns result
+  ... target continues, GDB returns to wait for the target
+  <- target hits breakpoint and sends a Txx packet
+@end smallexample
+
+The protocol is only used for files on the host file system and
+for I/O on the console.  Character or block special devices, pipes,
+named pipes or sockets or any other communication method on the host
+system are not supported by this protocol.
+
+@node Protocol basics
+@subsection Protocol basics
+
+The File-I/O protocol uses the @code{F} packet, as request as well
+as as reply packet.  Since a File-I/O system call can only occur when
+@value{GDBN} is waiting for the continuing or stepping target, the 
+File-I/O request is a reply that @value{GDBN} has to expect as a result
+of a former @samp{C}, @samp{c}, @samp{S} or @samp{s} packet.
+This @code{F} packet contains all information needed to allow @value{GDBN}
+to call the appropriate host system call:
+
+@itemize @bullet
+@item 
+A unique identifier for the requested system call.
+
+@item
+All parameters to the system call.  Pointers are given as addresses
+into the target memory.  Pointers to strings are given as pointer/length
+pair.  Numerical values are given as they are.  Numerical control values
+are given in a protocol specific representation.
+
+@end itemize
+
+At that point @value{GDBN} has to perform the following actions.
+
+@itemize @bullet
+@item 
+If parameter pointer values are given, which point to data needed as input
+to a system call, @value{GDBN} requests this data from the target with a
+standard @code{m} packet request.  This additional communication has to be
+expected by the target implementation and is handled as any other @code{m}
+packet.
+
+@item
+Translating all values from protocol representation to host representation
+as needed.  Datatypes are coerced into the host types.
+
+@item
+Call system call.
+
+@item
+Coerce datatypes back to protocol representation.
+
+@item
+If pointer parameters in the request packet point to buffer space in which
+a system call is expected to copy data to, the data is transmitted to the
+target using a @code{M} packet.  This packet has to be expected by the
+target implementation and is handled as any other @code{M} packet.
+
+@end itemize
+
+Eventually GDB replies with another @code{F} packet which contains all
+necessary information for the target to continue.  This at least contains
+
+@itemize @bullet
+@item
+Return value.
+
+@item
+Errno, if has been changed by the system call.
+
+@item
+"Ctrl-C" flag.
+
+@end itemize
+
+After having done the needed type and value coercion, the target continues
+the latest continue or step action.
+
+@node The @code{F} request packet
+@subsection The @code{F} request packet
+
+The @code{F} request packet has the following format:
+
+@table @samp
+@item @code{F}@var{call-id}@code{,}@var{parameter@dots{}}
+
+@var{call-id} is the identifier to indicate the host system call to be called.
+This is just the name of the function.
+
+@var{parameter@dots{}} are the parameters to the system call.
+
+@end table
+
+Parameters are hexadecimal integer values, either the real values in case
+of scalar datatypes, as pointers to target buffer space in case of compound
+datatypes and unspecified memory areas or as pointer/length pairs in case
+of string parameters.  These are appended to the call-id, each separated
+from its predecessor by a comma.  All values are transmitted in ASCII
+string representation, pointer/length pairs separated by a slash.
+
+@node The @code{F} reply packet
+@subsection The @code{F} reply packet
+
+The @code{F} reply packet has the following format:
+@table @samp
+@item @code{F}@var{retcode}@code{,}@var{errno}@code{,}@var{Ctrl-C flag}@code{;}@var{call specific attachment}
+
+@var{retcode} is the return code of the system call as hexadecimal value.
+
+@var{errno} is the errno set by the call, in protocol specific representation.
+This parameter can be omitted if the call was successful.
+
+@var{Ctrl-C flag} is only send if the user requested a break.  In this
+case, @var{errno} must be send as well, even if the call was successful.
+The @var{Ctrl-C flag} itself consists of the character 'C':
+
+@smallexample
+F0,0,C
+@end smallexample
+
+or, if the call was interupted before the host call has been performed:
+
+@smallexample
+F-1,4,C
+@end smallexample
+
+assuming 4 is the protocol specific representation of EINTR.
+
+@end table
+
+@node Memory transfer
+@subsection Memory transfer
+
+Structured data which is transferred using a memory read or write as e. g.
+a @code{struct stat} is expected to be in a protocol specific format with
+all scalar multibyte datatypes being big endian.  This should be done by
+the target before the @code{F} packet is sent resp. by @value{GDBN} before
+it transfers memory to the target.  Transferred pointers to structured
+data should point to the already coerced data at any time.
+
+@node The Ctrl-C message
+@subsection The Ctrl-C message
+
+A special case is, if the @var{Ctrl-C flag} is set in the @value{GDBN}
+reply packet.  In this case the target should behave, as if it had
+gotten a break message.  The meaning for the target is "system call
+interupted by SIGINT".  Consequentially, the target should actually stop
+(as with a break message) and return to @value{GDBN} with a @code{T02}
+packet.  In this case, it's important for the target to know, in which 
+state the system call was interrupted.  Since this action is by design
+not an atomic operation, we have to differ between two cases:
+
+@itemize @bullet
+@item
+The system call hasn't been performed on the host yet.
+
+@item The system call on the host has been finished.
+
+@end itemize
+
+These two states can be distinguished by the target by the value of the
+returned errno.  If it's the protocol representation of EINTR, the system
+call hasn't been performed.  This is equivalent to the EINTR handling
+on POSIX systems.  In any other case, the target may presume that the
+system call has been finished -- successful or not -- and should behave
+as if the break message arrived right after the system call.
+
+@value{GDBN} must behave reliable.  If the system call has not been called
+yet, @value{GDBN} may send the 'F' reply immediately, setting EINTR as
+errno in the packet.  If the system call on the host has been finished
+before the user requests a break, the full action must be finshed by
+@value{GDBN}.  This requires sending @code{M} packets as they fit.
+The @code{F} packet may only be send when either nothing has happened
+or the full action has been completed.
+
+@node Console I/O
+@subsection Console I/O
+
+By default and if not explicitely closed by the target system, the file
+descriptors 0, 1 and 2 are connected to the @value{GDBN} console.  Output
+on the @value{GDBN} console is handled as any other file output operation
+(@code{write(1, ...)} or @code{write(2, ...)}).  Console input is handled
+by @value{GDBN} so that after the target read request from file descriptor
+0 all following typing is buffered until either one of the following
+conditions is met:
+
+@itemize @bullet
+@item
+The user presses Ctrl-C.  The behaviour is as explained above, the read()
+system call is treated as finished.
+
+@item
+The user presses <Enter>.  This is treated as end of input with a trailing
+line feed.
+
+@item
+The user presses Ctrl-D.  This is treated as end of input.  No trailing
+character, especially no Ctrl-D is appended to the input.
+
+@end itemize
+
+If the user has typed more characters as fit in the buffer given to
+the read call, the trailing characters are buffered in @value{GDBN} until
+either another @code{read(0, ...)} is requested by the target or debugging
+is stopped on users request.
+
+@node The isatty(3) call
+@subsection The isatty(3) call
+
+A special case in this protocol is the library call isatty(3) which
+is implemented as it's own call inside of this protocol.  It returns
+1 to the target if the file descriptor given as parameter is attached
+to the GDB console, 0 otherwise.  Implementing through system calls
+would require implementing ioctl() and would be more complex than
+needed.
+
+@node The system(3) call
+@subsection The system(3) call
+
+The other special case in this protocol is the system(3) call which
+is implemented as it's own call, too.  @value{GDBN} is taking over the full
+task of calling the necessary host calls to perform the system(3)
+call.  The return value of system(3) is simplified before it's returned
+to the target.  Basically, the only signal transmitted back is EINTR
+in case the user pressed Ctrl-C.  Otherwise the return value consists
+entirely of the exit status of the called command.
+
+Due to security concerns, the system(3) call is refused to be called
+by @value{GDBN}.  The user has to allow this call explicitely by 
+entering
+
+@table @samp
+@item @code{set remote system-call-allowed 1}
+@end table
+
+Disabling the system(3) call is done by
+
+@table @samp
+@item @code{set remote system-call-allowed 0}
+@end table
+
+The current setting is shown by typing
+
+@table @samp
+@item @code{show remote system-call-allowed}
+@end table
+
+@node List of supported calls
+@subsection List of supported calls
+
+@menu
+* open::
+* close::
+* read::
+* write::
+* lseek::
+* rename::
+* unlink::
+* stat/fstat::
+* gettimeofday::
+* isatty::
+* system::
+@end menu
+
+@node open
+@unnumberedsubsubsec open
+
+@smallexample
+Synopsis:     int open(const char *pathname, int flags);
+              int open(const char *pathname, int flags, mode_t mode);
+
+Request:      Fopen,pathptr/len,flags,mode
+
+  `flags' is the bitwise or of the following values:
+
+  O_CREAT     If the file does not exist it will be created.  The host
+              rules apply as far as file ownership and time stamps
+              are concerned.
+
+  O_EXCL      When used with O_CREAT, if the file already exists it is
+              an error and open() fails.
+
+  O_TRUNC     If the file already exists and the open mode allows
+              writing (O_RDWR or O_WRONLY is given) it will be
+              truncated to length 0.
+
+  O_APPEND    The file is opened in append mode.
+
+  O_RDONLY    The file is opened for reading only.
+
+  O_WRONLY    The file is opened for writing only.
+
+  O_RDWR      The file is opened for reading and writing.
+
+  Each other bit is silently ignored.
+
+  `mode' is the bitwise or of the following values:
+
+  S_IRUSR     User has read permission.
+
+  S_IWUSR     User has write permission.
+
+  S_IRGRP     Group has read permission.
+
+  S_IWGRP     Group has write permission.
+
+  S_IROTH     Others have read permission.
+
+  S_IWOTH     Others have write permission.
+
+  Each other bit is silently ignored.
+
+Return value: open returns the new file descriptor or -1 if an error
+              occured.
+
+Errors:
+
+  EEXIST      pathname already exists and O_CREAT and O_EXCL were used.
+
+  EISDIR      pathname refers to a directory.
+
+  EACCES      The requested access is not allowed.
+
+  ENAMETOOLONG
+              pathname was too long.
+
+  ENOENT      A directory component in pathname does not exist.
+
+  ENODEV      pathname refers to a device, pipe, named pipe or socket.
+
+  EROFS       pathname refers to a file on a read-only filesystem and
+              write access was requested.
+
+  EFAULT      pathname is an invalid pointer value.
+
+  ENOSPC      No space on device to create the file.
+
+  EMFILE      The process already has the maximum number of files open.
+
+  ENFILE      The limit on the total number of files open on the system
+              has been reached.
+
+  EINTR       The call was interrupted by the user.
+@end smallexample
+
+@node close
+@unnumberedsubsubsec close
+
+@smallexample
+Synopsis:     int close(int fd);
+
+Request:      Fclose,fd
+
+Return value: close returns zero on success, or -1 if an error occurred.
+
+Errors:
+
+  EBADF       fd isn't a valid open file descriptor.
+
+  EINTR       The call was interrupted by the user.
+@end smallexample
+
+@node read
+@unnumberedsubsubsec read
+
+@smallexample
+Synopsis:     int read(int fd, void *buf, unsigned int count);
+
+Request:      Fread,fd,bufptr,count
+
+Return value: On success, the number of bytes read is returned.
+              Zero indicates end of file.  If count is zero, read
+              returns zero as well.  On error, -1 is returned. 
+
+Errors:
+
+  EBADF       fd is not a valid file descriptor or is not open for
+              reading.
+
+  EFAULT      buf is an invalid pointer value.
+
+  EINTR       The call was interrupted by the user.
+@end smallexample
+
+@node write
+@unnumberedsubsubsec write
+
+@smallexample
+Synopsis:     int write(int fd, const void *buf, unsigned int count);
+
+Request:      Fwrite,fd,bufptr,count
+
+Return value: On success, the number of bytes written are returned.
+              Zero indicates nothing was written.  On error, -1
+              is returned.
+
+Errors:
+
+  EBADF       fd is not a valid file descriptor or is not open for
+              writing.
+
+  EFAULT      buf is an invalid pointer value.
+
+  EFBIG       An attempt was made to write a file that exceeds the
+              host specific maximum file size allowed.
+
+  ENOSPC      No space on device to write the data.
+
+  EINTR       The call was interrupted by the user.
+@end smallexample
+
+@node lseek
+@unnumberedsubsubsec lseek
+
+@smallexample
+Synopsis:     long lseek (int fd, long offset, int flag);
+
+Request:      Flseek,fd,offset,flag
+
+`flag' is one of:
+
+  SEEK_SET    The offset is set to offset bytes.
+
+  SEEK_CUR    The offset is set to its current location plus offset
+              bytes.
+
+  SEEK_END    The offset is set to the size of the file plus offset
+              bytes.
+
+Return value: On success, the resulting unsigned offset in bytes from
+              the beginning of the file is returned.  Otherwise, a
+              value of -1 is returned.
+
+Errors:
+
+  EBADF       fd is not a valid open file descriptor.
+
+  ESPIPE      fd is associated with the GDB console.
+
+  EINVAL      flag is not a proper value.
+
+  EINTR       The call was interrupted by the user.
+@end smallexample
+
+@node rename
+@unnumberedsubsubsec rename
+
+@smallexample
+Synopsis:     int rename(const char *oldpath, const char *newpath);
+
+Request:      Frename,oldpathptr/len,newpathptr/len
+
+Return value: On success, zero is returned.  On error, -1 is returned.
+
+Errors:
+
+  EISDIR      newpath is an existing directory, but oldpath is not a
+              directory.
+
+  EEXIST      newpath is a non-empty directory.
+
+  EBUSY       oldpath or newpath is a directory that is in use by some
+              process.
+
+  EINVAL      An attempt was made to make a directory a subdirectory
+              of itself.
+
+  ENOTDIR     A  component used as a directory in oldpath or new
+              path is not a directory.  Or oldpath is a directory
+              and newpath exists but is not a directory.
+
+  EFAULT      oldpathptr or newpathptr are invalid pointer values.
+
+  EACCES      No access to the file or the path of the file.
+
+  ENAMETOOLONG
+              oldpath or newpath was too long.
+
+  ENOENT      A directory component in oldpath or newpath does not exist.
+
+  EROFS       The file is on a read-only filesystem.
+
+  ENOSPC      The device containing the file has no room for the new
+              directory entry.
+
+  EINTR       The call was interrupted by the user.
+@end smallexample
+
+@node unlink
+@unnumberedsubsubsec unlink
+
+@smallexample
+Synopsis:     int unlink(const char *pathname);
+
+Request:      Funlink,pathnameptr/len
+
+Return value: On success, zero is returned.  On error, -1 is returned.
+
+Errors:
+
+  EACCES      No access to the file or the path of the file.
+
+  EPERM       The system does not allow unlinking of directories.
+
+  EBUSY       The file pathname cannot be unlinked because it's
+              being used by another process.
+
+  EFAULT      pathnameptr is an invalid pointer value.
+
+  ENAMETOOLONG
+              pathname was too long.
+
+  ENOENT      A directory component in pathname does not exist.
+
+  ENOTDIR     A component of the path is not a directory.
+
+  EROFS       The file is on a read-only filesystem.
+
+  EINTR       The call was interrupted by the user.
+@end smallexample
+
+@node stat/fstat
+@unnumberedsubsubsec stat/fstat
+
+@smallexample
+Synopsis:     int stat(const char *pathname, struct stat *buf);
+              int fstat(int fd, struct stat *buf);
+
+Request:      Fstat,pathnameptr/len,bufptr
+              Ffstat,fd,bufptr
+
+Return value: On success, zero is returned.  On error, -1 is returned.
+
+Errors:
+
+  EBADF       fd is not a valid open file.
+
+  ENOENT      A directory component in pathname does not exist or the
+              path is an empty string.
+
+  ENOTDIR     A component of the path is not a directory.
+
+  EFAULT      pathnameptr is an invalid pointer value.
+
+  EACCES      No access to the file or the path of the file.
+
+  ENAMETOOLONG
+              pathname was too long.
+
+  EINTR       The call was interrupted by the user.
+@end smallexample
+
+@node gettimeofday
+@unnumberedsubsubsec gettimeofday
+
+@smallexample
+Synopsis:     int gettimeofday(struct timeval *tv, void *tz);
+
+Request:      Fgettimeofday,tvptr,tzptr
+
+Return value: On success, 0 is returned, -1 otherwise.
+
+Errors:
+
+  EINVAL      tz is a non-NULL pointer.
+
+  EFAULT      tvptr and/or tzptr is an invalid pointer value.
+@end smallexample
+
+@node isatty
+@unnumberedsubsubsec isatty
+
+@smallexample
+Synopsis:     int isatty(int fd);
+
+Request:      Fisatty,fd
+
+Return value: Returns 1 if fd refers to the GDB console, 0 otherwise.
+
+Errors:
+
+  EINTR       The call was interrupted by the user.
+@end smallexample
+
+@node system
+@unnumberedsubsubsec system
+
+@smallexample
+Synopsis:     int system(const char *command);
+
+Request:      Fsystem,commandptr/len
+
+Return value: The value returned is -1 on error and the return status
+              of the command otherwise.  Only the exit status of the
+              command is returned, which is extracted from the hosts
+              system return value by calling WEXITSTATUS(retval).
+              In case /bin/sh could not be executed, 127 is returned.
+
+Errors:
+
+  EINTR       The call was interrupted by the user.
+@end smallexample
+
+@node Protocol specific representation of datatypes
+@subsection Protocol specific representation of datatypes
+
+@menu
+* Integral datatypes::
+* Pointer values::
+* struct stat::
+* struct timeval::
+@end menu
+
+@node Integral datatypes
+@unnumberedsubsubsec Integral datatypes
+
+The integral datatypes used in the system calls are
+
+@smallexample
+int, unsigned int, long, unsigned long, mode_t and time_t
+@end smallexample
+
+Int, unsigned int, mode_t and time_t are implemented as 32 bit values
+in this protocol.
+
+Long and unsigned long are implemented as 64 bit types. 
+    
+@xref{Limits}, for corresponding MIN and MAX values (similar to those
+in limits.h) to allow range checking on host and target.
+
+@node Pointer values
+@unnumberedsubsubsec Pointer values
+
+Pointers to target data is transmitted as they are.  A difference
+is made for pointers to buffers for which the length isn't
+transmitted as part of the function call, namely strings.  Strings
+are transmitted as a pointer/length pair, both as hex values, e. g.
+
+@smallexample
+@code{1aaf/12}
+@end smallexample
+
+which is a pointer to data of length 18 bytes at position 0x1aaf.
+The length is defined as the full string length in bytes, including
+the trailing null byte.  Example:
+
+@smallexample
+"hello, world" at address 0x123456
+@end smallexample
+
+is transmitted as
+
+@smallexample
+@code{123456/d}
+@end smallexample
+
+@node struct stat
+@unnumberedsubsubsec struct stat
+
+The buffer of type struct stat used by the target and GDB is defined
+as follows:
+
+@smallexample
+struct stat @{
+    unsigned int  st_dev;      /* device */
+    unsigned int  st_ino;      /* inode */
+    mode_t        st_mode;     /* protection */
+    unsigned int  st_nlink;    /* number of hard links */
+    unsigned int  st_uid;      /* user ID of owner */
+    unsigned int  st_gid;      /* group ID of owner */
+    unsigned int  st_rdev;     /* device type (if inode device) */
+    unsigned long st_size;     /* total size, in bytes */
+    unsigned long st_blksize;  /* blocksize for filesystem I/O */
+    unsigned long st_blocks;   /* number of blocks allocated */
+    time_t        st_atime;    /* time of last access */
+    time_t        st_mtime;    /* time of last modification */
+    time_t        st_ctime;    /* time of last change */
+@};
+@end smallexample
+
+The integral datatypes are conforming to the definition in B.1 so this
+structure is of size 64 bytes.
+
+The values of several fields have a restricted meaning and/or
+range of values.
+
+@smallexample
+st_dev:     0       file
+            1       console
+
+st_ino:     No valid meaning for the target.  Transmitted unchanged.
+
+st_mode:    Valid mode bits are described in Appendix C.  Any other
+            bits have currently no meaning for the target.
+
+st_uid:     No valid meaning for the target.  Transmitted unchanged.
+
+st_gid:     No valid meaning for the target.  Transmitted unchanged.
+
+st_rdev:    No valid meaning for the target.  Transmitted unchanged.
+
+st_atime, st_mtime, st_ctime:
+            These values have a host and file system dependent
+            accuracy.  Especially on Windows hosts the file systems
+            don't support exact timing values.
+@end smallexample
+
+The target gets a struct stat of the above representation and is
+responsible to coerce it to the target representation before
+continuing.
+
+Note that due to size differences between the host and target
+representation of stat members, these members could eventually
+get truncated on the target.
+
+@node struct timeval
+@unnumberedsubsubsec struct timeval
+
+The buffer of type struct timeval used by the target and GDB is defined
+as follows:
+
+@smallexample
+struct timeval @{ 
+    time_t tv_sec;  /* second */
+    long   tv_usec; /* microsecond */
+@};
+@end smallexample
+
+The integral datatypes are conforming to the definition in B.1 so this
+structure is of size 8 bytes.
+
+@node Constants
+@subsection Constants
+
+The following values are used for the constants inside of the
+protocol.  GDB and target are resposible to translate these
+values before and after the call as needed.
+
+@menu
+* Open flags::
+* mode_t values::
+* Errno values::
+* Lseek flags::
+* Limits::
+@end menu
+
+@node Open flags
+@unnumberedsubsubsec Open flags
+
+All values are given in hexadecimal representation.
+
+@smallexample
+  O_RDONLY        0
+  O_WRONLY        1
+  O_RDWR          2
+  O_APPEND        8
+  O_CREAT       200
+  O_TRUNC       400
+  O_EXCL        800
+@end smallexample
+
+@node mode_t values
+@unnumberedsubsubsec mode_t values
+
+All values are given in octal representation.
+
+@smallexample
+  S_IFREG       100000
+  S_IFDIR        40000
+  S_IRUSR          400
+  S_IWUSR          200
+  S_IXUSR          100
+  S_IRGRP           40
+  S_IWGRP           20
+  S_IXGRP           10
+  S_IROTH            4
+  S_IWOTH            2
+  S_IXOTH            1
+@end smallexample
+
+@node Errno values
+@unnumberedsubsubsec Errno values
+
+All values are given in decimal representation.
+
+@smallexample
+  EPERM           1
+  ENOENT          2
+  EINTR           4
+  EBADF           9
+  EACCES         13
+  EFAULT         14
+  EBUSY          16
+  EEXIST         17
+  ENODEV         19
+  ENOTDIR        20
+  EISDIR         21
+  EINVAL         22
+  ENFILE         23
+  EMFILE         24
+  EFBIG          27
+  ENOSPC         28
+  ESPIPE         29
+  EROFS          30
+  ENAMETOOLONG   91
+  EUNKNOWN       9999
+@end smallexample
+
+  EUNKNOWN is used as a fallback error value if a host system returns
+  any error value not in the list of supported error numbers.
+
+@node Lseek flags
+@unnumberedsubsubsec Lseek flags
+
+@smallexample
+  SEEK_SET      0
+  SEEK_CUR      1
+  SEEK_END      2
+@end smallexample
+
+@node Limits
+@unnumberedsubsubsec Limits
+
+All values are given in decimal representation.
+
+@smallexample
+  INT_MIN       -2147483648
+  INT_MAX        2147483647
+  UINT_MAX       4294967295
+  LONG_MIN      -9223372036854775808
+  LONG_MAX       9223372036854775807
+  ULONG_MAX      18446744073709551615
+@end smallexample
 
 @node Examples
 @section Examples