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