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

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

[Corinna Vinschen]

[-- 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

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

[Corinna Vinschen]

On Thu, Nov 21, 2002 at 10:04:43AM +0100, Corinna Vinschen wrote:
> Hi,
> 
> this is the patch containing the additional documentation for File-I/O.

Of course I found an error seconds after sending this.

> [...]
> +@node struct stat
> +@unnumberedsubsubsec struct stat
> [...]

Subsitute

> +The integral datatypes are conforming to the definition in B.1 so this
> +structure is of size 64 bytes.

by

  The integral datatypes are conforming to the definitions given in the
  approriate section (@xref{Integral datatypes}, for details) so this
  structure is of size 64 bytes.

The same happened in the next section "struct timeval", just the size
is 8 instead of 64.

Sorry,
Corinna

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

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

[Eli Zaretskii]

Sorry for the delay; this is a signifcant patch, and I'm hard pressed
for free time lately.

> Date: Thu, 21 Nov 2002 10:04:43 +0100
> From: Corinna Vinschen <vinschen@redhat.com>
> 
> this is the patch containing the additional documentation for File-I/O.

Thanks.  Your documentation patch is approved, provided that you
correct the following technicalities before committing it:

> +@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

There are a few problems here.  This menu lists node names, some of
which use characters and constructs that are either disallowed or
discouraged in node names.  You cannot use parentheses in node names,
since (foo)bar as a node name means node `bar' in the manual `foo'.
Commands like @code are discouraged in node names, because using them
makes validation of cross-references hard.

See the node "Node Line Requirements" in the Texinfo manual for more
details.

The corresponding @node lines should be fixed as well.

The corresponding section and subsection names, by contrast, may use
those characters.  In fact, you are encouraged to use markup such as
@code in section names, as that makes the printed manual (where only
the section names are visible) look prettier.

> +This simulates file system operations even on file system-less targets. 

A stylistic nit: I'd suggest to say "targets that lack file
systems".  I think it sounds less awkward.

> +@smallexample
> +(gdb) continue
   ^^^^^
This should be @value{GDBP}...

> +  target is stopped, GDB executes system call
                        ^^^
...and this should be @value{GDBN}.

> +@item
> +All parameters to the system call.  Pointers are given as addresses
> +into the target memory.

I suggest to say "as addresses in the target memory address space".

> +@item
> +Translating all values from protocol representation to host representation
> +as needed.

I think it's better to say "@value{GDBN} translates all values...",
to be consistent with the wording of the previous @item.  And the
same below:

> +@item
> +Call system call.

"@value{GDBN} calls the system call."

> +@item
> +Coerce datatypes back to protocol representation.

"It then coerces datatypes back..."

> +@item
> +Errno, if has been changed by the system call.

I think @code{errno} is better.

> +@item
> +"Ctrl-C" flag.

Please use `` and '' instead of " and " in Texinfo.  They produce
identical results in the Info output, but the former are typeset
better by TeX in the printed manual.

> +@item @code{F}@var{retcode}@code{,}@var{errno}@code{,}@var{Ctrl-C flag}@code{;}@var{call specific attachment}

This is okay, but you don't need to repeat @code all that much, just
include everything in a @code to begin with.  I think the following
will produce the same effect as what you did:

 @item @code{F@var{retcode},@var{errno},@var{Ctrl-C flag};@var{call-specific attachment}}

> +@smallexample
> +F0,0,C
> +@end smallexample
> +
> +or, if the call was interupted before the host call has been performed:

There should be a @noindent (on a line by itself) before the last
line, to prevent makeinfo and TeX from indenting it.

> +@smallexample
> +F-1,4,C
> +@end smallexample
> +
> +assuming 4 is the protocol specific representation of EINTR.

Same here.

> +Structured data which is transferred using a memory read or write as e. g.

Please use "e.g.@:" instead of "e. g.".  The @: tells TeX that the
period does not end a sentence, so that TeX won't typeset extra white
space after it.

> +the target before the @code{F} packet is sent resp. by @value{GDBN} before

Same here: please use "resp.@:".

> +gotten a break message.  The meaning for the target is "system call
> +interupted by SIGINT".

Please use `` and ''.

> +@itemize @bullet
> +@item
> +The system call hasn't been performed on the host yet.
> +
> +@item The system call on the host has been finished.

Please leave the @item on its separate line in the last sentence.

> +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

"errno" should be in @code, and so should be "EINTR" and any other
possible values of `errno'.

> +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.

Whenever you want a long dash, please write "---" (3 dashes) in
Texinfo.  "--" and "-" produce identical results in the printed
manual, while "---" produces a longer dash.

> +@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

The 'F' should be @code{F}, I think.

> +(@code{write(1, ...)} or @code{write(2, ...)}).  Console input is handled

Please use @dots{} instead of literal "...".

> +The user presses Ctrl-C.

What the user types should have the @kbd markup: "@kbd{Ctrl-C}".

>                            The behaviour is as explained above, the read()
> +system call is treated as finished.

Please say "@code{read}" instead of "read()".  The latter looks like
a call to the function `read' with no arguments, which is not what
you want to say.

In general, the frequent practice of appending "()" to a name to mean
that it's a function should be abandoned in Texinfo in favor of the
@code markup.

> +The user presses <Enter>.

Keys should have the @key markup: "@key{Enter}".  This produces a
small image of a key in the printed manual.

> +Due to security concerns, the system(3) call is refused to be called
> +by @value{GDBN}.

I think you forgot to say "by default" here.  GDB only refises to call
`system' by default, not unconditionally.

>                     The user has to allow this call explicitely by 
                                                      ^^^^^^^^^^^
This should be "explicitly".

> +@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

The "set remote system-call-allowed" and "show remote
system-call-allowed" commands should be indexed with @kindex, like we
do with all user commands.

> +The integral datatypes used in the system calls are
> +
> +@smallexample
> +int, unsigned int, long, unsigned long, mode_t and time_t
> +@end smallexample

I'd put the "and" and the commas inside @r{}, so that they don't have
the fixed typewriter typeface used inside @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. 

The names of the data types (int, mode_t, etc.) should have the @code
markup here.

> +@xref{Limits}, for corresponding MIN and MAX values (similar to those
> +in limits.h) to allow range checking on host and target.

"limits.h" should have the @file markup, as it's a file name.

> +Pointers to target data is transmitted as they are.
                           ^^
This should be "are".

>                                                       A difference
> +is made for pointers to buffers for which the length isn't

"An exception is made for pointers...".

> +transmitted as part of the function call, namely strings.  Strings
> +are transmitted as a pointer/length pair, both as hex values, e. g.

"e.g.@:"

> +@smallexample
> +@code{1aaf/12}
> +@end smallexample
> +
> +which is a pointer to data of length 18 bytes at position 0x1aaf.

Please insert a @noindent before the last line.

> +@smallexample
> +"hello, world" at address 0x123456
> +@end smallexample
> +
> +is transmitted as

Same here.

> +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.

Is it really necessary to use hexadecimal representation for the
former and octal representation for the latter?  Can we use the same
representation for both, to avoid confusion?

Finally, please add @cindex entries to allow for efficient searches
of relevant issues.  As a minimum, please consider adding a @cindex
for section/subsection whose name is the same as the section name,
but in lower case.  For example:

  @node Memory transfer
  @subsection Memory transfer
  @cindex memory transfer, in file I/O packets

(The addition of "in file I/O packets" is meant to qualify "memory
transfer" which is too general; without it, a user might not realize
this index entry is for the file I/O feature.)

Thanks again for writing this.

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

[Eli Zaretskii]

> Date: Thu, 21 Nov 2002 10:22:01 +0100
> From: Corinna Vinschen <vinschen@redhat.com>
> 
> Subsitute
> 
> > +The integral datatypes are conforming to the definition in B.1 so this
> > +structure is of size 64 bytes.
> 
> by
> 
>   The integral datatypes are conforming to the definitions given in the
>   approriate section (@xref{Integral datatypes}, for details) so this
>   structure is of size 64 bytes.

That's okay, but please don't use "@xref" except at the beginning of a
sentence, because it produces capitalized "Note:" and "See" in the
output.  In this case, I suggest instead to say

  approriate section (see @ref{Integral datatypes}, for details) so this

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

[Andrew Cagney]

> Sorry for the delay; this is a signifcant patch, and I'm hard pressed
> for free time lately.
> 
> 
>> Date: Thu, 21 Nov 2002 10:04:43 +0100
>> From: Corinna Vinschen <vinschen@redhat.com>
>> 
>> this is the patch containing the additional documentation for File-I/O.
> 
> 
> Thanks.  Your documentation patch is approved, provided that you
> correct the following technicalities before committing it:

Corinna, just to clarify this a little.

The protocol changes proper still need to be approved so, until that 
happens, can you please not commit this.

Andrew

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

[Corinna Vinschen]

On Sat, Nov 23, 2002 at 01:02:05PM +0300, Eli Zaretskii wrote:
> Sorry for the delay; this is a signifcant patch, and I'm hard pressed
> for free time lately.

No worries.  Thanks for reviewing this mess ;-)

I applied most of your hints and suggestions.  However, a few comments
are left, which I'd like to clarify:

> > +* The @code{F} request packet::
> > +* The @code{F} reply packet::

I changed that and the corresponding @node-s to

  * The `F' request packet::
  * The `F' reply packet::

Is that ok?

> > +* The isatty(3) call::
> > +* The system(3) call::

Here I just dropped the "(3)" part.

> > +@smallexample
> > +(gdb) continue
>    ^^^^^
> This should be @value{GDBP}...

Should it?  That's the GDB prompt.  It's used plain text in other
examples in the text as well so I assumed that being correct here.

> > +@item @code{F}@var{retcode}@code{,}@var{errno}@code{,}@var{Ctrl-C flag}@code{;}@var{call specific attachment}
> 
> This is okay, but you don't need to repeat @code all that much, just
> include everything in a @code to begin with.  I think the following
> will produce the same effect as what you did:
> 
>  @item @code{F@var{retcode},@var{errno},@var{Ctrl-C flag};@var{call-specific attachment}}
> 

No, the effect is different:

   `F'RETCODE`,'ERRNO`,'CTRL-C FLAG`;'CALL SPECIFIC ATTACHMENT

Your version:

   `FRETCODE,ERRNO,CTRL-C FLAG;CALL SPECIFIC ATTACHMENT'

> > +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
> 
> "errno" should be in @code, and so should be "EINTR" and any other
> possible values of `errno'.

I did the same with SIGINT.

What about all the constants used in the descriptions of the calls?
Should I rewrite all

  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.
    [...]
    Errors:

    EEXIST      pathname already exists and O_CREAT and O_EXCL were used.

to

  Request:      Fopen,pathptr/len,flags,mode

    `flags' is the bitwise or of the following values:

    @code{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.
    [...]
    Errors:

    @code{EEXIST}      pathname already exists and O_CREAT and O_EXCL were used.

?


> > +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.
> 
> Is it really necessary to use hexadecimal representation for the
> former and octal representation for the latter?  Can we use the same
> representation for both, to avoid confusion?

The used representation is the one used in most header files.  Open modes
are most easy to read in hex, permission bits in octal.  That's the reasoning.

What about prepending the hex numbers with a leading '0x', the octals
with a leading '0'?

Corinna
> Finally, please add @cindex entries to allow for efficient searches
> of relevant issues.  As a minimum, please consider adding a @cindex
> for section/subsection whose name is the same as the section name,

Section name?  Not node name?  What about

  @node The `F' request packet
  @subsection The @code{F} request packet

Especially the Uppercase F?  Wouldn't

  @cindex the file-i/o request package

be the way to go?

Again, thanks for reviewing,
Corinna

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

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

[Eli Zaretskii]

> Date: Mon, 25 Nov 2002 11:51:58 +0100
> From: Corinna Vinschen <vinschen@redhat.com>
> 
> > > +* The @code{F} request packet::
> > > +* The @code{F} reply packet::
> 
> I changed that and the corresponding @node-s to
> 
>   * The `F' request packet::
>   * The `F' reply packet::
> 
> Is that ok?

Yes.  To be absolutely sure, generate an Info manual from the Texinfo
sources, then fire up an Info reader of your choice, go to these menu
lines and press [Enter].  If this works, everything's okay.

> > > +* The isatty(3) call::
> > > +* The system(3) call::
> 
> Here I just dropped the "(3)" part.

Fine, thanks.

> > > +@smallexample
> > > +(gdb) continue
> >    ^^^^^
> > This should be @value{GDBP}...
> 
> Should it?  That's the GDB prompt.  It's used plain text in other
> examples in the text as well so I assumed that being correct here.

Well, gdbint.texinfo indeed didn't use @value{GDBN} and @value{GDBP}
until very recently, unlike gdb.texinfo.  I think the decision was to
use them in both manuals, but I might be mistaken.  Andrew?

> > > +@item @code{F}@var{retcode}@code{,}@var{errno}@code{,}@var{Ctrl-C flag}@code{;}@var{call specific attachment}
> > 
> > This is okay, but you don't need to repeat @code all that much, just
> > include everything in a @code to begin with.  I think the following
> > will produce the same effect as what you did:
> > 
> >  @item @code{F@var{retcode},@var{errno},@var{Ctrl-C flag};@var{call-specific attachment}}
> > 
> 
> No, the effect is different:
> 
>    `F'RETCODE`,'ERRNO`,'CTRL-C FLAG`;'CALL SPECIFIC ATTACHMENT
> 
> Your version:
> 
>    `FRETCODE,ERRNO,CTRL-C FLAG;CALL SPECIFIC ATTACHMENT'

Well, I think my result is more accurate ;-)  Those `' around F and
such are not really there in the packet, right?

But if you think your result is better, I won't insist.

> What about all the constants used in the descriptions of the calls?
> Should I rewrite all
> 
>   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.
>     [...]
>     Errors:
> 
>     EEXIST      pathname already exists and O_CREAT and O_EXCL were used.
> 
> to
> 
>   Request:      Fopen,pathptr/len,flags,mode
> 
>     `flags' is the bitwise or of the following values:
> 
>     @code{O_CREAT}     If the file does not exist it will be created.  The host

No, you don't need to do that, since @smallexample already typesets
everything in the same typeface as @code.

Btw, theere's a disadvantage of using @smallexample here: the other
text, such as the verbal descriptions of the O_* flags and errno
values, is also typeset in fixed-size typewriter face, so the flag and
errno names don't stand out.  For that reason, I generally recommend
to use a @table instead of @smallexample, like this:

@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
@end smallexample

@noindent
where @code{flags} is the bitwise or of the following values:

@table @code
@item 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.

@item O_EXCL
When used with O_CREAT, if the file already exists it is
an error and open() fails.
...
@end table

This typesets the flag names in fixed font, but the rest of the text
is typeset in the usual roman typeface.

> What about prepending the hex numbers with a leading '0x', the octals
> with a leading '0'?

This is IMHO better than having '0' in both.

> > Finally, please add @cindex entries to allow for efficient searches
> > of relevant issues.  As a minimum, please consider adding a @cindex
> > for section/subsection whose name is the same as the section name,
> 
> Section name?  Not node name?

Section name is usually better, since its language is more natural
(node name is just a label, and is not generally meant for humans to
read), and since index entries do allow @-commands such as @code while
node names don't.

>  What about
> 
>   @node The `F' request packet
>   @subsection The @code{F} request packet
> 
> Especially the Uppercase F?  Wouldn't
> 
>   @cindex the file-i/o request package
> 
> be the way to go?

Either will do, so in this case it's up to you.  Actually, I could
make an argument for having both ;-)

When writing @cindex entries, what I generally do is pretend to be a
person who is looking for some material described in this section, and
then ask myself: what phrase would I try to look for in the index?

However, if you do use the latter, please leave the "the" part out:
index entries should not have them, just the terms themselves.
(Otherwise, many entries will begin with "the".)

> Again, thanks for reviewing,

And thank _you_ for doing the actual work.

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

[Corinna Vinschen]

On Mon, Nov 25, 2002 at 09:01:26PM +0300, Eli Zaretskii wrote:
> > From: Corinna Vinschen <vinschen@redhat.com>
> > > > +@smallexample
> > > > +(gdb) continue
> > >    ^^^^^
> > > This should be @value{GDBP}...
> > 
> > Should it?  That's the GDB prompt.  It's used plain text in other
> > examples in the text as well so I assumed that being correct here.
> 
> Well, gdbint.texinfo indeed didn't use @value{GDBN} and @value{GDBP}
> until very recently, unlike gdb.texinfo.  I think the decision was to
> use them in both manuals, but I might be mistaken.  Andrew?

Aaandrew?

> > No, the effect is different:
> > 
> >    `F'RETCODE`,'ERRNO`,'CTRL-C FLAG`;'CALL SPECIFIC ATTACHMENT
> > 
> > Your version:
> > 
> >    `FRETCODE,ERRNO,CTRL-C FLAG;CALL SPECIFIC ATTACHMENT'
> 
> Well, I think my result is more accurate ;-)  Those `' around F and
> such are not really there in the packet, right?
> 
> But if you think your result is better, I won't insist.

Ok, I will use my version.  My reasoning is that in an info reader it's
pretty hard to distinguish between the fixed parts like the leading `F'
and the variable parts as "retcode".

> @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
> @end smallexample
> 
> @noindent
> where @code{flags} is the bitwise or of the following values:
> 
> @table @code
> @item 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.
> 
> @item O_EXCL
> When used with O_CREAT, if the file already exists it is
> an error and open() fails.
> ...
> @end table

I like the idea and I'd like to use it.  However, there is one problem
I don't know how to solve correctly.  The "Synopsis", "Request" etc.
are unfortunately indented due to the usage of smallexample.  I tried
using @noindent but that has no influence in a smallexample.  Using
a @table @samp doesn't work either because it quotes the headlines
and
 
``Synopsis:''
    int open ...

doesn't look that nice.

How can I get the typical typeset for the "Synopsis" etc. paragraphs but
without the indenting of smallexample?

> Either will do, so in this case it's up to you.  Actually, I could
> make an argument for having both ;-)

Ok, I added two more @cindex.

Corinna

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

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

[Eli Zaretskii]

> Date: Tue, 26 Nov 2002 15:06:45 +0100
> From: Corinna Vinschen <vinschen@redhat.com>
> 
> ``Synopsis:''
>     int open ...
> 
> doesn't look that nice.
> 
> How can I get the typical typeset for the "Synopsis" etc. paragraphs but
> without the indenting of smallexample?

Use @exdent.  The details of its usage, including an example, are in
the manual of the Texinfo package.

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

[Corinna Vinschen]

On Tue, Nov 26, 2002 at 08:01:44PM +0300, Eli Zaretskii wrote:
> > Date: Tue, 26 Nov 2002 15:06:45 +0100
> > From: Corinna Vinschen <vinschen@redhat.com>
> > 
> > ``Synopsis:''
> >     int open ...
> > 
> > doesn't look that nice.
> > 
> > How can I get the typical typeset for the "Synopsis" etc. paragraphs but
> > without the indenting of smallexample?
> 
> Use @exdent.  The details of its usage, including an example, are in
> the manual of the Texinfo package.

Thanks for the hint.  That looks fine now.

Corinna

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

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

[Andrew Cagney]

> 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, do you have the up-to-date version of this document somewhere?

Andrew

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

[Corinna Vinschen]

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

On Wed, Feb 26, 2003 at 06:22:52PM -0500, Andrew Cagney wrote:
> >        * gdb.texinfo: Add File-I/O documentation.
> >
> Corinna, do you have the up-to-date version of this document somewhere?

Attached.

Corinna

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

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

Index: doc/gdb.texinfo
===================================================================
RCS file: /cvs/src/src/gdb/doc/gdb.texinfo,v
retrieving revision 1.149
diff -u -p -r1.149 gdb.texinfo
--- doc/gdb.texinfo	23 Feb 2003 22:19:48 -0000	1.149
+++ doc/gdb.texinfo	27 Feb 2003 08:34:19 -0000
@@ -14766,6 +14766,7 @@ compiled with the @samp{-pg} compiler op
 * Stop Reply Packets::
 * General Query Packets::
 * Register Packet Format::
+* File-I/O remote protocol extension::
 * Examples::
 @end menu
 
@@ -14991,9 +14992,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}
@@ -15492,6 +15496,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
@@ -15701,6 +15723,1088 @@ 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
+@cindex File-I/O remote protocol extension
+
+@menu
+* File-I/O Overview::
+* 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::
+@end menu
+
+@node File-I/O Overview
+@subsection File-I/O Overview
+@cindex 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 targets that lack file systems.
+
+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, @value{GDBN} 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
+@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:
+
+@itemize @bullet
+@item 
+A unique identifier for the requested system call.
+
+@item
+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.
+
+@item
+@value{GDBN} translates all value from protocol representation to host
+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} 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
+@code{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 `F' request packet
+@subsection The @code{F} request packet
+@cindex file-i/o request packet
+@cindex @code{F} request packet
+
+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
+@cindex file-i/o reply packet
+@cindex @code{F} reply packet
+
+The @code{F} reply packet has the following format:
+
+@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
+@end smallexample
+
+@noindent
+assuming 4 is the protocol specific representation of @code{EINTR}.
+
+@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
+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 @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} 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
+@cindex console i/o as part of file-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, @dots{})} or @code{write(2, @dots{})}).  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 @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 isatty(3) call
+@cindex isatty call, file-i/o protocol
+
+A special case in this protocol is the library call @code{isatty} 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 @code{ioctl} and would be more complex than
+needed.
+
+@node The system call
+@subsection The system(3) call
+@cindex system call, file-i/o protocol
+
+The other special case in this protocol is the @code{system} 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 @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 refused to be called
+by @value{GDBN} by default.  The user has to allow this call explicitly by 
+entering
+
+@table @samp
+@kindex set remote system-call-allowed 1
+@item @code{set remote system-call-allowed 1}
+@end table
+
+Disabling the @code{system} call is done by
+
+@table @samp
+@kindex set remote system-call-allowed 0
+@item @code{set remote system-call-allowed 0}
+@end table
+
+The current setting is shown by typing
+
+@table @samp
+@kindex show remote system-call-allowed
+@item @code{show remote system-call-allowed}
+@end table
+
+@node List of supported calls
+@subsection List of supported calls
+@cindex list of supported file-i/o calls
+
+@menu
+* open::
+* close::
+* read::
+* write::
+* lseek::
+* rename::
+* unlink::
+* stat/fstat::
+* gettimeofday::
+* isatty::
+* system::
+@end menu
+
+@node open
+@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    
+If the file does not exist it will be created.  The host
+rules apply as far as file ownership and time stamps
+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.
+
+@item O_RDONLY   
+The file is opened for reading only.
+
+@item O_WRONLY   
+The file is opened for writing only.
+
+@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    
+User has read permission.
+
+@item S_IWUSR    
+User has write permission.
+
+@item S_IRGRP    
+Group has read permission.
+
+@item S_IWGRP    
+Group has write permission.
+
+@item S_IROTH    
+Others have read permission.
+
+@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.
+
+@item EMFILE     
+The process already has the maximum number of files open.
+
+@item ENFILE     
+The limit on the total number of files open on the system
+has been reached.
+
+@item EINTR      
+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
+host specific maximum file size allowed.
+
+@item ENOSPC     
+No space on device to write the data.
+
+@item EINTR      
+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 GDB 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     
+An attempt was made to make a directory a subdirectory
+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.
+
+@item ENOSPC     
+The device containing the file has no room for the new
+directory entry.
+
+@item EINTR      
+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     
+No access to the file or the path of the file.
+
+@item EPERM      
+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.
+
+@item EROFS      
+The file is on a read-only filesystem.
+
+@item EINTR      
+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 GDB 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
+
+@menu
+* Integral datatypes::
+* Pointer values::
+* struct stat::
+* struct timeval::
+@end menu
+
+@node Integral datatypes
+@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.
+
+@node Pointer values
+@unnumberedsubsubsec Pointer values
+@cindex pointer values, in file-i/o protocol
+
+Pointers to target data are transmitted as they are.  An exception
+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
+
+@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 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 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 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 definitions given in the
+approriate section (see @ref{Integral datatypes}, for details) so this
+structure is of size 8 bytes.
+
+@node Constants
+@subsection Constants
+@cindex constants, in file-i/o protocol
+
+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
+@cindex open flags, in file-i/o protocol
+
+All values are given in hexadecimal representation.
+
+@smallexample
+  O_RDONLY        0x0
+  O_WRONLY        0x1
+  O_RDWR          0x2
+  O_APPEND        0x8
+  O_CREAT       0x200
+  O_TRUNC       0x400
+  O_EXCL        0x800
+@end smallexample
+
+@node mode_t values
+@unnumberedsubsubsec mode_t values
+@cindex mode_t values, in file-i/o protocol
+
+All values are given in octal representation.
+
+@smallexample
+  S_IFREG       0100000
+  S_IFDIR        040000
+  S_IRUSR          0400
+  S_IWUSR          0200
+  S_IXUSR          0100
+  S_IRGRP           040
+  S_IWGRP           020
+  S_IXGRP           010
+  S_IROTH            04
+  S_IWOTH            02
+  S_IXOTH            01
+@end smallexample
+
+@node Errno values
+@unnumberedsubsubsec Errno values
+@cindex errno values, in file-i/o protocol
+
+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
+@cindex lseek flags, in file-i/o protocol
+
+@smallexample
+  SEEK_SET      0
+  SEEK_CUR      1
+  SEEK_END      2
+@end smallexample
+
+@node Limits
+@unnumberedsubsubsec Limits
+@cindex limits, in file-i/o protocol
+
+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

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

[Andrew Cagney]

> +@menu
> +* File-I/O Overview::
> +* 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::

I think the only problem here is the need for two small, simple but 
concrete examples:

- the target doing a write() call

- the user entering CNTRL-C and a demonstration of one of the edge cases

> +* Protocol specific representation of datatypes::
> +* Constants::
> +@end menu

--

My one concern with the protocol spec is with this structure.  The size 
of those various types is target compiler dependent yet the 
implementation assumes specific sizes.

> +@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

c99 (what ever the standard) formalized a number of explicitly sized 
types (int32 et.al. I believe).  I think this table should be specified 
using those types.  The alternative is to generalize the 
sim/common/sim-types.h file and then specify the sizes using that.

The time unit of st_*time should be defined.

The byte order of all the values should be defined.

The reference to B.1 should be removed.

Andrew

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

[Corinna Vinschen]

On Thu, Feb 27, 2003 at 06:07:06PM -0500, Andrew Cagney wrote:
> I think the only problem here is the need for two small, simple but 
> concrete examples:
> 
> - the target doing a write() call
> 
> - the user entering CNTRL-C and a demonstration of one of the edge cases

Ok.

> My one concern with the protocol spec is with this structure.  The size 
> of those various types is target compiler dependent yet the 
> implementation assumes specific sizes.

Sure.  The sizes are chosen so that they are very likely big enough
to match all hosts and targets for... well... at least a long time.

> c99 (what ever the standard) formalized a number of explicitly sized 
> types (int32 et.al. I believe).  I think this table should be specified 
> using those types.  The alternative is to generalize the 
> sim/common/sim-types.h file and then specify the sizes using that.

I don't think so.  The protocol is more or less self-contained.  All
definitions are based on the assumption, that you'll never find a
really matching combination of values as they are defined on all
machines.  Looking into the fileio code you'll see, that gdb has a
couple of functions which transform all protocol datatypes to host
datatypes and all protocol values to host values and vice versa.
This is done that way to be totally independent from other sources of
definition (especially machine dependent definitions).

It's *expected* that the gdb plugin on the target side is doing the
same.

> The time unit of st_*time should be defined.

Second since epoche but you're right, it should be mentioned.

> The byte order of all the values should be defined.

It is.  Quote from the text:

  Structured data which is transferred using a memory read or write
  packet as e.g. a struct stat is expected to be in a protocol specific
  format with all numerical multibyte datatypes being big endian.

> The reference to B.1 should be removed.

Nope.

Corinna

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

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

[Daniel Jacobowitz]

On Fri, Feb 28, 2003 at 09:33:08AM +0100, Corinna Vinschen wrote:
> > c99 (what ever the standard) formalized a number of explicitly sized 
> > types (int32 et.al. I believe).  I think this table should be specified 
> > using those types.  The alternative is to generalize the 
> > sim/common/sim-types.h file and then specify the sizes using that.
> 
> I don't think so.  The protocol is more or less self-contained.  All
> definitions are based on the assumption, that you'll never find a
> really matching combination of values as they are defined on all
> machines.  Looking into the fileio code you'll see, that gdb has a
> couple of functions which transform all protocol datatypes to host
> datatypes and all protocol values to host values and vice versa.
> This is done that way to be totally independent from other sources of
> definition (especially machine dependent definitions).
> 
> It's *expected* that the gdb plugin on the target side is doing the
> same.

Sure.  But how big are they on the wire?  I think that's what Andrew
was asking to be clarified.


-- 
Daniel Jacobowitz
MontaVista Software                         Debian GNU/Linux Developer

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

[Andrew Cagney]

> On Thu, Feb 27, 2003 at 06:07:06PM -0500, Andrew Cagney wrote:
> 
>> I think the only problem here is the need for two small, simple but 
>> concrete examples:
>> 
>> - the target doing a write() call
>> 
>> - the user entering CNTRL-C and a demonstration of one of the edge cases
> 
> 
> Ok.
> 
> 
>> My one concern with the protocol spec is with this structure.  The size 
>> of those various types is target compiler dependent yet the 
>> implementation assumes specific sizes.
> 
> 
> Sure.  The sizes are chosen so that they are very likely big enough
> to match all hosts and targets for... well... at least a long time.

Right.  That is fine.

>> c99 (what ever the standard) formalized a number of explicitly sized 
>> types (int32 et.al. I believe).  I think this table should be specified 
>> using those types.  The alternative is to generalize the 
>> sim/common/sim-types.h file and then specify the sizes using that.
> 
> 
> I don't think so.  The protocol is more or less self-contained.  All
> definitions are based on the assumption, that you'll never find a
> really matching combination of values as they are defined on all
> machines.  Looking into the fileio code you'll see, that gdb has a
> couple of functions which transform all protocol datatypes to host
> datatypes and all protocol values to host values and vice versa.
> This is done that way to be totally independent from other sources of
> definition (especially machine dependent definitions).


> It's *expected* that the gdb plugin on the target side is doing the
> same.

The problem is that the protocol spec isn't self contained.  As best as 
I can tell, the specification is making assumptions about the underlying 
characteristics of `int', `long', `time_t', et.al. types.  `int', for 
instance, can be anything from 16 to 64 bits.

For the target side for this to be correctly, the types:

- the size of these types.
- the byte order of these types
- the underlying implementation of these types

all need to be specified (I'm sure there is other stuff that someone 
will point out later :-).  I don't see that information.

>> The time unit of st_*time should be defined.
> 
> 
> Second since epoche but you're right, it should be mentioned.
> 
> 
>> The byte order of all the values should be defined.
> 
> 
> It is.  Quote from the text:
> 
>   Structured data which is transferred using a memory read or write
>   packet as e.g. a struct stat is expected to be in a protocol specific
>   format with all numerical multibyte datatypes being big endian.

If it is defined somewhere else, then cross references are needed.

>> The reference to B.1 should be removed.
> 
> 
> Nope.

Er, `B.1' is meaningless.  If the intent was to reference another 
section of the document, then a texinfo cross-reference should be used.

Andrew

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

[Corinna Vinschen]

On Fri, Feb 28, 2003 at 10:30:05AM -0500, Andrew Cagney wrote:
> The problem is that the protocol spec isn't self contained.  As best as 
> I can tell, the specification is making assumptions about the underlying 
> characteristics of `int', `long', `time_t', et.al. types.  `int', for 
> instance, can be anything from 16 to 64 bits.

Huh?  This is explicitely defined in the chapter "Integral datatypes"
which is the chapter mistakenly defined as B.1.  See below.

> >>The byte order of all the values should be defined.
> >
> >It is.  Quote from the text:
> >
> >  Structured data which is transferred using a memory read or write
> >  packet as e.g. a struct stat is expected to be in a protocol specific
> >  format with all numerical multibyte datatypes being big endian.
> 
> If it is defined somewhere else, then cross references are needed.

So why don't you say this?  You read the document, I assume.  But you
told that as if it's not in the document.  That's a difference I couldn't
get from what you wrote.

> >>The reference to B.1 should be removed.
> Er, `B.1' is meaningless.  If the intent was to reference another 
> section of the document, then a texinfo cross-reference should be used.

Sic, yes.  It's just a textual reference which I got wrong.  This has
nothing to do with content which your reply implied to me. 

Sorry to say that but it's hard to understand what you're up to if your
answers are that short.  My mind-reading skills got a little bit rusty...


Corinna

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

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

[Corinna Vinschen]

On Fri, Feb 28, 2003 at 10:25:04AM -0500, Daniel Jacobowitz wrote:
> On Fri, Feb 28, 2003 at 09:33:08AM +0100, Corinna Vinschen wrote:
> > > c99 (what ever the standard) formalized a number of explicitly sized 
> > > types (int32 et.al. I believe).  I think this table should be specified 
> > > using those types.  The alternative is to generalize the 
> > > sim/common/sim-types.h file and then specify the sizes using that.
> > 
> > I don't think so.  The protocol is more or less self-contained.  All
> > definitions are based on the assumption, that you'll never find a
> > really matching combination of values as they are defined on all
> > machines.  Looking into the fileio code you'll see, that gdb has a
> > couple of functions which transform all protocol datatypes to host
> > datatypes and all protocol values to host values and vice versa.
> > This is done that way to be totally independent from other sources of
> > definition (especially machine dependent definitions).
> > 
> > It's *expected* that the gdb plugin on the target side is doing the
> > same.
> 
> Sure.  But how big are they on the wire?  I think that's what Andrew
> was asking to be clarified.

...which is written into the document in the chapter "Integral datatypes"
which I mistakenly referenced as "B.1" as it was in my original document
I've send months ago on the gdb ML.

Corinna

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

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

[Daniel Jacobowitz]

On Fri, Feb 28, 2003 at 04:49:26PM +0100, Corinna Vinschen wrote:
> On Fri, Feb 28, 2003 at 10:25:04AM -0500, Daniel Jacobowitz wrote:
> > On Fri, Feb 28, 2003 at 09:33:08AM +0100, Corinna Vinschen wrote:
> > > > c99 (what ever the standard) formalized a number of explicitly sized 
> > > > types (int32 et.al. I believe).  I think this table should be specified 
> > > > using those types.  The alternative is to generalize the 
> > > > sim/common/sim-types.h file and then specify the sizes using that.
> > > 
> > > I don't think so.  The protocol is more or less self-contained.  All
> > > definitions are based on the assumption, that you'll never find a
> > > really matching combination of values as they are defined on all
> > > machines.  Looking into the fileio code you'll see, that gdb has a
> > > couple of functions which transform all protocol datatypes to host
> > > datatypes and all protocol values to host values and vice versa.
> > > This is done that way to be totally independent from other sources of
> > > definition (especially machine dependent definitions).
> > > 
> > > It's *expected* that the gdb plugin on the target side is doing the
> > > same.
> > 
> > Sure.  But how big are they on the wire?  I think that's what Andrew
> > was asking to be clarified.
> 
> ...which is written into the document in the chapter "Integral datatypes"
> which I mistakenly referenced as "B.1" as it was in my original document
> I've send months ago on the gdb ML.

Sorry.  I was extrapolating from Andrew's answer, and it's been months
since I read it.

-- 
Daniel Jacobowitz
MontaVista Software                         Debian GNU/Linux Developer

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

[Eli Zaretskii]

> Date: Thu, 27 Feb 2003 09:37:01 +0100
> From: Corinna Vinschen <vinschen@redhat.com>
> 
> On Wed, Feb 26, 2003 at 06:22:52PM -0500, Andrew Cagney wrote:
> > >        * gdb.texinfo: Add File-I/O documentation.
> > >
> > Corinna, do you have the up-to-date version of this document somewhere?
> 
> Attached.

I'm sorry if I missed something from this thread, but do I understand
correctly that this doco patch is not yet committed?  If so, is that
my fault somehow?  I thought I approved this patch many weeks ago, but
perhaps I missed something.

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

[Andrew Cagney]

> Date: Thu, 27 Feb 2003 09:37:01 +0100
>> From: Corinna Vinschen <vinschen@redhat.com>
>> 
>> On Wed, Feb 26, 2003 at 06:22:52PM -0500, Andrew Cagney wrote:
> 
>> > >        * gdb.texinfo: Add File-I/O documentation.
>> > >
> 
>> > Corinna, do you have the up-to-date version of this document somewhere?
> 
>> 
>> Attached.
> 
> 
> I'm sorry if I missed something from this thread, but do I understand
> correctly that this doco patch is not yet committed?  If so, is that
> my fault somehow?  I thought I approved this patch many weeks ago, but
> perhaps I missed something.

You've previously approved this.  I put a hold on the doco being 
committed until I also reviewed it (as the remote maintainer).

Andrew

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

[Andrew Cagney]

> If it is defined somewhere else, then cross references are needed.
> 
> 
> So why don't you say this?  You read the document, I assume.  But you
> told that as if it's not in the document.  That's a difference I couldn't
> get from what you wrote.

Well the texinfo.  I read the reference as a reference to something 
completly separate.

Can you please expand the paragraph to reference: Protocol specific 
representation of datatypes.

Otherwize ok by me,
Andrew

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

[Corinna Vinschen]

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

On Sat, Mar 01, 2003 at 09:58:44PM -0500, Andrew Cagney wrote:
> Well the texinfo.  I read the reference as a reference to something 
> completly separate.
> 
> Can you please expand the paragraph to reference: Protocol specific 
> representation of datatypes.

Uhm... sorry but is it possible that you didn't read the texinfo file
created by my patch send the week before but instead the one from
December?  I just looked through the doc and I was a bit surprised
to see that there isn't any reference to B.1 but instead there's
already a "(see @ref{Integral datatypes}, for details)" in it.

I've attached the new version of my patch with the following changes:

- Using M packets for memory transfer is redefined so that the target
  should expect M or X packets.  The current implementation (my patch)
  uses only X packets so far.  I forgot that in the original document.

- The "Integral datatypes" chapter contains a hint that these datatypes
  are passed as big endian when part of a memory transfer of a compound
  type.

- The "Integral datatypes" chapter defines time_t as seconds since Epoch.

- A new "File-I/O Examples" chapter.


Please review if that's ok now,
Corinna

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

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

Index: gdb.texinfo
===================================================================
RCS file: /cvs/src/src/gdb/doc/gdb.texinfo,v
retrieving revision 1.149
diff -u -p -r1.149 gdb.texinfo
--- gdb.texinfo	23 Feb 2003 22:19:48 -0000	1.149
+++ gdb.texinfo	3 Mar 2003 12:07:18 -0000
@@ -14766,6 +14766,7 @@ compiled with the @samp{-pg} compiler op
 * Stop Reply Packets::
 * General Query Packets::
 * Register Packet Format::
+* File-I/O remote protocol extension::
 * Examples::
 @end menu
 
@@ -14991,9 +14992,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}
@@ -15492,6 +15496,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
@@ -15701,6 +15723,1157 @@ 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
+@cindex File-I/O remote protocol extension
+
+@menu
+* File-I/O Overview::
+* 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::
+* File-I/O Examples::
+@end menu
+
+@node File-I/O Overview
+@subsection File-I/O Overview
+@cindex 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 targets that lack file systems.
+
+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, @value{GDBN} 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
+@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:
+
+@itemize @bullet
+@item 
+A unique identifier for the requested system call.
+
+@item
+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.
+
+@item
+@value{GDBN} translates all value from protocol representation to host
+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.
+
+@end itemize
+
+Eventually @value{GDBN} 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
+@code{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 `F' request packet
+@subsection The @code{F} request packet
+@cindex file-i/o request packet
+@cindex @code{F} request packet
+
+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
+@cindex file-i/o reply packet
+@cindex @code{F} reply packet
+
+The @code{F} reply packet has the following format:
+
+@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
+@end smallexample
+
+@noindent
+assuming 4 is the protocol specific representation of @code{EINTR}.
+
+@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
+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 @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
+@subsection Console I/O
+@cindex console i/o as part of file-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, @dots{})} or @code{write(2, @dots{})}).  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 @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 isatty(3) call
+@cindex isatty call, file-i/o protocol
+
+A special case in this protocol is the library call @code{isatty} 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 @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 system(3) call
+@cindex system call, file-i/o protocol
+
+The other special case in this protocol is the @code{system} 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 @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 refused to be called
+by @value{GDBN} by default.  The user has to allow this call explicitly by 
+entering
+
+@table @samp
+@kindex set remote system-call-allowed 1
+@item @code{set remote system-call-allowed 1}
+@end table
+
+Disabling the @code{system} call is done by
+
+@table @samp
+@kindex set remote system-call-allowed 0
+@item @code{set remote system-call-allowed 0}
+@end table
+
+The current setting is shown by typing
+
+@table @samp
+@kindex show remote system-call-allowed
+@item @code{show remote system-call-allowed}
+@end table
+
+@node List of supported calls
+@subsection List of supported calls
+@cindex list of supported file-i/o calls
+
+@menu
+* open::
+* close::
+* read::
+* write::
+* lseek::
+* rename::
+* unlink::
+* stat/fstat::
+* gettimeofday::
+* isatty::
+* system::
+@end menu
+
+@node open
+@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    
+If the file does not exist it will be created.  The host
+rules apply as far as file ownership and time stamps
+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.
+
+@item O_RDONLY   
+The file is opened for reading only.
+
+@item O_WRONLY   
+The file is opened for writing only.
+
+@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    
+User has read permission.
+
+@item S_IWUSR    
+User has write permission.
+
+@item S_IRGRP    
+Group has read permission.
+
+@item S_IWGRP    
+Group has write permission.
+
+@item S_IROTH    
+Others have read permission.
+
+@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.
+
+@item EMFILE     
+The process already has the maximum number of files open.
+
+@item ENFILE     
+The limit on the total number of files open on the system
+has been reached.
+
+@item EINTR      
+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
+host specific maximum file size allowed.
+
+@item ENOSPC     
+No space on device to write the data.
+
+@item EINTR      
+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     
+An attempt was made to make a directory a subdirectory
+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.
+
+@item ENOSPC     
+The device containing the file has no room for the new
+directory entry.
+
+@item EINTR      
+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     
+No access to the file or the path of the file.
+
+@item EPERM      
+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.
+
+@item EROFS      
+The file is on a read-only filesystem.
+
+@item EINTR      
+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
+
+@menu
+* Integral datatypes::
+* Pointer values::
+* struct stat::
+* struct timeval::
+@end menu
+
+@node Integral datatypes
+@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.
+
+@code{time_t} datatypes are defined as seconds since the Epoch.
+
+All integral datatypes transferred as part of a memory read or write of a
+structured datatype e.g.@: a @code{struct stat} have to be given in big endian
+byte order.
+
+@node Pointer values
+@unnumberedsubsubsec Pointer values
+@cindex pointer values, in file-i/o protocol
+
+Pointers to target data are transmitted as they are.  An exception
+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
+
+@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 @{
+    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 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
+struct timeval @{ 
+    time_t tv_sec;  /* second */
+    long   tv_usec; /* microsecond */
+@};
+@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
+@subsection Constants
+@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
+* Open flags::
+* mode_t values::
+* Errno values::
+* Lseek flags::
+* Limits::
+@end menu
+
+@node Open flags
+@unnumberedsubsubsec Open flags
+@cindex open flags, in file-i/o protocol
+
+All values are given in hexadecimal representation.
+
+@smallexample
+  O_RDONLY        0x0
+  O_WRONLY        0x1
+  O_RDWR          0x2
+  O_APPEND        0x8
+  O_CREAT       0x200
+  O_TRUNC       0x400
+  O_EXCL        0x800
+@end smallexample
+
+@node mode_t values
+@unnumberedsubsubsec mode_t values
+@cindex mode_t values, in file-i/o protocol
+
+All values are given in octal representation.
+
+@smallexample
+  S_IFREG       0100000
+  S_IFDIR        040000
+  S_IRUSR          0400
+  S_IWUSR          0200
+  S_IXUSR          0100
+  S_IRGRP           040
+  S_IWGRP           020
+  S_IXGRP           010
+  S_IROTH            04
+  S_IWOTH            02
+  S_IXOTH            01
+@end smallexample
+
+@node Errno values
+@unnumberedsubsubsec Errno values
+@cindex errno values, in file-i/o protocol
+
+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
+@cindex lseek flags, in file-i/o protocol
+
+@smallexample
+  SEEK_SET      0
+  SEEK_CUR      1
+  SEEK_END      2
+@end smallexample
+
+@node Limits
+@unnumberedsubsubsec Limits
+@cindex limits, in file-i/o protocol
+
+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 File-I/O Examples
+@subsection File-I/O Examples
+@cindex file-i/o examples
+
+Example sequence of a write call, file descriptor 3, buffer is at target
+address 0x1234, 6 bytes should be written:
+
+@smallexample
+<- @code{Fwrite,3,1234,6}
+@emph{request memory read from target}
+-> @code{m1234,6}
+<- @code{+}
+<- XXXXXX
+@emph{return "6 bytes written"}
+-> @code{F6}
+<- @code{+}
+@end smallexample
+
+Example sequence of a read call, file descriptor 3, buffer is at target
+address 0x1234, 6 bytes should be read:
+
+@smallexample
+<- @code{Fread,3,1234,6}
+@emph{request memory write to target}
+-> @code{X1234,6:XXXXXX}
+<- @code{+}
+@emph{return "6 bytes read"}
+-> @code{F6}
+<- @code{+}
+@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}
+-> @code{F-1,9}
+<- @code{+}
+@end smallexample
+
+Example sequence of a read call, user presses Ctrl-C before syscall on
+host is called:
+
+@smallexample
+<- @code{Fread,3,1234,6}
+-> @code{F-1,4,C}
+<- @code{+}
+<- @code{T02}
+@end smallexample
+
+Example sequence of a read call, user presses Ctrl-C after syscall on
+host is called:
+
+@smallexample
+<- @code{Fread,3,1234,6}
+-> @code{X1234,6:XXXXXX}
+<- @code{+}
+<- @code{T02}
+-> @code{+}
+@end smallexample
 
 @node Examples
 @section Examples

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

[Andrew Cagney]

[added Eli]

> On Sat, Mar 01, 2003 at 09:58:44PM -0500, Andrew Cagney wrote:
> 
>> Well the texinfo.  I read the reference as a reference to something 
>> completly separate.
>> 
>> Can you please expand the paragraph to reference: Protocol specific 
>> representation of datatypes.
> 
> 
> Uhm... sorry but is it possible that you didn't read the texinfo file
> created by my patch send the week before but instead the one from
> December?  I just looked through the doc and I was a bit surprised
> to see that there isn't any reference to B.1 but instead there's
> already a "(see @ref{Integral datatypes}, for details)" in it.

Yes.  I'm having a `bad hair' day :-(

> I've attached the new version of my patch with the following changes:
> 
> - Using M packets for memory transfer is redefined so that the target
>   should expect M or X packets.  The current implementation (my patch)
>   uses only X packets so far.  I forgot that in the original document.
> 
> - The "Integral datatypes" chapter contains a hint that these datatypes
>   are passed as big endian when part of a memory transfer of a compound
>   type.
> 
> - The "Integral datatypes" chapter defines time_t as seconds since Epoch.
> 
> - A new "File-I/O Examples" chapter.

I just tried to build a pdf file using this patch and it died with:

(/usr/share/texmf/pdftex/plain/misc/pdfcolor.tex) fonts, page headings,
tables, conditionals, indexing, sectioning, toc, environments, defuns, 
macros,
cross references, (/usr/share/texmf/tex/plain/dvips/epsf.tex) localization,
and turning on texinfo input format.) (./gdb.aux
! Missing @endcsname inserted.
<to be read again>
                    @
<argument> The `F@
                    request packet-title
@xrdef ...@endgroup @expandafter @gdef @csname X#1
                                                   @endcsname
l.862 'xrdef {The `F' request packet-title}
                                            {The \code {F} request packet}
?

Changing the line:

	@subsection The @code{F} request packet

(and a second very similar in a similar way) to:

	@subsection The `F' request packet

fixed the problem.  This has me totally puzzled since other @subsection 
lines use @..{} and work fine.

Eli?

Andrew

PS: pdftex on a RHAT 7.2 system.

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

[Eli Zaretskii]

> Date: Tue, 04 Mar 2003 13:53:38 -0500
> From: Andrew Cagney <ac131313@redhat.com>
> 
> Changing the line:
> 
> 	@subsection The @code{F} request packet
> 
> (and a second very similar in a similar way) to:
> 
> 	@subsection The `F' request packet
> 
> fixed the problem.  This has me totally puzzled since other @subsection 
> lines use @..{} and work fine.
> 
> Eli?

Sounds like a bug in pdftex (I don't use it much, so don't have any
clues, sorry): @-commands should work in section names.

Do texi2dvi and TeX grok the original Texinfo?  If they do, this is
worth reporting as a bug to bug-texinfo mailing list (but make sure
you have the latest pdftex first).

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

[Andrew Cagney]

> Do texi2dvi and TeX grok the original Texinfo?  If they do, this is
> worth reporting as a bug to bug-texinfo mailing list (but make sure
> you have the latest pdftex first).

Looks like it was once a bug in texinfo.   Importing a new texinfo.tex 
made the problem `go away' :-)

Andrew

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

[Andrew Cagney]

Corinna,

(solved the pdftex problem)

Can you just tweak the following, then commit:

- move this new file i/o section to after:
	 @node Examples
	 @section Examples
instead of before.  That way the Examples section is closer to the 
documentation that it relates to.

- in the examples, don't worry about including the `+' replies:
	+<- @code{+}
Some are missing and I figure it is easier to just remove all of them :-)

Andrew

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

[Corinna Vinschen]

On Thu, Mar 06, 2003 at 04:26:36PM -0500, Andrew Cagney wrote:
> Corinna,
> 
> (solved the pdftex problem)
> 
> Can you just tweak the following, then commit:
> 
> - move this new file i/o section to after:
> 	 @node Examples
> 	 @section Examples
> instead of before.  That way the Examples section is closer to the 
> documentation that it relates to.

I don't quite understand.  Do you mean to move the whole lot of File-I/O
after the examples or just to move the File-I/O examples to become a
subchapter of the other examples?

> - in the examples, don't worry about including the `+' replies:
> 	+<- @code{+}
> Some are missing and I figure it is easier to just remove all of them :-)

Ok.

Corinna

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

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

[Andrew Cagney]

> 
> I don't quite understand.  Do you mean to move the whole lot of File-I/O
> after the examples

Yes.

 > or just to move the File-I/O examples to become a
> subchapter of the other examples?

No.

Andrew