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']} \defun {select }{rvec wvec evec [timeout]}{[rvec' wvec' evec']}
\defunx{select!}{rvec wvec evec [timeout]}{[nr nw ne]} \defunx{select!}{rvec wvec evec [timeout]}{[nr nw ne]}
\begin{desc} \begin{desc}
The \ex{select} procedure allows a process to block and wait for events on \emph{These two procedures have been de-released for version 0.6.
multiple I/O channels. They will come back in a later verison of Scsh.}
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 % The \ex{select} procedure allows a process to block and wait for
passed to it is ready for operation. % events on multiple I/O channels. The \var{rvec} and \var{evec}
The \var{timeout} value can be used to force the call to time-out % arguments are vectors of input ports and integer file descriptors;
after a given number of seconds. It defaults to the special value % \var{wvec} is a vector of output ports and integer file
\ex{\#f}, meaning wait indefinitely. A zero value can be used to poll % descriptors. The procedure returns three vectors whose elements
the I/O channels. % are subsets of the corresponding arguments. Every element of
% \var{rvec'} is ready for input; every element of \var{wvec'} is
If an I/O channel appears more than once in a given vector---perhaps % ready for output; every element of \var{evec'} has an exceptional
occuring once as a Scheme port, and once as the port's underlying % condition pending.
integer file descriptor---only one of these two references may appear
in the returned vector. % The \ex{select} call will block until at least one of the I/O
Buffered I/O ports are handled specially---if an input port's buffer is % channels passed to it is ready for operation. The \var{timeout}
not empty, or an output port's buffer is not yet full, then these % value can be used to force the call to time-out after a given
ports are immediately considered eligible for I/O without using % number of seconds. It defaults to the special value \ex{\#f},
the actual, primitive \ex{select} system call to check the underlying % meaning wait indefinitely. A zero value can be used to poll the
file descriptor. % I/O channels.
This works pretty well for buffered input ports, but is a little
problematic for buffered output ports. % If an I/O channel appears more than once in a given
% vector---perhaps occuring once as a Scheme port, and once as the
The \ex{select!} procedure is similar, but indicates the subset % port's underlying integer file descriptor---only one of these two
of active I/O channels by side-effecting the argument vectors. % references may appear in the returned vector. Buffered I/O ports
Non-active I/O channels in the argument vectors are overwritten with % are handled specially---if an input port's buffer is not empty, or
{\sharpf} values. % an output port's buffer is not yet full, then these ports are
The call returns the number of active elements remaining in each % immediately considered eligible for I/O without using the actual,
vector. % primitive \ex{select} system call to check the underlying file
As a convenience, the vectors passed in to \ex{select!} are % descriptor. This works pretty well for buffered input ports, but
allowed to contain {\sharpf} values as well as integers and ports. % is a little problematic for buffered output ports.
\remark{I have found the \ex{select!} interface to be the more % The \ex{select!} procedure is similar, but indicates the subset of
useful of the two. After the system call, it allows you % active I/O channels by side-effecting the argument vectors.
to check a specific I/O channel in constant time.} % 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} \end{desc}
\begin{defundescx}{write-string}{string [fd/port start end]}\undefined \begin{defundescx}{write-string}{string [fd/port start end]}\undefined
This procedure writes all the data requested. This procedure writes all the data requested.
If the procedure cannot perform the write with a single kernel call 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} \codex{(file-directory? "/usr/dalbertz")\qquad\evalto\qquad\sharpt}
\end{desc} \end{desc}
\defun {file-not-readable?} {fname} \boolean \defun {file-not-readable?} {fname/fd/port} \boolean
\defunx{file-not-writable?} {fname} \boolean \defunx{file-not-writable?} {fname/fd/port} \boolean
\defunx{file-not-executable?} {fname} \boolean \defunx{file-not-executable?} {fname/fd/port} \boolean
\begin{desc} \begin{desc}
Returns: Returns:
\begin{optiontable} \begin{optiontable}
@ -1318,16 +1317,16 @@ For example,
are tolerated. are tolerated.
\end{desc} \end{desc}
\defun {file-readable?} {fname} \boolean \defun {file-readable?} {fname/fd/port} \boolean
\defunx {file-writable?} {fname} \boolean \defunx {file-writable?} {fname/fd/port} \boolean
\defunx {file-executable?} {fname} \boolean \defunx {file-executable?} {fname/fd/port} \boolean
\begin{desc} \begin{desc}
These procedures are the logical negation of the These procedures are the logical negation of the
preceding \ex{file-not-\ldots?} procedures. preceding \ex{file-not-\ldots?} procedures.
Refer to them for a discussion of their problems and limitations. Refer to them for a discussion of their problems and limitations.
\end{desc} \end{desc}
\begin{defundesc}{file-not-exists?} {fname [chase?]} \object \begin{defundesc}{file-not-exists?} {fname/fd/port [chase?]} \object
Returns: Returns:
\begin{optiontable} \begin{optiontable}
\sharpf & Exists. \\ \sharpf & Exists. \\
@ -1338,7 +1337,7 @@ Returns:
\end{optiontable} \end{optiontable}
\end{defundesc} \end{defundesc}
\begin{defundesc}{file-exists?} {fname [chase?]} \boolean \begin{defundesc}{file-exists?} {fname/fd/port [chase?]} \boolean
This is simply This is simply
\ex{(not (file-not-exists? \var{fname} \var{[chase?]}))} \ex{(not (file-not-exists? \var{fname} \var{[chase?]}))}
\end{defundesc} \end{defundesc}
@ -1556,7 +1555,8 @@ delimiter.
\begin{defundesc} {create-temp-file} {[prefix]} \str \begin{defundesc} {create-temp-file} {[prefix]} \str
\ex{Create-temp-file} creates a new temporary file and return its name. \ex{Create-temp-file} creates a new temporary file and return its name.
The optional argument specifies the filename prefix to use, and defaults 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 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 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} 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 that collisions are less likely to occur. This speeds things up, but does
not affect correctness. not affect correctness.
Security note: doing i/o to files created this way in \ex{/usr/tmp/} is 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{/usr/tmp/}, 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 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 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 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. only needs to be opened once.
\item If the file needs to be opened twice or more, create it in a \item If the file needs to be opened twice or more, create it in a
protected directory, \eg, \verb|$HOME|. 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. requires system administrator privileges.
\end{enumerate} \end{enumerate}
The actual default prefix used is controlled by the dynamic variable 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 and opening an unused, secure temp file.
\item Creating an unused temporary directory. \item Creating an unused temporary directory.
\end{itemize} \end{itemize}
This procedure uses \var{template} to generate a series of trial file This procedure uses \var{template} to generate a series of trial
names. file names. \var{Template} is a \ex{format} control string, and
\var{Template} is a \ex{format} control string, and defaults to defaults to \codex{"\TMPDIR{}/\var{pid}.\~a"} if \TMPDIR{} is set
\codex{"/usr/tmp/\var{pid}.\~a"} and \codex{"/var/tmp/\var{pid}.\~a"} otherwise where \var{pid} is
where \var{pid} is the current process' process id. the current process' process id. File names are generated by
File names are generated by calling \ex{format} to instantiate the calling \ex{format} to instantiate the template's \verb|~a| field
template's \verb|~a| field with a varying string. with a varying string.
\var{Maker} is a procedure which is serially called on each file name \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 generated. It must return at least one value; it may return multiple
@ -1651,19 +1651,19 @@ delimiter.
To create a unique temporary directory: To create a unique temporary directory:
\begin{code} \begin{code}
(temp-file-iterate (\l{dir} (create-directory dir) dir) (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, Similar operations can be used to generate unique symlinks and fifos,
or to return values other than the new filename (\eg, an open file or to return values other than the new filename (\eg, an open file
descriptor or port). descriptor or port).
The default template is in fact taken from the value of the dynamic The default template is in fact taken from the value of the
variable \ex{*temp-file-template*}, which itself defaults to dynamic variable \ex{*temp-file-template*}, which itself defaults
\ex{"/usr/tmp/\var{pid}.\~a"}, where \var{pid} is the scsh process' to \ex{"\TMPDIR{}/\var{pid}.\~a"} if \TMPDIR{} is set and
pid. \ex{"/usr/tmp/\var{pid}.\~a"} otherwise, where \var{pid} is the
For increased security, a user may wish to change the template scsh process' pid. For increased security, a user may wish to
to use a directory not allowing world write access change the template to use a directory not allowing world write
(\eg, his home directory). access (\eg, his home directory).
\end{desc} \end{desc}
\defun{temp-file-channel}{} {[inp outp]} \defun{temp-file-channel}{} {[inp outp]}
@ -2425,12 +2425,17 @@ or integer process ids.
\defun{itimer}{???} \undefined \defun{itimer}{???} \undefined
\defunx{pause-until-interrupt}{} \undefined \defunx{pause-until-interrupt}{} \undefined
\defun{sleep}{secs} \undefined \defun{process-sleep}{secs} \undefined
\defunx{sleep-until}{time}\undefined \defunx{process-sleep-until}{time}\undefined
\begin{desc} \begin{desc}
The \ex{sleep} procedure causes the process to sleep for \var{secs} seconds. The \ex{sleep} procedure causes the process to sleep for \var{secs}
The \ex{sleep-until} procedure causes the process to sleep until \var{time} seconds. The \ex{sleep-until} procedure causes the process to sleep
(see section~\ref{sec:time}). 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} \end{desc}
\subsubsection{Interrupt handlers} \subsubsection{Interrupt handlers}
@ -2522,15 +2527,13 @@ Unix signal & Type & OS Variant \\ \hline\hline
here.} here.}
\label{table:uncatchable-signals} \label{table:uncatchable-signals}
\end{table} \end{table}
Note that scsh does \emph{not} support signal handlers for ``synchronous'' Note that scsh does \emph{not} support signal handlers for
{\Unix} signals, such as \ex{signal/ill} or \ex{signal/pipe} ``synchronous'' {\Unix} signals, such as \ex{signal/ill} or
(see table~\ref{table:uncatchable-signals}). \ex{signal/pipe} (see table~\ref{table:uncatchable-signals}).
Synchronous occurrences of these signals are better handled by raising Synchronous occurrences of these signals are better handled by raising
a Scheme exception. a Scheme exception. We recommend you avoid using signal handlers
We recommend you avoid using signal handlers unless you absolutely have unless you absolutely have to; Section \ref{sec:event-interf-interr}
to; we intend to provide a better, higher-level interface to {\Unix} describes a better interface to signals.
signals after scsh has been ported to a multi-threaded platform.
\begin{defundesc}{signal->interrupt}{\integer}{\integer} \begin{defundesc}{signal->interrupt}{\integer}{\integer}
The programmer maps from {\Unix} signals to {\scm} interrupts with the The programmer maps from {\Unix} signals to {\scm} interrupts with the
\ex{signal->interrupt} procedure. \ex{signal->interrupt} procedure.