Update of /cvsroot/scsh/scsh/doc/scsh-manual
In directory usw-pr-cvs1:/tmp/cvs-serv16015
Modified Files:
syscalls.tex
Log Message:
Slightly clarify explanation of WITH-ERRNO-HANDLER*.
Index: syscalls.tex
===================================================================
RCS file: /cvsroot/scsh/scsh/doc/scsh-manual/syscalls.tex,v
retrieving revision 1.8
retrieving revision 1.9
diff -C2 -r1.8 -r1.9
*** syscalls.tex 2001/06/01 17:49:20 1.8
--- syscalls.tex 2001/06/13 14:11:49 1.9
***************
*** 50,54 ****
If a {\Unix} error arises while \var{thunk} is executing,
! \var{handler} is called on two arguments:
\codex{(\var{handler} \var{errno} \var{packet})}
\var{packet} is a list of the form
--- 50,54 ----
If a {\Unix} error arises while \var{thunk} is executing,
! \var{handler} is called on two arguments like this:
\codex{(\var{handler} \var{errno} \var{packet})}
\var{packet} is a list of the form
***************
*** 647,652 ****
\begin{tabular}[t]{@{}>{\ttfamily}l@{}}
%% These are gettable and settable
! open/append \\
! open/non-blocking \\
open/async \textrm{(Non-\Posix)} \\
open/fsync \textrm{(Non-\Posix)}
--- 647,652 ----
\begin{tabular}[t]{@{}>{\ttfamily}l@{}}
%% These are gettable and settable
! open/append \\
! open/non-blocking \\
open/async \textrm{(Non-\Posix)} \\
open/fsync \textrm{(Non-\Posix)}
***************
*** 660,666 ****
\begin{tabular}[t]{@{}>{\ttfamily}l@{}}
%% These are gettable, not settable
! open/read \\
! open/write \\
! open/read+write \\
open/access-mask
\end{tabular}
--- 660,666 ----
\begin{tabular}[t]{@{}>{\ttfamily}l@{}}
%% These are gettable, not settable
! open/read \\
! open/write \\
! open/read+write \\
open/access-mask
\end{tabular}
***************
*** 674,692 ****
\begin{tabular}[t]{@{}>{\ttfamily}l@{}}
%% These are neither gettable nor settable.
! open/create \\
! open/exclusive \\
! open/no-control-tty \\
! open/truncate
\end{tabular}
\end{tabular}
\end{center}
\caption{Status flags for \texttt{open-file},
! \texttt{fdes-status} and \texttt{set-fdes-status}.
! Only {\Posix} flags are guaranteed to be present;
! your operating system may define others.
! The \texttt{open/access-mask} value is not an actual flag,
! but a bit mask used to select the field for the \texttt{open/read},
! \texttt{open/write} and \texttt{open/read+write} bits.
! }
\label{table:fdes-status-flags}
\end{table}
--- 674,692 ----
\begin{tabular}[t]{@{}>{\ttfamily}l@{}}
%% These are neither gettable nor settable.
! open/create \\
! open/exclusive \\
! open/no-control-tty \\
! open/truncate
\end{tabular}
\end{tabular}
\end{center}
\caption{Status flags for \texttt{open-file},
! \texttt{fdes-status} and \texttt{set-fdes-status}.
! Only {\Posix} flags are guaranteed to be present;
! your operating system may define others.
! The \texttt{open/access-mask} value is not an actual flag,
! but a bit mask used to select the field for the \texttt{open/read},
! \texttt{open/write} and \texttt{open/read+write} bits.
! }
\label{table:fdes-status-flags}
\end{table}
***************
*** 704,708 ****
\defun{read-string}{nbytes [fd/port]} {{\str} or \sharpf}
\dfnix{read-string!} {str [fd/port start end]} {nread or \sharpf}{procedure}
! {read-string"!@\texttt{read-string"!}}
\begin{desc}
These calls read exactly as much data as you requested, unless
--- 704,708 ----
\defun{read-string}{nbytes [fd/port]} {{\str} or \sharpf}
\dfnix{read-string!} {str [fd/port start end]} {nread or \sharpf}{procedure}
! {read-string"!@\texttt{read-string"!}}
\begin{desc}
These calls read exactly as much data as you requested, unless
***************
*** 732,736 ****
\defun {read-string/partial} {nbytes [fd/port]} {{\str} or \sharpf}
\dfnix{read-string!/partial} {str [fd/port start end]} {nread or \sharpf}
! {procedure}{read-string"!/partial@\texttt{read-string"!/partial}}
\begin{desc}
%
--- 732,736 ----
\defun {read-string/partial} {nbytes [fd/port]} {{\str} or \sharpf}
\dfnix{read-string!/partial} {str [fd/port start end]} {nread or \sharpf}
! {procedure}{read-string"!/partial@\texttt{read-string"!/partial}}
\begin{desc}
%
***************
*** 817,821 ****
\remark{I have found the \ex{select!} interface to be the more
useful of the two. After the system call, it allows you
! to check a specific I/O channel in constant time.}
\end{desc}
--- 817,821 ----
\remark{I have found the \ex{select!} interface to be the more
useful of the two. After the system call, it allows you
! to check a specific I/O channel in constant time.}
\end{desc}
***************
*** 902,912 ****
It may only be used on new ports, \ie, before I/O is performed on the port.
There are three buffering policies that may be chosen:
! \begin{inset}
! \begin{tabular}{l@{\qquad}l}
! \ex{bufpol/block} & General block buffering (general default) \\
! \ex{bufpol/line} & Line buffering (tty default) \\
! \ex{bufpol/none} & Direct I/O---no buffering
! \end{tabular}
! \end{inset}
The line buffering policy flushes output whenever a newline is output;
whenever the buffer is full; or whenever an input is read from stdin.
--- 902,912 ----
It may only be used on new ports, \ie, before I/O is performed on the port.
There are three buffering policies that may be chosen:
! \begin{inset}
! \begin{tabular}{l@{\qquad}l}
! \ex{bufpol/block} & General block buffering (general default) \\
! \ex{bufpol/line} & Line buffering (tty default) \\
! \ex{bufpol/none} & Direct I/O---no buffering
! \end{tabular}
! \end{inset}
The line buffering policy flushes output whenever a newline is output;
whenever the buffer is full; or whenever an input is read from stdin.
***************
*** 1238,1247 ****
\remark{\ex{file-info} was named \ex{file-attributes} in releases of scsh
prior to release 0.4. We changed the name to \ex{file-info} for
! consistency with the other information-retrieval procedures in
! scsh: \ex{user-info}, \ex{group-info}, \ex{host-info},
! \ex{network-info }, \ex{service-info}, and \ex{protocol-info}.
! The \ex{file-attributes} binding is still supported in the current
! release of scsh, but is deprecated, and may go away in a future
release.}
\end{defundesc}
--- 1238,1247 ----
\remark{\ex{file-info} was named \ex{file-attributes} in releases of scsh
prior to release 0.4. We changed the name to \ex{file-info} for
! consistency with the other information-retrieval procedures in
! scsh: \ex{user-info}, \ex{group-info}, \ex{host-info},
! \ex{network-info }, \ex{service-info}, and \ex{protocol-info}.
! The \ex{file-attributes} binding is still supported in the current
! release of scsh, but is deprecated, and may go away in a future
release.}
\end{defundesc}
***************
*** 1461,1468 ****
\begin{defundesc}{file-match}{root dot-files? \vari{pat}1 \vari{pat}2
{\ldots} \vari{pat}n}{string list}
\note{This procedure is deprecated, and will probably either go away or
! be substantially altered in a future release. New code should not
! call this procedure. The problem is that it relies upon
! Posix-notation regular expressions; the rest of scsh has been
! converted over to the new SRE notation.}
\ex{file-match} provides a more powerful file-matching service, at the
--- 1461,1468 ----
\begin{defundesc}{file-match}{root dot-files? \vari{pat}1 \vari{pat}2
{\ldots} \vari{pat}n}{string list}
\note{This procedure is deprecated, and will probably either go away or
! be substantially altered in a future release. New code should not
! call this procedure. The problem is that it relies upon
! Posix-notation regular expressions; the rest of scsh has been
! converted over to the new SRE notation.}
\ex{file-match} provides a more powerful file-matching service, at the
***************
*** 1870,1874 ****
(set-current-input-port! (fdes->inport 0)
! (read-line) ; Read the string output by the child.\end{code}
None of this is necessary when the I/O is performed by an exec'd
program in the child or parent process, only when the pipe will
--- 1870,1874 ----
(set-current-input-port! (fdes->inport 0)
! (read-line) ; Read the string output by the child.\end{code}
None of this is necessary when the I/O is performed by an exec'd
program in the child or parent process, only when the pipe will
***************
*** 1894,1898 ****
\begin{code}
(define-record proc
! pid)\end{code}
\index{proc}\index{proc?}\index{proc:pid}
The only exposed slot in a proc record is the process' pid,
--- 1894,1898 ----
\begin{code}
(define-record proc
! pid)\end{code}
\index{proc}\index{proc?}\index{proc:pid}
The only exposed slot in a proc record is the process' pid,
***************
*** 1912,1919 ****
\begin{tabular}{|l|l|}
\hline
! \var{probe?} & Return \\ \hline\hline
! \sharpf & \emph{signal error condition.} \\ \hline
! \ex{'create} & Create new proc object. \\ \hline
! True value & \sharpf \\ \hline
\end{tabular}
\end{center}
--- 1912,1919 ----
\begin{tabular}{|l|l|}
\hline
! \var{probe?} & Return \\ \hline\hline
! \sharpf & \emph{signal error condition.} \\ \hline
! \ex{'create} & Create new proc object. \\ \hline
! True value & \sharpf \\ \hline
\end{tabular}
\end{center}
***************
*** 1971,1997 ****
\begin{description}
\item [early]
! The child is reaped from the {\Unix} kernel's process table
! into scsh as soon as it dies. This is done by having a
signal handler for the \ex{SIGCHLD} signal reap the process.
! \emph{
! If a scsh program sets its own handler for the \ex{SIGCHLD}
! signal, the handler must reap dead children
! by calling \ex{wait}, \ex{wait-any}, or \ex{reap-zombies}.}
! We deprecate interrupt-driven code, and hope to provide
! alternative tools in a future, multi-threaded release of scsh.
\item [late]
! The child is not autoreaped until it dies \emph{and} the scsh program
! drops all pointers to its process object. That is, the process
! table is cleaned out during garbage collection.
! \oops{The \ex{late} policy is not supported under the current
! release of scsh. It requires more sophisticated gc hooks than
! we can get from the release of {\scm} that we use.}
\item [\sharpf]
! If autoreaping is turned off, process reaping is completely under
! control of the programmer, who can force outstanding zombies to
! be reaped by manually calling the \ex{reap-zombies} procedure
! (see below).
\end{description}
Note that under any of the autoreap policies, a particular process $p$ can
--- 1971,1997 ----
\begin{description}
\item [early]
! The child is reaped from the {\Unix} kernel's process table
! into scsh as soon as it dies. This is done by having a
signal handler for the \ex{SIGCHLD} signal reap the process.
! \emph{
! If a scsh program sets its own handler for the \ex{SIGCHLD}
! signal, the handler must reap dead children
! by calling \ex{wait}, \ex{wait-any}, or \ex{reap-zombies}.}
! We deprecate interrupt-driven code, and hope to provide
! alternative tools in a future, multi-threaded release of scsh.
\item [late]
! The child is not autoreaped until it dies \emph{and} the scsh program
! drops all pointers to its process object. That is, the process
! table is cleaned out during garbage collection.
! \oops{The \ex{late} policy is not supported under the current
! release of scsh. It requires more sophisticated gc hooks than
! we can get from the release of {\scm} that we use.}
\item [\sharpf]
! If autoreaping is turned off, process reaping is completely under
! control of the programmer, who can force outstanding zombies to
! be reaped by manually calling the \ex{reap-zombies} procedure
! (see below).
\end{description}
Note that under any of the autoreap policies, a particular process $p$ can
***************
*** 2073,2085 ****
additional options. It is composed by or'ing together the following
flags:
! \begin{center}
! \begin{tabular}{|l|l|}
! \hline
! Flag & Meaning \\ \hline
\hline
! \ex{wait/poll} & Return {\sharpf} immediately if
! child still active. \\ \hline
! \ex{wait/stopped-children} & Wait for suspend as well as exit. \\
\hline
! \end{tabular}
! \end{center}
\end{desc}
--- 2073,2085 ----
additional options. It is composed by or'ing together the following
flags:
! \begin{center}
! \begin{tabular}{|l|l|}
! \hline
! Flag & Meaning \\ \hline
\hline
! \ex{wait/poll} & Return {\sharpf} immediately if
! child still active. \\ \hline
! \ex{wait/stopped-children} & Wait for suspend as well as exit.
\\ \hline
! \end{tabular}
! \end{center}
\end{desc}
***************
*** 2087,2104 ****
The optional \var{flags} argument is as for \ex{wait}.
This procedure waits for any child process to exit (or stop, if the
! \ex{wait/stopped-children} flag is used)
It returns the process' process object and status code.
If there are no children left for which to wait, the two values
! \ex{[{\sharpf} {\sharpt}]} are returned.
If the \ex{wait/poll} flag is used, and none of the children
are immediately eligble for waiting,
! then the values \ex{[{\sharpf} {\sharpf}]} are returned:
! \begin{center}
! \begin{tabular}{|l|l|}
! \hline
! [{\sharpf} {\sharpf}] & Poll, none ready \\ \hline
! [{\sharpf} {\sharpt}] & No children \\ \hline
! \end{tabular}
! \end{center}
\ex{Wait-any} will not return a process that has been previously waited
--- 2087,2104 ----
The optional \var{flags} argument is as for \ex{wait}.
This procedure waits for any child process to exit (or stop, if the
! \ex{wait/stopped-children} flag is used)
It returns the process' process object and status code.
If there are no children left for which to wait, the two values
! \ex{[{\sharpf} {\sharpt}]} are returned.
If the \ex{wait/poll} flag is used, and none of the children
are immediately eligble for waiting,
! then the values \ex{[{\sharpf} {\sharpf}]} are returned:
! \begin{center}
! \begin{tabular}{|l|l|}
! \hline
! [{\sharpf} {\sharpf}] & Poll, none ready \\ \hline
! [{\sharpf} {\sharpt}] & No children \\ \hline
! \end{tabular}
! \end{center}
\ex{Wait-any} will not return a process that has been previously waited
***************
*** 2168,2172 ****
%returns true iff \ex{(\var{proc})} returns at all.
%\remark{The current implementation is a constant function returning
{\sharpt},
! % which suffices for all {\Unix} implementations of which we are
aware.}
%\end{desc}
--- 2168,2172 ----
%returns true iff \ex{(\var{proc})} returns at all.
%\remark{The current implementation is a constant function returning
{\sharpt},
! % which suffices for all {\Unix} implementations of which we are
aware.}
%\end{desc}
***************
*** 2454,2490 ****
Interrupt & Unix signal & OS Variant \\ \hline\hline
\kwd{interrupt/alrm}\footnote{Also bound to {\scm} interrupt
! \kwd{interrupt/alarm}.}
! & \kwd{signal/alrm} & \Posix \\
%
\kwd{interrupt/int}\footnote{Also bound to {\scm} interrupt
! \kwd{interrupt/keyboard}.}
! & \kwd{signal/int} & \Posix \\
%
! \kwd{interrupt/memory-shortage} & N/A & \\
! \kwd{interrupt/chld} & \kwd{signal/chld} & \Posix \\
! \kwd{interrupt/cont} & \kwd{signal/cont} & \Posix \\
! \kwd{interrupt/hup} & \kwd{signal/hup} & \Posix \\
! \kwd{interrupt/quit} & \kwd{signal/quit} & \Posix \\
! \kwd{interrupt/term} & \kwd{signal/term} & \Posix \\
! \kwd{interrupt/tstp} & \kwd{signal/tstp} & \Posix \\
! \kwd{interrupt/usr1} & \kwd{signal/usr1} & \Posix \\
! \kwd{interrupt/usr2} & \kwd{signal/usr2} & \Posix \\
\\
! \kwd{interrupt/info} & \kwd{signal/info} & BSD only \\
! \kwd{interrupt/io} & \kwd{signal/io} & BSD + SVR4 \\
! \kwd{interrupt/poll} & \kwd{signal/poll} & SVR4 only \\
! \kwd{interrupt/prof} & \kwd{signal/prof} & BSD + SVR4 \\
! \kwd{interrupt/pwr} & \kwd{signal/pwr} & SVR4 only \\
! \kwd{interrupt/urg} & \kwd{signal/urg} & BSD + SVR4 \\
! \kwd{interrupt/vtalrm} & \kwd{signal/vtalrm} & BSD + SVR4 \\
! \kwd{interrupt/winch} & \kwd{signal/winch} & BSD + SVR4 \\
! \kwd{interrupt/xcpu} & \kwd{signal/xcpu} & BSD + SVR4 \\
! \kwd{interrupt/xfsz} & \kwd{signal/xfsz} & BSD + SVR4 \\
\end{tabular}
\end{center}
\caption{{\scm} virtual-machine interrupts and related {\Unix} signals.
! Only the {\Posix} signals are guaranteed to be defined; however,
! your implementation and OS may define other signals and
! interrupts not listed here.}
\end{minipage}
\label{table:signals-and-interrupts}
--- 2454,2490 ----
Interrupt & Unix signal & OS Variant \\ \hline\hline
\kwd{interrupt/alrm}\footnote{Also bound to {\scm} interrupt
! \kwd{interrupt/alarm}.}
! & \kwd{signal/alrm} & \Posix \\
%
\kwd{interrupt/int}\footnote{Also bound to {\scm} interrupt
! \kwd{interrupt/keyboard}.}
! & \kwd{signal/int} & \Posix \\
%
! \kwd{interrupt/memory-shortage} & N/A & \\
! \kwd{interrupt/chld} & \kwd{signal/chld} & \Posix \\
! \kwd{interrupt/cont} & \kwd{signal/cont} & \Posix \\
! \kwd{interrupt/hup} & \kwd{signal/hup} & \Posix \\
! \kwd{interrupt/quit} & \kwd{signal/quit} & \Posix \\
! \kwd{interrupt/term} & \kwd{signal/term} & \Posix \\
! \kwd{interrupt/tstp} & \kwd{signal/tstp} & \Posix \\
! \kwd{interrupt/usr1} & \kwd{signal/usr1} & \Posix \\
! \kwd{interrupt/usr2} & \kwd{signal/usr2} & \Posix \\
\\
! \kwd{interrupt/info} & \kwd{signal/info} & BSD only \\
! \kwd{interrupt/io} & \kwd{signal/io} & BSD + SVR4 \\
! \kwd{interrupt/poll} & \kwd{signal/poll} & SVR4 only \\
! \kwd{interrupt/prof} & \kwd{signal/prof} & BSD + SVR4 \\
! \kwd{interrupt/pwr} & \kwd{signal/pwr} & SVR4 only \\
! \kwd{interrupt/urg} & \kwd{signal/urg} & BSD + SVR4 \\
! \kwd{interrupt/vtalrm} & \kwd{signal/vtalrm} & BSD + SVR4 \\
! \kwd{interrupt/winch} & \kwd{signal/winch} & BSD + SVR4 \\
! \kwd{interrupt/xcpu} & \kwd{signal/xcpu} & BSD + SVR4 \\
! \kwd{interrupt/xfsz} & \kwd{signal/xfsz} & BSD + SVR4 \\
\end{tabular}
\end{center}
\caption{{\scm} virtual-machine interrupts and related {\Unix} signals.
! Only the {\Posix} signals are guaranteed to be defined; however,
! your implementation and OS may define other signals and
! interrupts not listed here.}
\end{minipage}
\label{table:signals-and-interrupts}
***************
*** 2496,2524 ****
\begin{tabular}{lll}\hline
Unix signal & Type & OS Variant \\ \hline\hline
! \kwd{signal/stop} & Uncatchable & \Posix \\
! \kwd{signal/kill} & Uncatchable & \Posix \\
\\
! \kwd{signal/abrt} & Synchronous & \Posix \\
! \kwd{signal/fpe} & Synchronous & \Posix \\
! \kwd{signal/ill} & Synchronous & \Posix \\
! \kwd{signal/pipe} & Synchronous & \Posix \\
! \kwd{signal/segv} & Synchronous & \Posix \\
! \kwd{signal/ttin} & Synchronous & \Posix \\
! \kwd{signal/ttou} & Synchronous & \Posix \\
\\
! \kwd{signal/bus} & Synchronous & BSD + SVR4 \\
! \kwd{signal/emt} & Synchronous & BSD + SVR4 \\
! \kwd{signal/iot} & Synchronous & BSD + SVR4 \\
! \kwd{signal/sys} & Synchronous & BSD + SVR4 \\
! \kwd{signal/trap} & Synchronous & BSD + SVR4 \\
\end{tabular}
\end{center}
\caption{Uncatchable and synchronous {\Unix} signals. While these signals
may be sent with \texttt{signal-process} or
! \texttt{signal-process-group},
there are no corresponding scsh interrupt handlers.
Only the {\Posix} signals are guaranteed to be defined; however,
! your implementation and OS may define other signals not listed
! here.}
\label{table:uncatchable-signals}
\end{table}
--- 2496,2524 ----
\begin{tabular}{lll}\hline
Unix signal & Type & OS Variant \\ \hline\hline
! \kwd{signal/stop} & Uncatchable & \Posix \\
! \kwd{signal/kill} & Uncatchable & \Posix \\
\\
! \kwd{signal/abrt} & Synchronous & \Posix \\
! \kwd{signal/fpe} & Synchronous & \Posix \\
! \kwd{signal/ill} & Synchronous & \Posix \\
! \kwd{signal/pipe} & Synchronous & \Posix \\
! \kwd{signal/segv} & Synchronous & \Posix \\
! \kwd{signal/ttin} & Synchronous & \Posix \\
! \kwd{signal/ttou} & Synchronous & \Posix \\
\\
! \kwd{signal/bus} & Synchronous & BSD + SVR4 \\
! \kwd{signal/emt} & Synchronous & BSD + SVR4 \\
! \kwd{signal/iot} & Synchronous & BSD + SVR4 \\
! \kwd{signal/sys} & Synchronous & BSD + SVR4 \\
! \kwd{signal/trap} & Synchronous & BSD + SVR4 \\
\end{tabular}
\end{center}
\caption{Uncatchable and synchronous {\Unix} signals. While these signals
may be sent with \texttt{signal-process} or
! \texttt{signal-process-group},
there are no corresponding scsh interrupt handlers.
Only the {\Posix} signals are guaranteed to be defined; however,
! your implementation and OS may define other signals not listed
! here.}
\label{table:uncatchable-signals}
\end{table}
***************
*** 2605,2610 ****
\end{defundesc}
! % %set-unix-signal-handler
! % %unix-signal-handler
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
--- 2605,2610 ----
\end{defundesc}
! % %set-unix-signal-handler
! % %unix-signal-handler
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
***************
*** 2715,2725 ****
\begin{inset}
\begin{tabular}{lp{0.7\linewidth}}
! \ex{\#f} & Local time \\
! Integer & Seconds of offset from UTC. For example,
! New York City is -18000 (-5 hours), San Francisco
! is -28800 (-8 hours). \\
! String & A {\Posix} time zone string understood by the OS
! (\ie., the sort of time zone assigned to the \ex{\$TZ}
! environment variable).
\end{tabular}
\end{inset}
--- 2715,2725 ----
\begin{inset}
\begin{tabular}{lp{0.7\linewidth}}
! \ex{\#f} & Local time \\
! Integer & Seconds of offset from UTC. For example,
! New York City is -18000 (-5 hours), San Francisco
! is -28800 (-8 hours). \\
! String & A {\Posix} time zone string understood by the OS
! (\ie., the sort of time zone assigned to the \ex{\$TZ}
! environment variable).
\end{tabular}
\end{inset}
***************
*** 2751,2773 ****
\begin{remarkenv}
! I chose to represent system clock resolution as ticks/sec
! instead of sec/tick to increase the odds that the value could
! be represented as an exact integer, increasing efficiency and
making it easier for Scheme implementations that don't have
! sophisticated numeric support to deal with the quantity.
! You can convert seconds and ticks to seconds with the expression
! \codex{(+ \var{secs} (/ \var{ticks} (ticks/sec)))}
! Given that, why not have the fine-grain time procedure just
! return a non-integer real for time? Following Common Lisp, I chose to
! allow the system clock to report sub-second time in its own units to
! lower the overhead of determining the time. This would be important
! for a system that wanted to precisely time the duration of some
! event. Time stamps could be collected with little overhead, deferring
! the overhead of precisely calculating with them until after collection.
! This is all a bit academic for the {\scm} implementation, where
! we determine time with a heavyweight system call, but it's nice
! to plan for the future.
\end{remarkenv}
\end{desc}
--- 2751,2773 ----
\begin{remarkenv}
! I chose to represent system clock resolution as ticks/sec
! instead of sec/tick to increase the odds that the value could
! be represented as an exact integer, increasing efficiency and
making it easier for Scheme implementations that don't have
! sophisticated numeric support to deal with the quantity.
! You can convert seconds and ticks to seconds with the expression
! \codex{(+ \var{secs} (/ \var{ticks} (ticks/sec)))}
! Given that, why not have the fine-grain time procedure just
! return a non-integer real for time? Following Common Lisp, I chose to
! allow the system clock to report sub-second time in its own units to
! lower the overhead of determining the time. This would be important
! for a system that wanted to precisely time the duration of some
! event. Time stamps could be collected with little overhead, deferring
! the overhead of precisely calculating with them until after
collection.
! This is all a bit academic for the {\scm} implementation, where
! we determine time with a heavyweight system call, but it's nice
! to plan for the future.
\end{remarkenv}
\end{desc}
***************
*** 2793,2798 ****
Scsh resolves the ambiguity in a paranoid fashion: it always
reports an error if the underlying Unix facility returns -1.
! We feel your pain.
! }
\end{desc}
--- 2793,2798 ----
Scsh resolves the ambiguity in a paranoid fashion: it always
reports an error if the underlying Unix facility returns -1.
! We feel your pain.
! }
\end{desc}
***************
*** 2816,2821 ****
\begin{tightinset}
\begin{tabular}{ll}
! \ex{\#f} & Resolve an ambiguous time in favor of non-summer time. \\
! true & Resolve an ambiguous time in favor of summer time.
\end{tabular}
\end{tightinset}
--- 2816,2821 ----
\begin{tightinset}
\begin{tabular}{ll}
! \ex{\#f} & Resolve an ambiguous time in favor of non-summer time. \\
! true & Resolve an ambiguous time in favor of summer time.
\end{tabular}
\end{tightinset}
***************
*** 2841,2845 ****
form:
\begin{tightinset}
! Sun Sep 16 01:03:52 1973
\end{tightinset}
--- 2841,2845 ----
form:
\begin{tightinset}
! Sun Sep 16 01:03:52 1973
\end{tightinset}
***************
*** 2859,2868 ****
\verb|~B| & full month name \\
\verb|~c| & time and date using the time and date representation
! for the locale (\verb|~X ~x|) \\
\verb|~d| & day of the month as a decimal number (01-31) \\
\verb|~H| & hour based on a 24-hour clock
! as a decimal number (00-23) \\
\verb|~I| & hour based on a 12-hour clock
! as a decimal number (01-12) \\
\verb|~j| & day of the year as a decimal number (001-366) \\
\verb|~m| & month as a decimal number (01-12) \\
--- 2859,2868 ----
\verb|~B| & full month name \\
\verb|~c| & time and date using the time and date representation
! for the locale (\verb|~X ~x|) \\
\verb|~d| & day of the month as a decimal number (01-31) \\
\verb|~H| & hour based on a 24-hour clock
! as a decimal number (00-23) \\
\verb|~I| & hour based on a 12-hour clock
! as a decimal number (01-12) \\
\verb|~j| & day of the year as a decimal number (001-366) \\
\verb|~m| & month as a decimal number (01-12) \\
***************
*** 2871,2878 ****
\verb|~S| & second as a decimal number (00-61) \\
\verb|~U| & week number of the year;
! Sunday is first day of week (00-53) \\
\verb|~w| & weekday as a decimal number (0-6), where Sunday is 0 \\
\verb|~W| & week number of the year;
! Monday is first day of week (00-53) \\
\verb|~x| & date using the date representation for the locale \\
\verb|~X| & time using the time representation for the locale \\
--- 2871,2878 ----
\verb|~S| & second as a decimal number (00-61) \\
\verb|~U| & week number of the year;
! Sunday is first day of week (00-53) \\
\verb|~w| & weekday as a decimal number (0-6), where Sunday is 0 \\
\verb|~W| & week number of the year;
! Monday is first day of week (00-53) \\
\verb|~x| & date using the date representation for the locale \\
\verb|~X| & time using the time representation for the locale \\
***************
*** 2880,2884 ****
\verb|~Y| & year with century (\eg 1990) \\
\verb|~Z| & time zone name or abbreviation, or no characters
! if no time zone is determinable
\end{tabular}
--- 2880,2884 ----
\verb|~Y| & year with century (\eg 1990) \\
\verb|~Z| & time zone name or abbreviation, or no characters
! if no time zone is determinable
\end{tabular}
***************
*** 2910,2917 ****
% \begin{inset}
% \begin{tabular}{lp{0.7\linewidth}}
! % Integer & A time value.
! % The variant in use at that time is returned. \\
! % \ex{\#f} & The standard time name is returned. \\
! % \emph{Otherwise} & The summer time name is returned.
% \end{tabular}
% \end{inset}
--- 2910,2917 ----
% \begin{inset}
% \begin{tabular}{lp{0.7\linewidth}}
! % Integer & A time value.
! % The variant in use at that time is returned.
\\
! % \ex{\#f} & The standard time name is returned. \\
! % \emph{Otherwise} & The summer time name is returned.
% \end{tabular}
% \end{inset}
***************
*** 2921,2925 ****
\dfni {fill-in-date!}{date}{date}{procedure}
! {fill-in-date"!@\texttt{fill-in-date"!}}
\begin{desc}
This procedure fills in missing, redundant slots in a date record.
--- 2921,2925 ----
\dfni {fill-in-date!}{date}{date}{procedure}
! {fill-in-date"!@\texttt{fill-in-date"!}}
\begin{desc}
This procedure fills in missing, redundant slots in a date record.
***************
*** 3112,3117 ****
%\remark{An earlier release of scsh provided the \ex{split-colon-list}
% and \ex{string-list->colon-list} functions. These have been
! % removed from scsh, and are replaced by the more general
! % parsers and unparsers of the field-reader module.}
%
%\defun {split-colon-list} {string} {{\str} list}
--- 3112,3117 ----
%\remark{An earlier release of scsh provided the \ex{split-colon-list}
% and \ex{string-list->colon-list} functions. These have been
! % removed from scsh, and are replaced by the more general
! % parsers and unparsers of the field-reader module.}
%
%\defun {split-colon-list} {string} {{\str} list}
|