diff --git a/doc/scsh-manual/syscalls.tex b/doc/scsh-manual/syscalls.tex index 2a1deb8..aa7985e 100644 --- a/doc/scsh-manual/syscalls.tex +++ b/doc/scsh-manual/syscalls.tex @@ -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.