scsh-conservatory
/
scsh-0.6
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

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
This commit is contained in:
mainzelm 2001-11-08 08:38:26 +00:00
parent 937cc307d5
commit 143d96954b
1 changed files with 87 additions and 84 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

171
doc/scsh-manual/syscalls.tex
View File

@ -775,51 +775,50 @@ Returns two ports, the read and write end-points of a {\Unix} pipe.
\defun {select }{rvec wvec evec [timeout]}{[rvec' wvec' evec']}
\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.
\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} 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.}
% 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
This procedure writes all the data requested.
If the procedure cannot perform the write with a single kernel call
@ -1267,9 +1266,9 @@ For example,
\codex{(file-directory? "/usr/dalbertz")\qquad\evalto\qquad\sharpt}
\end{desc}
\defun {file-not-readable?} {fname} \boolean
\defunx{file-not-writable?} {fname} \boolean
\defunx{file-not-executable?} {fname} \boolean
\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:
\begin{optiontable}
@ -1318,16 +1317,16 @@ For example,
are tolerated.
\end{desc}
\defun {file-readable?} {fname} \boolean
\defunx {file-writable?} {fname} \boolean
\defunx {file-executable?} {fname} \boolean
\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
preceding \ex{file-not-\ldots?} procedures.
Refer to them for a discussion of their problems and limitations.
\end{desc}
\begin{defundesc}{file-not-exists?} {fname [chase?]} \object
\begin{defundesc}{file-not-exists?} {fname/fd/port [chase?]} \object
Returns:
\begin{optiontable}
\sharpf & Exists. \\
@ -1338,7 +1337,7 @@ Returns:
\end{optiontable}
\end{defundesc}
\begin{defundesc}{file-exists?} {fname [chase?]} \boolean
\begin{defundesc}{file-exists?} {fname/fd/port [chase?]} \boolean
This is simply
\ex{(not (file-not-exists? \var{fname} \var{[chase?]}))}
\end{defundesc}
@ -1556,7 +1555,8 @@ delimiter.
\begin{defundesc} {create-temp-file} {[prefix]} \str
\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.
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
file system. When it finds one, it creates it, with permission \cd{#o600}
@ -1574,8 +1574,8 @@ delimiter.
that collisions are less likely to occur. This speeds things up, but does
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/},
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
will then give you his file, to which he has access rights. There are
@ -1586,7 +1586,7 @@ delimiter.
only needs to be opened once.
\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
\item Ensure that \ex{/var/tmp} has its sticky bit set. This
requires system administrator privileges.
\end{enumerate}
The actual default prefix used is controlled by the dynamic variable
@ -1604,14 +1604,14 @@ delimiter.
\item Creating and opening an unused, secure temp file.
\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.
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
generated. It must return at least one value; it may return multiple
@ -1651,19 +1651,19 @@ delimiter.
To create a unique temporary directory:
\begin{code}
(temp-file-iterate (\l{dir} (create-directory dir) dir)
"/usr/tmp/tempdir.\~a")\end{code}
"/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{"/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).
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}
\defun{temp-file-channel}{} {[inp outp]}
@ -2425,12 +2425,17 @@ or integer process ids.
\defun{itimer}{???} \undefined
\defunx{pause-until-interrupt}{} \undefined
\defun{sleep}{secs} \undefined
\defunx{sleep-until}{time}\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}).
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}
\subsubsection{Interrupt handlers}
@ -2522,15 +2527,13 @@ Unix signal & Type & OS Variant \\ \hline\hline
here.}
\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}).
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.
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
\ex{signal->interrupt} procedure.