Update of /cvsroot/scsh/scsh-0.6/doc
In directory usw-pr-cvs1:/tmp/cvs-serv27695/doc
Added Files:
cheat.txt scsh.man
Log Message:
Added from 0.5 tree.
--- NEW FILE ---
Scsh cheat sheet
Olin Shivers
November 1996
This cheat sheet is intentionally kept brief and minimalist.
It is intended to function as an ASCII-format reminder for the
full manual, not as the definition. It can be read using GNU Emacs's
outline mode.
It is also not entirely up-to-date. I'd appreciate getting updates from users.
-------------------------------------------------------------------------------
* High-level forms
Extended process form:
(PF [REDIR1 ...])
Redirection:
(< [FDES] FILE-NAME)
(> [FDES] FILE-NAME)
(<< [FDES] OBJECT)
(= FDES FDES/PORT)
(- FDES/PORT)
stdports
Subforms are implicitly backquoted.
Process form:
(| PF1 ...) ; pipeline
(|+ CONNECT-LIST PF1 ...) ; complex pipeline
(begin . BODY) ; Scheme form
(epf . EPF) ; Embedded extended process form
(PROG ARG1 ... ARGn) ; Exec a program
Subforms are implicitly backquoted.
Using process forms in Scheme:
(exec-epf . EPF) ; Nuke the current process.
(& . EPF) ; Fork process in background. Return proc object.
(run . EPF) ; Run process. Return exit code.
(& . EPF) = (fork (lambda () (exec-epf . EPF)))
(run . EPF) = (wait (& . EPF))
Interfacing to subprocess I/O:
(run/port . EPF) -> port
(run/file . EPF) -> string
(run/string . EPF) -> string
(run/strings . EPF) -> string list
(run/sexp . EPF) -> object
(run/sexps . EPF) -> list
There are procedural equivalents for each of these, e.g., run/port* and
run/file*, that take thunk arguments for the subprocess.
(port->string PORT) -> string
Read until EOF on PORT, return data as a string.
(port->string-list PORT) -> string list
Repeatedly apply READ-LINE to PORT until EOF. Return list of lines read.
(port->sexp-list PORT) -> list
Repeatedly apply READ to PORT until EOF. Return list of items read.
(port->list READER PORT)
Repeatedly apply READER to PORT until EOF. Return list of items read.
(reduce-port PORT READER OP . SEEDS)
Evaluate (OP (READER PORT) . SEEDS) to get a new set of seeds
(OP must return as many values as there are SEEDS). When
a port read returns EOF, the current set of seed values are
returned as multiple values.
(run/port+proc . EPF) -> [port proc]
(run/port+proc* THUNK) -> [port proc]
(run/collecting FDS . EPF) -> [port ...]
(run/collecting* FDS THUNK) -> [port ...]
RUN/COLLECTING implicitly backquotes FDS.
(|| PF1 ... PFn)
(&& PF1 ... PFn)
Conditionally execute processes.
(char-filter filter) -> procedure
(string-filter filter [buflen]) -> procedure
* System calls
** Errors
(errno-error errno SYSCALL . DATA)
(with-errno-handler* HANDLER THUNK) -> value of thunk
HANDLER is called on two arguments: (HANDLER ERRNO PACKET)
where PACKET is a list of the form (ERRNO-MSG SYSCALL . DATA)
If HANDLER returns at all, the handler search continues upwards.
(with-errno-handler HANDLER-SPEC . BODY)
HANDLER-SPEC is of the form
((ERRNO PACKET) CLAUSE ...)
ERRNO and PACKET are variables bound to the errno error being raised.
There are two forms for handler clauses:
((ERRNO ...) . BODY)
(else . BODY)
ERRNO are expressions evaluating to errno integers.
** I/O
*** Port Manipulation
(close-after PORT CONSUMER) -> value(s) of consumer
(error-output-port) -> port
(with-current-input-port port . body) -> value(s) of body
(with-current-output-port port . body) -> value(s) of body
(with-error-output-port port . body) -> value(s) of body
(with-current-input-port* port thunk) -> value(s) of thunk
(with-current-output-port* port thunk) -> value(s) of thunk
(with-error-output-port* port thunk) -> value(s) of thunk
(close fd/port)
(stdports->stdio)
(stdio->stdports)
(with-stdio-ports* thunk) -> value(s) of thunk
(with-stdio-ports . body) -> value(s) of body
(make-string-input-port) -> port
(string-output-port-output port) -> port
(call-with-string-output-port proc) -> str
** Port and file descriptors
(fdes->inport fd) -> port
(fdes->outport fd) -> port
(port->fdes port) -> fixnum
Increment port's revealed count.
(port-revealed port) -> integer or #f
(release-port-handle port)
(call/fdes fd/port consumer) -> value(s) of consumer
(move->fdes fd/port target-fd) -> port or fdes
** Unix I/O
(dup fd/port [newfd]) -> fd/port
(dup->inport fd/port [newfd]) -> port
(dup->outport fd/port [newfd]) -> port
(dup->fdes fd/port [newfd]) -> fd
(file-seek fd/port offset whence)
(open-file fname flags [perms]) -> port
(open-input-file fname [flags]) -> port
(open-output-file fname [flags perms]) -> port
(open-fdes fname flags [perms]) -> integer
(fdes-flags fd/port)
(set-fdes-flags fd/port flags)
Only Posix flag defined is FDFLAGS/CLOSE-ON-EXEC, which you should
not ever have to use -- scsh manages this automatically.
(fdes-status fd/port)
(set-fdes-flags fd/port flags)
Operations allowed Flags
------------------ -----
Open+get+set open/append, open/non-blocking
open/async, open/fsync (non-Posix)
Open+get open/read, open/write, open/read+write
open/access-mask
Open only open/create, open/exclusive,
open/no-control-tty, open/truncate
(pipe) -> [rport wport]
(read-line [fd/port retain-newline?]) -> string or eof-object
(read-string nbytes [fd/port]) -> string or #f
(read-string! str [fd/port start end]) -> [nread or #f]
(read-string/partial nbytes [fd/port]) -> string or #f
(read-string!/partial str [fd/port start end]) -> [nread or #f]
(write-string string [fd/port start end])
(write-string/partial string [fd/port start end]) -> nwritten
(force-output [fd/port])
** File locking
(define-record lock-region
exclusive? ; write or read lock?
start ; integer: start, end & whence
end ; integer: define the region being locked.
whence ; The value of SEEK/SET, SEEK/DELTA, or SEEK/END.
proc) ; A proc object for the process locking the region.
(make-lock-region exclusive? start len [whence]) -> lock-region
WHENCE defaults to the value of SEEK/SET.
(lock-region fdes lock)
(lock-region/no-block fdes lock)
(get-lock-region fdes lock) -> lock-region or #f
(unlock-region fdes lock)
(with-region-lock* fdes lock thunk)
(with-region-lock fdes lock body ...) Syntax
** File system
(create-directory fname [perms override?])
(create-fifo fname [perms override?])
(create-hard-link oldname newname [override?])
OVERRIDE? one of {#f, QUERY, other true value}
(delete-directory fname)
(delete-file fname)
(delete-filesys-object fname)
(read-symlink fname) -> string
(rename-file old-fname new-fname [override?])
(set-file-mode fname/fd/port mode)
(set-file-owner fname/fd/port uid)
(set-file-group fname/fd/port gid)
(sync-file fd/port)
(sync-file-system)
(truncate-file fname/fd/port len)
(file-attributes fname/fd/port [chase?]) -> file-info
(define-record file-info
type ; {block-special, char-special, directory,
; fifo, regular, socket, symlink}
device ; Device file resides on.
inode ; File's inode.
mode ; File's permission bits.
nlinks ; Number of hard links to this file.
uid ; Owner of file.
gid ; File's group id.
size ; Size of file, in bytes.
atime ; Last access time.
mtime ; Last status-change time.
ctime) ; Creation time.
Derived procedures:
file-type type
file-inode inode
file-mode mode
file-nlinks nlinks
file-owner uid
file-group gid
file-size size
file-last-access atime
file-last-mod mtime
file-last-status-change ctime
(file-not-readable? fname) -> boolean
(file-not-writable? fname) -> boolean
(file-not-executable? fname) -> boolean
Returns one of
#f Access permitted
SEARCH-DENIED Can't stat---a protected directory
is blocking access.
PERMISSION Permission denied.
NO-DIRECTORY Some directory doesn't exist.
NONEXISTENT File doesn't exist.
(file-readable? fname) -> boolean
(file-writable? fname) -> boolean
(file-executable? fname) -> boolean
(file-not-exists? fname [chase?]) -> boolean
#f Exists.
SEARCH-DENIED Some protected directory
is blocking the search.
#t Doesn't exist.
(file-exists? fname [chase?]) -> boolean
(directory-files [dir dotfiles?]) -> string list
(glob pat1 ...) -> string list
(glob-quote string) -> string
(file-match root dot-files? pat1 ...) -> string list
(create-temp-file [prefix]) -> string
(temp-file-iterate maker [template]) -> [object ...]
TEMPLATE defaults to the value of *TEMP-FILE-TEMPLATE*.
(temp-file-channel) -> [inport outport]
** Processes
(exec prog arg1 ...)
(exec-path prog arg1 ...)
(exec/env prog env arg1 ...)
(exec-path/env prog env arg1 ...)
(%exec prog arglist env)
(exec-path-search fname pathlist) -> string
(exit [status])
(%exit [status])
(suspend)
(fork [thunk]) -> proc or #d
(%fork [thunk]) -> proc or #f
(fork/pipe [thunk]) -> proc or #f
(%fork/pipe [thunk]) -> proc or #f
(fork/pipe+ conns [thunk]) proc or #f
(%fork/pipe+ conns [thunk]) proc or #f
(wait proc/pid [flags]) -> status [proc]
(call-terminally thunk)
** Process state
(umask) -> fixnum
(set-umask perms)
(with-umask* perms thunk) -> values of thunk
(with-umask perms . body) -> values of body
(chdir [fname])
(cwd) -> string
(with-cwd* fname thunk) -> value(s) of thunk
(with-cwd fname . body) -> value(s) of body
(pid) -> fixnum
(parent-pid) -> fixnum
(process-group) -> fixnum
(set-process-group [proc/pid] pgrp)
(user-login-name) -> string
(user-uid) -> fixnum
(user-effective-uid) -> fixnum
(user-gid) -> fixnum
(user-effective-gid) -> fixnum
(user-supplementary-gids) -> fixnum list
(set-uid uid)
(set-gid gid)
(process-times) -> [ucpu scpu uchildren schildren]
** User and group db access
(user-info uid-or-name) -> user-info
(define-record user-info
name
uid
gid
home-dir
shell)
(->uid uid/name) -> fixnum
(->username uid/name) -> string
(group-info gid-or-name) -> record
(define-record group-info
name
gid
members) ; List of uids
(->gid gid/name) -> fixnum
(->group gid/name) -> string
** Accessing command-line arguments
command-line-arguments
Does not include program name
(command-line) -> string list
Includes program name in list.
(arg arglist n [default]) -> string
(arg* arglist n [default-thunk]) -> string
(argv n [default]) -> string
ARG is 1-based access to ARGLIST
ARGV is 0-based access to prog + args
** System parameters
(system-name) -> string
** Signal system
(signal-process proc/pid sig)
(signal-procgroup prgrp sig)
(pause-until-interrupt)
(sleep secs)
Non-signal S48 interrupts
-------------------------
interrupt/memory-shortage
Posix signals with S48 interrupts
------------------------------
signal/alrm interrupt/alrm (aka interrupt/alarm)
signal/int interrupt/int (aka interrupt/int)
signal/chld interrupt/chld
signal/cont interrupt/cont
signal/hup interrupt/hup
signal/quit interrupt/quit
signal/term interrupt/term
signal/tstp interrupt/tstp
signal/usr1 interrupt/usr1
signal/usr2 interrupt/usr2
signal/info interrupt/info Non-Posix
signal/io interrupt/io Non-Posix
signal/poll interrupt/poll Non-Posix
signal/prof interrupt/prof Non-Posix
signal/pwr interrupt/pwr Non-Posix
signal/urg interrupt/urg Non-Posix
signal/vtalrm interrupt/vtalrm Non-Posix
signal/winch interrupt/winch Non-Posix
signal/xcpu interrupt/xcpu Non-Posix
signal/xfsz interrupt/xfsz Non-Posix
Synchronous and uncatchable signals
-----------------------------------
signal/stop Uncatchable Posix
signal/kill Uncatchable Posix
signal/abrt Synchronous Posix
signal/fpe Synchronous Posix
signal/ill Synchronous Posix
signal/pipe Synchronous Posix
signal/segv Synchronous Posix
signal/ttin Synchronous Posix
signal/ttou Synchronous Posix
signal/bus Synchronous BSD + SVR4
signal/emt Synchronous BSD + SVR4
signal/iot Synchronous BSD + SVR4
signal/sys Synchronous BSD + SVR4
signal/trap Synchronous BSD + SVR4
** Interrupt handlers
(signal->interrupt sig) -> interrupt
(interrupt-set integer1 ...) -> integer
(enabled-interrupts) -> integer
(set-enabled-interrupts! integer) -> integer
(with-enabled-interrupts interrupt-set body ...) Syntax
(with-enabled-interrupts* interrupt-set thunk)
(set-interrupt-handler! interrupt handler) -> old-handler
(interrupt-handler interrupt) -> handler
HANDLER is #f (ignored), #t (default), or (lambda (enabled-ints) ...) proc.
** Time
(define-record date
seconds minute hour month-day month year
tz-name tz-secs summer?
week-day year-day)
(make-date sec min hour mday month year [tz-name tz-secs summer? wday yday])
(time+ticks)
(ticks/sec)
(date [time tz])
(time [date])
(date->string date)
(format-date fmt date)
** Environment variables
(setenv var val)
(getenv var) -> string
(env->alist) -> string->string alist
(alist->env alist)
(alist-delete key alist) -> alist
(alist-update key val alist) -> alist
(alist-compress alist) -> alist
(with-env* env-alist-delta thunk) -> value(s) of thunk
(with-total-env* env-alist thunk) -> value(s) of thunk
(with-env env-alist-delta . body) -> value(s) of body
(with-total-env env-alist . body) -> value(s) of body
(add-before elt before list) -> list
(add-after elt after list) -> list
** $USER $HOME, and $PATH
home-directory
exec-path-list
* Networking
** High Level Socket Routines
*** clients
(socket-connect protocol-family/internet socket-type name port) -> socket
(socket-connect protocol-family/unix socket-type pathname) -> socket
*** server
(bind-listen-accept-loop protocol-family/internet proc port) -> does-not-return
(bind-listen-accept-loop protocol-family/unix proc pathname) -> does-not-return
proc is a procedure of two arguments: a socket and a socket-address
** Sockets
(create-socket protocol-family type [protocol]) -> socket
(create-socket-pair type) -> [socket1 socket2]
(close-socket socket) -> undefined
protocol-family/unix
protocol-family/internet
socket-type/stream
socket-type/datagram
for protocol see protocol-info
(define-record socket family inport outport)
** Socket Addresses
(define-record socket-address family)
(unix-address->socket-address pathname) -> socket-address
(internet-address->socket-address host-address service-port)-> socket-address
internet-address/any
internet-address/loopback
internet-address/broadcast
(socket-address->unix-address socket-address) -> pathname
(socket-address->internet-address socket-address) ->
[host-address service-port]
** Low Level Socket Routines
(connect-socket socket socket-address) -> undefined
(bind-socket socket socket-address) -> undefined
(listen-socket socket backlog) -> undefined
(accept-connection socket) -> [new-socket socket-address]
(socket-local-address socket) -> socket-address
(socket-remote-address socket) -> socket-address
(shutdown-socket socket how-to) -> undefined
how-to:
shutdown/receives
shutdown/sends
shutdown/sends+receives
** Socket Specific I/O
see read-string/write-string for info on arguments
(receive-message socket length [flags]) ->
[string-or-#f socket-address]
(receive-message! socket string [start] [end] [flags]) ->
[count-or-#f socket-address]
(receive-message/partial socket length [flags]) ->
[string-or-#f socket-address]
(receive-message!/partial socket string [start] [end] [flags]) ->
[count-or-#f socket-address]
(send-message socket string [start] [end] [flags] [socket-address] ->
undefined
(send-message/partial socket string [start] [end] [flags] [socket-address]) ->
count
** Socket Options
(socket-option socket level option) -> value
(set-socket-option socket level option value) -> undefined
boolean:
socket/debug
socket/accept-connect
socket/reuse-address
socket/keep-alive
socket/dont-route
socket/broadcast
socket/use-loop-back
socket/oob-inline
socket/use-privileged
socket/cant-signal
tcp/no-delay
value:
socket/send-buffer
socket/receive-buffer
socket/send-low-water
socket/receive-low-water
socket/error
socket/type
ip/time-to-live
tcp/max-segment
socket/linger is #f or integer seconds
real number with microsecond resolution:
socket/send-timeout
socket/receive-timeout
** Database-information entries
(host-info name-or-socket-address) -> host-info
(network-info name-or-socket-address) -> network-info
(service-info name-or-number [protocol-name]) -> service-info
(protocol-info name-or-number) -> protocol-info
(define-record host-info name aliases addresses)
(define-record network-info name aliases net)
(define-record service-info name aliases port protocol)
(define-record protocol-info name aliases number)
* String manipulation
** Regular expressions
(string-match regexp string [start]) -> match or false
(regexp-match? obj) -> boolean
(match:start match [match-number]) -> fixnum
(match:end match [match-number]) -> fixnum
(match:substring match [match-number]) -> string
(make-regexp str) -> re
(regexp? obj) -> boolean
(regexp-exec regexp str [start]) -> match or false
(regexp-quote str) -> string
** Other string manipulation facilities
(index string char [start]) -> fixnum or false
(rindex string char [start]) -> fixnum or false
(substitute-env-vars fname) -> string
** Manipulating file-names
** Record I/O and field parsing
(read-delimited char-set [port]) -> string or eof
(read-delimited! char-set buf [port start end]) -> nchars or #f or eof
((record-reader [delims elide-delims? handle-delim]) [port]) -> string or eof
HANDLE-DELIM one of {trim, split, concat}
(read-paragraph [port delimiter?])
** Parsing fields
(field-splitter [regexp num-fields]) -> parser
(infix-splitter [delim num-fields handle-delim]) -> parser
(suffix-splitter [delim num-fields handle-delim]) -> parser
(sloppy-suffix-splitter [delim num-fields handle-delim]) -> parser
Where (parser string [start])
HANDLE-DELIM one of {trim, concat, split}
(join-strings strings [delimiter grammar])
GRAMMAR one of {infix, suffix}
** Field readers
(field-reader [field-parser record-reader])
* Awk
(awk <reader-exp> <rec&field-vars> [<rec-counter>] <state-var-inits>
<clause>
.
.
)
* Miscellaneous routines
** Integer bitwise ops
(arithmetic-shift i j) -> integer
(bitwise-and i j) -> integer
(bitwise-ior i j) -> integer
(bitwise-not i) -> integer
(bitwise-xor i j) -> integer
** ASCII encoding
(char->ascii \character) -> integer
(ascii->char \integer) -> character
** Top level
(repl)
* Running scsh
scsh [meta-arg] [switch1 ...] [end-option arg1 ...]
meta-arg: \ <script-file-name>
switch: -e <entry-point> Top-level entry point
-o <structure> Open structure in current package.
-m <structure> Switch to package.
-n <new-package> Switch to new package.
-lm <module> <file-name> Load module into config package.
-l <file-name> Load file into current package.
-dm Do script module.
-ds Do script.
end-option: -s <script> Specifies script to load.
-sfd <num> Script from file descriptor <num>.
-c <expression> Eval <expression> and exit.
--
scshvm [meta-arg] [vm-options] [end-option arg1 ...]
meta-arg: \ <fname>
vm-options: -h heap-size
-s stack-size
-o object-file
end-option: -i image-file
--
(dump-scsh-program main fname)
** File locations
/usr/local/bin/scsh
/usr/local/lib/scsh/
scshvm
scsh
scsh.image
doc/
--- NEW FILE ---
.TH LS48 1
.\" File scsh.man: Manual page template for scsh.
.\" Replace LSCSH with the name of your default image and LLIB with the
.\" directory containing scshvm and default image.
.SH NAME
LSCSH \- a Scheme shell
.SH SYNOPSIS
.B LSCSH
[switch arg1 ... argn]
.SH DESCRIPTION
.B LSCSH
is an implementation of the Scheme shell.
It is implemented as
a heap image which is interpreted by the Scheme 48 virtual machine.
.B LSCSH
is a stub program that starts the virtual machine on the scsh heap image.
.PP
The
.B LSCSH
command loop reads Scheme expressions,
evaluates them, and prints their results.
The Scheme 48 system is an R5RS system with many additional features.
It also executes commands, which are identified by an initial comma character.
Type the command
.I ,help
to receive a list of available commands, or see the documentation for
Scheme 48.
.PP
Scsh's
.I switch
argument can be one of
.LP
.B \-s
.BI script
.LP
.B \-\-
.LP
Either of these switches terminates argument parsing; following arguments
are available from scsh as the string list produced by
.nf
(command-line-arguments)
.fi
The
.B \-s
.BI script
switch causes scsh to run in batch mode,
first loading the script and then exiting.
The default error exception handler terminates the process.
If the
.B \-s
switch is not specified, scsh operates in interactive mode.
It invokes the Scheme 48 top-level read-eval-print loop,
from which the user can enter forms to be evaluated.
In interactive mode, the default error handler invokes an interactive
debugging breakpoint.
The
.B \-\-
switch is used to pass arguments to an interactive scsh.
It simply terminates argument parsing, causing following
arguments to be bound to
.nf
(command-line-arguments)
.SH FILES
.TP
.B LLIB/doc/
The detailed documentation for scsh. Contains much more information
than this broken manpage.
.TP
.B LLIB/scshvm
the virtual machine.
.TP
.B LLIB/LSCSH.image
the default image.
.SH BUGS
Too big; starts up too slowly.
|