%&latex -*- latex -*-

\chapter{Miscellaneous routines}

\section{Integer bitwise ops}
\label{sec:bitwise}
\defun{arithmetic-shift} {i j} \integer
\defunx {bitwise-and} {i j} \integer
\defunx {bitwise-ior} {i j} \integer
\defunx {bitwise-not} {i} \integer
\defunx {bitwise-xor} {i j} \integer
\begin{desc}
    These operations operate on integers representing semi-infinite 
    bit strings, using a 2's-complement encoding.

    \ex{arithmetic-shift} shifts \var{i} by \var{j} bits. 
    A left shift is $j > 0$; a right shift is $j < 0$.
\end{desc}

\section{List procedures}
\defun{nth}{list i}\object
\begin{desc}
Returns the $i^{\mathrm th}$ element of \var{list}.
The first element (the car) is \ex{(nth \var{list} 0)},
the second element is \ex{(nth \var{list} 1)}, and so on.

This procedure is provided as it is useful for accessing elements
from the lists returned by the field-readers (chapter~\ref{chapt:fr-awk}).
\end{desc}


\section{Top level}
\defun{repl}{}\undefined
\begin{desc}
        This runs a {\scm} read-eval-print loop, 
        reading forms from the current input port, 
        and writing their values to the current output port.

        If you wish to try something dangerous,
        and want to be able to recover your shell state, you can
        fork off a subshell with the following form:
        \codex{(run (begin (repl)))}
        {\ldots}or, rephrased for the proceduralists:
        \codex{(wait (fork repl))}
\end{desc}

\section{Password encryption}

\defun {crypt} {key salt} {encrypted value}

Decrypts \var{key} by directly calling the \texttt{crypt} function
using \var{salt} to perturb the hashing algorithm. \var{Salt} must be
a two-character string consisting of digits, alphabetic characters,
``.'' or ``\verb+\+''. The length of \var{key} may be at most eight.

\section{Dot-Locking}
Section \ref{sec:filelocking} already points out that {\Posix}'s file
locks are almost useless in practice. To bypass this restriction other
advisory locking mechanisms, based only on standard file operations,
where invented. One of them is the so-called \emph{dot-locking} scheme
where the lock of \textit{filename} is represented by the file
\textit{filename}\texttt{.lock}. Care is taken that only one process
may generate the lock for a given file.

Here is scsh's interface to dot-locking:

\defun {obtain-dot-lock} {filename [interval retry-number]} {\boolean}

Tries to obtain the lock for \var{filename}. If the file is already
locked, the thread sleeps for \var{interval} milliseconds (default is
1000) before it retries. If the lock cannot be obtained after
\var{retry-number} attempts, the procedure returns \sharpf, otherwise
\sharpt. The default value of \var{retry-number} is \sharpf which
corresponds to an infinite number of retires.

\defun {release-dot-lock} {filename} {\boolean}

Releases the lock for \var{filename}. On success,
\ex{release-dot-lock} returns \sharpt, otherwise \sharpf. Note that
this procedure can also be used to break the lock for \var{filename}.

\defun{with-dot-lock*} {filename thunk} {value(s) of thunk}
\dfnx {with-dot-lock} {filename body \ldots} {value(s) of body}{syntax}

This procedure obtains the requested lock, and then calls 
\ex{(\var{thunk})}. When \var{thunk} returns, the lock is released.
A non-local exit (\eg, throwing to a saved continuation or raising
an exception) also causes the lock to be released.

After a normal return from \var{thunk}, its return values are returned
by \ex{with-dot-lock*}.
The \ex{with-dot-lock} special form is equivalent syntactic sugar.