scsh-checkins
[Top] [All Lists]

## [Scsh-checkins] CVS: scsh-0.6/doc/scsh-manual syscalls.tex,1.1,1.2

 To: scsh-checkins@lists.sourceforge.net [Scsh-checkins] CVS: scsh-0.6/doc/scsh-manual syscalls.tex,1.1,1.2 Martin Gasbichler Thu Nov 8 00:39:02 2001 scsh-checkins-admin@lists.sourceforge.net
 Update of /cvsroot/scsh/scsh-0.6/doc/scsh-manual In directory usw-pr-cvs1:/tmp/cvs-serv18564/doc/scsh-manual Modified Files: syscalls.tex Log Message: 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 Index: syscalls.tex =================================================================== RCS file: /cvsroot/scsh/scsh-0.6/doc/scsh-manual/syscalls.tex,v retrieving revision 1.1 retrieving revision 1.2 diff -C2 -r1.1 -r1.2 *** syscalls.tex 2001/07/13 06:59:22 1.1 --- syscalls.tex 2001/11/08 08:38:26 1.2 *************** *** 776,823 **** \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. ! ! 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 --- 776,822 ---- \defunx{select!}{rvec wvec evec [timeout]}{[nr nw ne]} \begin{desc} ! \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} 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 *************** *** 1268,1274 **** \end{desc} ! \defun {file-not-readable?} {fname} \boolean ! \defunx{file-not-writable?} {fname} \boolean ! \defunx{file-not-executable?} {fname} \boolean \begin{desc} Returns: --- 1267,1273 ---- \end{desc} ! \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: *************** *** 1319,1325 **** \end{desc} ! \defun {file-readable?} {fname} \boolean ! \defunx {file-writable?} {fname} \boolean ! \defunx {file-executable?} {fname} \boolean \begin{desc} These procedures are the logical negation of the --- 1318,1324 ---- \end{desc} ! \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 *************** *** 1328,1332 **** \end{desc} ! \begin{defundesc}{file-not-exists?} {fname [chase?]} \object Returns: \begin{optiontable} --- 1327,1331 ---- \end{desc} ! \begin{defundesc}{file-not-exists?} {fname/fd/port [chase?]} \object Returns: \begin{optiontable} *************** *** 1339,1343 **** \end{defundesc} ! \begin{defundesc}{file-exists?} {fname [chase?]} \boolean This is simply \ex{(not (file-not-exists? \var{fname} \var{[chase?]}))} --- 1338,1342 ---- \end{defundesc} ! \begin{defundesc}{file-exists?} {fname/fd/port [chase?]} \boolean This is simply \ex{(not (file-not-exists? \var{fname} \var{[chase?]}))} *************** *** 1557,1561 **** \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. 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 --- 1556,1561 ---- \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 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 *************** *** 1575,1580 **** 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/}, 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 --- 1575,1580 ---- not affect correctness. ! 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 *************** *** 1587,1591 **** \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 requires system administrator privileges. \end{enumerate} --- 1587,1591 ---- \item If the file needs to be opened twice or more, create it in a protected directory, \eg, \verb|$HOME|. ! \item Ensure that \ex{/var/tmp} has its sticky bit set. This requires system administrator privileges. \end{enumerate} *************** *** 1605,1616 **** \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. \var{Maker} is a procedure which is serially called on each file name --- 1605,1616 ---- \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{"\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 *************** *** 1652,1668 **** \begin{code} (temp-file-iterate (\l{dir} (create-directory dir) dir) ! "/usr/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). \end{desc} --- 1652,1668 ---- \begin{code} (temp-file-iterate (\l{dir} (create-directory dir) dir) ! "/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{"\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} *************** *** 2426,2435 **** \defunx{pause-until-interrupt}{} \undefined ! \defun{sleep}{secs} \undefined ! \defunx{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}). \end{desc} --- 2426,2440 ---- \defunx{pause-until-interrupt}{} \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}). ! ! \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} *************** *** 2523,2535 **** \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}). 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. ! \begin{defundesc}{signal->interrupt}{\integer}{\integer} The programmer maps from {\Unix} signals to {\scm} interrupts with the --- 2528,2538 ---- \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}). 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; 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 
 Current Thread [Scsh-checkins] CVS: scsh-0.6/doc/scsh-manual syscalls.tex,1.1,1.2, Martin Gasbichler <=