scsh-0.6/doc/cheat.txt

741 lines
19 KiB
Plaintext

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/