Slightly clarify explanation of WITH-ERRNO-HANDLER*.
This commit is contained in:
sperber
parent
a40ff4b314
commit
baa65dee1d
|
|
@ -49,7 +49,7 @@ Programs can use \ex{with-errno-handler*} to establish
|
|||
handlers for these exceptions.
|
||||
|
||||
If a {\Unix} error arises while \var{thunk} is executing,
|
||||
\var{handler} is called on two arguments:
|
||||
\var{handler} is called on two arguments like this:
|
||||
\codex{(\var{handler} \var{errno} \var{packet})}
|
||||
\var{packet} is a list of the form
|
||||
$$\var{packet} = \ex{(\var{errno-msg} \var{syscall} . \var{data})},$$
|
||||
|
|
@ -646,8 +646,8 @@ These procedures allow reading and writing of an open file's status flags
|
|||
%
|
||||
\begin{tabular}[t]{@{}>{\ttfamily}l@{}}
|
||||
%% These are gettable and settable
|
||||
open/append \\
|
||||
open/non-blocking \\
|
||||
open/append \\
|
||||
open/non-blocking \\
|
||||
open/async \textrm{(Non-\Posix)} \\
|
||||
open/fsync \textrm{(Non-\Posix)}
|
||||
\end{tabular}
|
||||
|
|
@ -659,9 +659,9 @@ These procedures allow reading and writing of an open file's status flags
|
|||
%
|
||||
\begin{tabular}[t]{@{}>{\ttfamily}l@{}}
|
||||
%% These are gettable, not settable
|
||||
open/read \\
|
||||
open/write \\
|
||||
open/read+write \\
|
||||
open/read \\
|
||||
open/write \\
|
||||
open/read+write \\
|
||||
open/access-mask
|
||||
\end{tabular}
|
||||
\\\cline{2-3}
|
||||
|
|
@ -673,21 +673,21 @@ These procedures allow reading and writing of an open file's status flags
|
|||
%
|
||||
\begin{tabular}[t]{@{}>{\ttfamily}l@{}}
|
||||
%% These are neither gettable nor settable.
|
||||
open/create \\
|
||||
open/exclusive \\
|
||||
open/no-control-tty \\
|
||||
open/truncate
|
||||
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.
|
||||
}
|
||||
\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}
|
||||
|
||||
|
|
@ -703,7 +703,7 @@ Returns two ports, the read and write end-points of a {\Unix} pipe.
|
|||
|
||||
\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"!}}
|
||||
{read-string"!@\texttt{read-string"!}}
|
||||
\begin{desc}
|
||||
These calls read exactly as much data as you requested, unless
|
||||
there is not enough data (eof).
|
||||
|
|
@ -731,7 +731,7 @@ Returns two ports, the read and write end-points of a {\Unix} pipe.
|
|||
|
||||
\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}}
|
||||
{procedure}{read-string"!/partial@\texttt{read-string"!/partial}}
|
||||
\begin{desc}
|
||||
%
|
||||
These are atomic best-effort/forward-progress calls.
|
||||
|
|
@ -816,7 +816,7 @@ allowed to contain {\sharpf} values as well as integers and ports.
|
|||
|
||||
\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.}
|
||||
to check a specific I/O channel in constant time.}
|
||||
\end{desc}
|
||||
|
||||
|
||||
|
|
@ -901,13 +901,13 @@ This procedure allows the programmer to assign a particular I/O buffering
|
|||
policy to a port, and to choose the size of the associated buffer.
|
||||
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}
|
||||
\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.
|
||||
Line buffering is the default for ports open on terminal devices.
|
||||
|
|
@ -1237,12 +1237,12 @@ Example:
|
|||
|
||||
\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}.
|
||||
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
|
||||
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}
|
||||
|
||||
|
|
@ -1460,10 +1460,10 @@ All wild-card characters in \var{str} are quoted with a backslash.
|
|||
|
||||
\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.}
|
||||
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
|
||||
expense of a less convenient notation. It is intermediate in
|
||||
|
|
@ -1869,7 +1869,7 @@ Suspend the current process with a SIGSTOP signal.
|
|||
(display "Hello, world.\\n"))))
|
||||
|
||||
(set-current-input-port! (fdes->inport 0)
|
||||
(read-line) ; Read the string output by the child.\end{code}
|
||||
(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
|
||||
be referenced by Scheme code through one of the default current I/O
|
||||
|
|
@ -1893,7 +1893,7 @@ They are created by the \ex{fork} procedure, and have the following
|
|||
exposed structure:
|
||||
\begin{code}
|
||||
(define-record proc
|
||||
pid)\end{code}
|
||||
pid)\end{code}
|
||||
\index{proc}\index{proc?}\index{proc:pid}
|
||||
The only exposed slot in a proc record is the process' pid,
|
||||
the integer id assigned by Unix to the process.
|
||||
|
|
@ -1911,10 +1911,10 @@ If there is no process object in the system indexed by the given pid,
|
|||
\begin{center}
|
||||
\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
|
||||
\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}
|
||||
\end{defundesc}
|
||||
|
|
@ -1970,29 +1970,29 @@ The policy is determined by applying this procedure to one of the
|
|||
values \ex{'early}, \ex{'late}, or {\sharpf} (\ie, no autoreap).
|
||||
\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
|
||||
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.
|
||||
\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.}
|
||||
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).
|
||||
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
|
||||
be manually reaped into scsh by simply calling \ex{(wait $p$)}.
|
||||
|
|
@ -2072,34 +2072,34 @@ forms, or use \ex{wait-any} to wait for the children to exit.
|
|||
The \var{flags} argument is an integer whose bits specify
|
||||
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}
|
||||
\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}
|
||||
|
||||
\begin{defundesc} {wait-any} {[flags]} {[proc status]}
|
||||
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)
|
||||
\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.
|
||||
\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}
|
||||
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
|
||||
by any other process-wait procedure (\ex{wait}, \ex{wait-any},
|
||||
|
|
@ -2167,7 +2167,7 @@ Otherwise, this function returns false.
|
|||
%This procedure, ported from early T implementations,
|
||||
%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.}
|
||||
% which suffices for all {\Unix} implementations of which we are aware.}
|
||||
%\end{desc}
|
||||
|
||||
\section{Process state}
|
||||
|
|
@ -2453,39 +2453,39 @@ asynchronous {\Unix} signals (table~\ref{table:signals-and-interrupts}).
|
|||
\begin{tabular}{lll}\hline
|
||||
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/alarm}.}
|
||||
& \kwd{signal/alrm} & \Posix \\
|
||||
%
|
||||
\kwd{interrupt/int}\footnote{Also bound to {\scm} interrupt
|
||||
\kwd{interrupt/keyboard}.}
|
||||
& \kwd{signal/int} & \Posix \\
|
||||
\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/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 \\
|
||||
\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.}
|
||||
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}
|
||||
\end{table}
|
||||
|
|
@ -2495,31 +2495,31 @@ Interrupt & Unix signal & OS Variant \\ \hline\hline
|
|||
\begin{center}
|
||||
\begin{tabular}{lll}\hline
|
||||
Unix signal & Type & OS Variant \\ \hline\hline
|
||||
\kwd{signal/stop} & Uncatchable & \Posix \\
|
||||
\kwd{signal/kill} & Uncatchable & \Posix \\
|
||||
\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/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 \\
|
||||
\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},
|
||||
\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.}
|
||||
your implementation and OS may define other signals not listed
|
||||
here.}
|
||||
\label{table:uncatchable-signals}
|
||||
\end{table}
|
||||
Note that scsh does \emph{not} support signal handlers for ``synchronous''
|
||||
|
|
@ -2604,8 +2604,8 @@ A handler is either \ex{\#f} (ignore), \ex{\#t} (default), or a
|
|||
procedure taking an integer argument.
|
||||
\end{defundesc}
|
||||
|
||||
% %set-unix-signal-handler
|
||||
% %unix-signal-handler
|
||||
% %set-unix-signal-handler
|
||||
% %unix-signal-handler
|
||||
|
||||
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
|
||||
\section{Time}
|
||||
|
|
@ -2714,13 +2714,13 @@ This is described for each procedure below.
|
|||
can be one of:
|
||||
\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).
|
||||
\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}
|
||||
An integer time zone gives the number of seconds you must add to UTC
|
||||
|
|
@ -2750,25 +2750,25 @@ String & A {\Posix} time zone string understood by the OS
|
|||
is always 0, and \ex{(ticks/sec)} returns 1.
|
||||
|
||||
\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
|
||||
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.
|
||||
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.
|
||||
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.
|
||||
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}
|
||||
|
||||
|
|
@ -2792,8 +2792,8 @@ String & A {\Posix} time zone string understood by the OS
|
|||
is also a legal return value (for date 23:59:59 UCT, 12/31/1969).
|
||||
Scsh resolves the ambiguity in a paranoid fashion: it always
|
||||
reports an error if the underlying Unix facility returns -1.
|
||||
We feel your pain.
|
||||
}
|
||||
We feel your pain.
|
||||
}
|
||||
\end{desc}
|
||||
|
||||
\defun {time} {} \integer
|
||||
|
|
@ -2815,8 +2815,8 @@ String & A {\Posix} time zone string understood by the OS
|
|||
\ex{summer?} field is used to resolve ambiguities:
|
||||
\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.
|
||||
\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}
|
||||
This is useful in boundary cases during the change-over. For example,
|
||||
|
|
@ -2840,7 +2840,7 @@ true & Resolve an ambiguous time in favor of summer time.
|
|||
\ex{Date->string} formats the date as a 24-character string of the
|
||||
form:
|
||||
\begin{tightinset}
|
||||
Sun Sep 16 01:03:52 1973
|
||||
Sun Sep 16 01:03:52 1973
|
||||
\end{tightinset}
|
||||
|
||||
\ex{Format-date} formats the date according to the format string
|
||||
|
|
@ -2858,28 +2858,28 @@ true & Resolve an ambiguous time in favor of summer time.
|
|||
\verb|~b| & abbreviated month name \\
|
||||
\verb|~B| & full month name \\
|
||||
\verb|~c| & time and date using the time and date representation
|
||||
for the locale (\verb|~X ~x|) \\
|
||||
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) \\
|
||||
as a decimal number (00-23) \\
|
||||
\verb|~I| & hour based on a 12-hour clock
|
||||
as a decimal number (01-12) \\
|
||||
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) \\
|
||||
\verb|~M| & minute as a decimal number (00-59) \\
|
||||
\verb|~p| & AM/PM designation associated with a 12-hour clock \\
|
||||
\verb|~S| & second as a decimal number (00-61) \\
|
||||
\verb|~U| & week number of the year;
|
||||
Sunday is first day of week (00-53) \\
|
||||
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) \\
|
||||
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 \\
|
||||
\verb|~y| & year without century (00-99) \\
|
||||
\verb|~Y| & year with century (\eg 1990) \\
|
||||
\verb|~Z| & time zone name or abbreviation, or no characters
|
||||
if no time zone is determinable
|
||||
if no time zone is determinable
|
||||
\end{tabular}
|
||||
|
||||
\caption{\texttt{format-date} conversion specifiers}
|
||||
|
|
@ -2909,10 +2909,10 @@ true & Resolve an ambiguous time in favor of summer time.
|
|||
% (\eg, ``EST'' and ``EDT'')\@. \var{Summer?} is interpreted as follows:
|
||||
% \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.
|
||||
% 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}
|
||||
% \ex{Summer?} defaults to the case that pertains at the time of the call.
|
||||
|
|
@ -2920,7 +2920,7 @@ true & Resolve an ambiguous time in favor of summer time.
|
|||
%\end{desc}
|
||||
|
||||
\dfni {fill-in-date!}{date}{date}{procedure}
|
||||
{fill-in-date"!@\texttt{fill-in-date"!}}
|
||||
{fill-in-date"!@\texttt{fill-in-date"!}}
|
||||
\begin{desc}
|
||||
This procedure fills in missing, redundant slots in a date record.
|
||||
In decreasing order of priority:
|
||||
|
|
@ -3111,8 +3111,8 @@ once they have been parsed from their colon-separated form.
|
|||
|
||||
%\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.}
|
||||
% 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}
|
||||
%\defunx {string-list->colon-list} {string-list} \str
|
||||
|
|
|
|||
Loading…
Reference in New Issue