Documentation for crypt and dot-locking.

doc/scsh-manual/miscprocs.tex

@@ -32,14 +32,65 @@ from the lists returned by the field-readers (chapter~\ref{chapt:fr-awk}).
 \section{Top level}
 \defun{repl}{}\undefined
 \begin{desc}
-	This runs a {\scm} read-eval-print loop, 
+        This runs a {\scm} read-eval-print loop, 
-	reading forms from the current input port, 
+        reading forms from the current input port, 
-	and writing their values to the current output port.
+        and writing their values to the current output port.
 
-	If you wish to try something dangerous,
+        If you wish to try something dangerous,
-	and want to be able to recover your shell state, you can
+        and want to be able to recover your shell state, you can
-	fork off a subshell with the following form:
+        fork off a subshell with the following form:
-	\codex{(run (begin (repl)))}
+        \codex{(run (begin (repl)))}
-	{\ldots}or, rephrased for the proceduralists:
+        {\ldots}or, rephrased for the proceduralists:
-	\codex{(wait (fork repl))}
+        \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.
+
+
+
+