Update of /cvsroot/scsh/scsh-0.6/doc/scsh-manual
In directory usw-pr-cvs1:/tmp/cvs-serv18564/doc/scsh-manual
Modified Files:
syscalls.tex
Log Message:
Marked select as dereleased
Added fd and port as possible arguments to a lot of file- procedures
Documented new default of *temp-file-template*
Renamed sleep and sleep-until
Index: syscalls.tex
===================================================================
RCS file: /cvsroot/scsh/scsh-0.6/doc/scsh-manual/syscalls.tex,v
retrieving revision 1.1
retrieving revision 1.2
diff -C2 -r1.1 -r1.2
*** syscalls.tex 2001/07/13 06:59:22 1.1
--- syscalls.tex 2001/11/08 08:38:26 1.2
***************
*** 776,823 ****
\defunx{select!}{rvec wvec evec [timeout]}{[nr nw ne]}
\begin{desc}
! The \ex{select} procedure allows a process to block and wait for events on
! multiple I/O channels.
! The \var{rvec} and \var{evec} arguments are vectors of input ports and
! integer file descriptors; \var{wvec} is a vector of output ports and
! integer file descriptors.
! The procedure returns three vectors whose elements are subsets of the
! corresponding arguments.
! Every element of \var{rvec'} is ready for input;
! every element of \var{wvec'} is ready for output;
! every element of \var{evec'} has an exceptional condition pending.
!
! The \ex{select} call will block until at least one of the I/O channels
! passed to it is ready for operation.
! The \var{timeout} value can be used to force the call to time-out
! after a given number of seconds. It defaults to the special value
! \ex{\#f}, meaning wait indefinitely. A zero value can be used to poll
! the I/O channels.
!
! If an I/O channel appears more than once in a given vector---perhaps
! occuring once as a Scheme port, and once as the port's underlying
! integer file descriptor---only one of these two references may appear
! in the returned vector.
! Buffered I/O ports are handled specially---if an input port's buffer is
! not empty, or an output port's buffer is not yet full, then these
! ports are immediately considered eligible for I/O without using
! the actual, primitive \ex{select} system call to check the underlying
! file descriptor.
! This works pretty well for buffered input ports, but is a little
! problematic for buffered output ports.
!
! The \ex{select!} procedure is similar, but indicates the subset
! of active I/O channels by side-effecting the argument vectors.
! Non-active I/O channels in the argument vectors are overwritten with
! {\sharpf} values.
! The call returns the number of active elements remaining in each
! vector.
! As a convenience, the vectors passed in to \ex{select!} are
! 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.}
! \end{desc}
\begin{defundescx}{write-string}{string [fd/port start end]}\undefined
--- 776,822 ----
\defunx{select!}{rvec wvec evec [timeout]}{[nr nw ne]}
\begin{desc}
! \emph{These two procedures have been de-released for version 0.6.
! They will come back in a later verison of Scsh.}
+ % The \ex{select} procedure allows a process to block and wait for
+ % events on multiple I/O channels. The \var{rvec} and \var{evec}
+ % arguments are vectors of input ports and integer file descriptors;
+ % \var{wvec} is a vector of output ports and integer file
+ % descriptors. The procedure returns three vectors whose elements
+ % are subsets of the corresponding arguments. Every element of
+ % \var{rvec'} is ready for input; every element of \var{wvec'} is
+ % ready for output; every element of \var{evec'} has an exceptional
+ % condition pending.
+
+ % The \ex{select} call will block until at least one of the I/O
+ % channels passed to it is ready for operation. The \var{timeout}
+ % value can be used to force the call to time-out after a given
+ % number of seconds. It defaults to the special value \ex{\#f},
+ % meaning wait indefinitely. A zero value can be used to poll the
+ % I/O channels.
+
+ % If an I/O channel appears more than once in a given
+ % vector---perhaps occuring once as a Scheme port, and once as the
+ % port's underlying integer file descriptor---only one of these two
+ % references may appear in the returned vector. Buffered I/O ports
+ % are handled specially---if an input port's buffer is not empty, or
+ % an output port's buffer is not yet full, then these ports are
+ % immediately considered eligible for I/O without using the actual,
+ % primitive \ex{select} system call to check the underlying file
+ % descriptor. This works pretty well for buffered input ports, but
+ % is a little problematic for buffered output ports.
+
+ % The \ex{select!} procedure is similar, but indicates the subset of
+ % active I/O channels by side-effecting the argument vectors.
+ % Non-active I/O channels in the argument vectors are overwritten
+ % with {\sharpf} values. The call returns the number of active
+ % elements remaining in each vector. As a convenience, the vectors
+ % passed in to \ex{select!} are 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.}
+ \end{desc}
\begin{defundescx}{write-string}{string [fd/port start end]}\undefined
***************
*** 1268,1274 ****
\end{desc}
! \defun {file-not-readable?} {fname} \boolean
! \defunx{file-not-writable?} {fname} \boolean
! \defunx{file-not-executable?} {fname} \boolean
\begin{desc}
Returns:
--- 1267,1273 ----
\end{desc}
! \defun {file-not-readable?} {fname/fd/port} \boolean
! \defunx{file-not-writable?} {fname/fd/port} \boolean
! \defunx{file-not-executable?} {fname/fd/port} \boolean
\begin{desc}
Returns:
***************
*** 1319,1325 ****
\end{desc}
! \defun {file-readable?} {fname} \boolean
! \defunx {file-writable?} {fname} \boolean
! \defunx {file-executable?} {fname} \boolean
\begin{desc}
These procedures are the logical negation of the
--- 1318,1324 ----
\end{desc}
! \defun {file-readable?} {fname/fd/port} \boolean
! \defunx {file-writable?} {fname/fd/port} \boolean
! \defunx {file-executable?} {fname/fd/port} \boolean
\begin{desc}
These procedures are the logical negation of the
***************
*** 1328,1332 ****
\end{desc}
! \begin{defundesc}{file-not-exists?} {fname [chase?]} \object
Returns:
\begin{optiontable}
--- 1327,1331 ----
\end{desc}
! \begin{defundesc}{file-not-exists?} {fname/fd/port [chase?]} \object
Returns:
\begin{optiontable}
***************
*** 1339,1343 ****
\end{defundesc}
! \begin{defundesc}{file-exists?} {fname [chase?]} \boolean
This is simply
\ex{(not (file-not-exists? \var{fname} \var{[chase?]}))}
--- 1338,1342 ----
\end{defundesc}
! \begin{defundesc}{file-exists?} {fname/fd/port [chase?]} \boolean
This is simply
\ex{(not (file-not-exists? \var{fname} \var{[chase?]}))}
***************
*** 1557,1561 ****
\ex{Create-temp-file} creates a new temporary file and return its name.
The optional argument specifies the filename prefix to use, and defaults
! to \ex{"/usr/tmp/\var{pid}"}, where \var{pid} is the current process' id.
The procedure generates a sequence of filenames that have \var{prefix} as
a common prefix, looking for a filename that doesn't already exist in the
--- 1556,1561 ----
\ex{Create-temp-file} creates a new temporary file and return its name.
The optional argument specifies the filename prefix to use, and defaults
! to the value of \ex{"\TMPDIR{}/\var{pid}"} if \TMPDIR{} is set and to
! \ex{"/var/tmp/\var{pid}"} otherwise, where \var{pid} is the current
process' id.
The procedure generates a sequence of filenames that have \var{prefix} as
a common prefix, looking for a filename that doesn't already exist in the
***************
*** 1575,1580 ****
not affect correctness.
! Security note: doing i/o to files created this way in \ex{/usr/tmp/} is
! not necessarily secure. General users have write access to \ex{/usr/tmp/},
so even if an attacker cannot access the new temp file, he can delete it
and replace it with one of his own. A subsequent open of this filename
--- 1575,1580 ----
not affect correctness.
! Security note: doing i/o to files created this way in \ex{/var/tmp/} is
! not necessarily secure. General users have write access to \ex{/var/tmp/},
so even if an attacker cannot access the new temp file, he can delete it
and replace it with one of his own. A subsequent open of this filename
***************
*** 1587,1591 ****
\item If the file needs to be opened twice or more, create it in a
protected directory, \eg, \verb|$HOME|.
! \item Ensure that \ex{/usr/tmp} has its sticky bit set. This
requires system administrator privileges.
\end{enumerate}
--- 1587,1591 ----
\item If the file needs to be opened twice or more, create it in a
protected directory, \eg, \verb|$HOME|.
! \item Ensure that \ex{/var/tmp} has its sticky bit set. This
requires system administrator privileges.
\end{enumerate}
***************
*** 1605,1616 ****
\item Creating an unused temporary directory.
\end{itemize}
!
! This procedure uses \var{template} to generate a series of trial file
! names.
! \var{Template} is a \ex{format} control string, and defaults to
! \codex{"/usr/tmp/\var{pid}.\~a"}
! where \var{pid} is the current process' process id.
! File names are generated by calling \ex{format} to instantiate the
! template's \verb|~a| field with a varying string.
\var{Maker} is a procedure which is serially called on each file name
--- 1605,1616 ----
\item Creating an unused temporary directory.
\end{itemize}
!
! This procedure uses \var{template} to generate a series of trial
! file names. \var{Template} is a \ex{format} control string, and
! defaults to \codex{"\TMPDIR{}/\var{pid}.\~a"} if \TMPDIR{} is set
! and \codex{"/var/tmp/\var{pid}.\~a"} otherwise where \var{pid} is
! the current process' process id. File names are generated by
! calling \ex{format} to instantiate the template's \verb|~a| field
! with a varying string.
\var{Maker} is a procedure which is serially called on each file name
***************
*** 1652,1668 ****
\begin{code}
(temp-file-iterate (\l{dir} (create-directory dir) dir)
! "/usr/tmp/tempdir.\~a")\end{code}
%
Similar operations can be used to generate unique symlinks and fifos,
or to return values other than the new filename (\eg, an open file
descriptor or port).
!
! The default template is in fact taken from the value of the dynamic
! variable \ex{*temp-file-template*}, which itself defaults to
! \ex{"/usr/tmp/\var{pid}.\~a"}, where \var{pid} is the scsh process'
! pid.
! For increased security, a user may wish to change the template
! to use a directory not allowing world write access
! (\eg, his home directory).
\end{desc}
--- 1652,1668 ----
\begin{code}
(temp-file-iterate (\l{dir} (create-directory dir) dir)
! "/var/tmp/tempdir.\~a")\end{code}
%
Similar operations can be used to generate unique symlinks and fifos,
or to return values other than the new filename (\eg, an open file
descriptor or port).
!
! The default template is in fact taken from the value of the
! dynamic variable \ex{*temp-file-template*}, which itself defaults
! to \ex{"\TMPDIR{}/\var{pid}.\~a"} if \TMPDIR{} is set and
! \ex{"/usr/tmp/\var{pid}.\~a"} otherwise, where \var{pid} is the
! scsh process' pid. For increased security, a user may wish to
! change the template to use a directory not allowing world write
! access (\eg, his home directory).
\end{desc}
***************
*** 2426,2435 ****
\defunx{pause-until-interrupt}{} \undefined
! \defun{sleep}{secs} \undefined
! \defunx{sleep-until}{time}\undefined
\begin{desc}
! The \ex{sleep} procedure causes the process to sleep for \var{secs} seconds.
! The \ex{sleep-until} procedure causes the process to sleep until \var{time}
! (see section~\ref{sec:time}).
\end{desc}
--- 2426,2440 ----
\defunx{pause-until-interrupt}{} \undefined
! \defun{process-sleep}{secs} \undefined
! \defunx{process-sleep-until}{time}\undefined
\begin{desc}
! The \ex{sleep} procedure causes the process to sleep for \var{secs}
! seconds. The \ex{sleep-until} procedure causes the process to sleep
! until \var{time} (see section~\ref{sec:time}).
!
! \note{The use of these procedures is deprecated as they suspend
! \emph{all} running threads, including the ones Scsh uses for
! administrtive purposes. Consider using the \texttt{sleep}
! procedure from the \texttt{thread} package.}
\end{desc}
***************
*** 2523,2535 ****
\label{table:uncatchable-signals}
\end{table}
! Note that scsh does \emph{not} support signal handlers for ``synchronous''
! {\Unix} signals, such as \ex{signal/ill} or \ex{signal/pipe}
! (see table~\ref{table:uncatchable-signals}).
Synchronous occurrences of these signals are better handled by raising
! a Scheme exception.
! We recommend you avoid using signal handlers unless you absolutely have
! to; we intend to provide a better, higher-level interface to {\Unix}
! signals after scsh has been ported to a multi-threaded platform.
!
\begin{defundesc}{signal->interrupt}{\integer}{\integer}
The programmer maps from {\Unix} signals to {\scm} interrupts with the
--- 2528,2538 ----
\label{table:uncatchable-signals}
\end{table}
! Note that scsh does \emph{not} support signal handlers for
! ``synchronous'' {\Unix} signals, such as \ex{signal/ill} or
! \ex{signal/pipe} (see table~\ref{table:uncatchable-signals}).
Synchronous occurrences of these signals are better handled by raising
! a Scheme exception. We recommend you avoid using signal handlers
! unless you absolutely have to; Section \ref{sec:event-interf-interr}
! describes a better interface to signals.
\begin{defundesc}{signal->interrupt}{\integer}{\integer}
The programmer maps from {\Unix} signals to {\scm} interrupts with the
|