by Robert MacLachlan, Skef Wholey, Bill
Chiles and William Lott
CMUCL attempts to make the full power of the underlying environment
available to the Lisp programmer. This is done using combination of
hand-coded interfaces and foreign function calls to C libraries.
Although the techniques differ, the style of interface is similar.
This chapter provides an overview of the facilities available and
general rules for using them, as well as describing specific
features in detail. It is assumed that the reader has a working
familiarity with Unix and X11, as well as access to the standard
6.1 Reading the Command Line
The shell parses the command line with which Lisp is invoked, and
passes a data structure containing the parsed information to Lisp.
This information is then extracted from that data structure and put
into a set of Lisp data structures.
The following functions may be used to examine command-line-switch structures.
The value of *command-line-words* is a list
of strings that make up the command line, one word per string. The
first word on the command line, i.e. the name of the program
invoked (usually lisp) is stored in
*command-line-utility-name*. The value of
*command-line-switches* is a list of
command-line-switch structures, with a
structure for each word on the command line starting with a hyphen.
All the command line words between the program name and the first
switch are stored in *command-line-words*.
Returns the name of the switch, less the preceding hyphen and
trailing equal sign (if any).
Returns the value designated using an embedded equal sign, if any.
If the switch has no equal sign, then this is null.
Returns a list of the words between this switch and the next switch
or the end of the command line.
Returns the first non-null value from cmd-switch-value, the first element in cmd-switch-words, or the first word in command-line-words.
This function takes the name of a switch as a string and returns
the value of the switch given on the command line. If no value was
specified, then any following words are returned. If there are no
following words, then t is returned. If the
switch was not specified, then nil is
This macro causes function to be called
when the switch name appears in the
command line. Name is a simple-string that does not begin with a
hyphen (unless the switch name really does begin with one.)
If function is not supplied, then the
switch is parsed into command-line-switches, but otherwise ignored. This
suppresses the undefined switch warning which would otherwise take
place. The warning can also be globally suppressed by complain-about-illegal-switches.
6.2 Useful Variables
Streams connected to the standard input, output and error file
A stream connected to /dev/tty.
The environment variables inherited by
the current process, as a keyword-indexed alist. For example, to
access the DISPLAY environment variable, you could use
Note that the case of the variable name is preserved when
converting to a keyword. Therefore, you need to specify the keyword
properly for variable names containing lower-case
(cdr (assoc :display ext:*environment-list*))
6.3 Lisp Equivalents for C Routines
The UNIX documentation describes the system interface in terms of C
procedure headers. The corresponding Lisp function will have a
somewhat different interface, since Lisp argument passing
conventions and datatypes are different.
The main difference in the argument passing conventions is that
Lisp does not support passing values by reference. In Lisp, all
argument and results are passed by value. Interface functions take
some fixed number of arguments and return some fixed number of
values. A given “parameter” in the C specification will
appear as an argument, return value, or both, depending on whether
it is an In parameter, Out parameter, or In/Out parameter. The
basic transformation one makes to come up with the Lisp equivalent
of a C routine is to remove the Out parameters from the call, and
treat them as extra return values. In/Out parameters appear both as
arguments and return values. Since Out and In/Out parameters are
only conventions in C, you must determine the usage from the
Thus, the C routine declared as
has as its Lisp equivalent something like
kern_return_t lookup(servport, portsname, portsid)
int *portsid; /* out */
*portsid = <expression to compute portsid field>
If there are multiple out or in-out arguments, then there are
multiple additional returns values.
(defun lookup (ServPort PortsName)
<expression to compute portsid field>))
Fortunately, CMUCL programmers rarely have to worry about the
nuances of this translation process, since the names of the
arguments and return values are documented in a way so that the
describe function (and the Hemlock Describe Function Call command, invoked with
C-M-Shift-A) will list this information. Since the names of
arguments and return values are usually descriptive, the
information that describe prints is usually
all one needs to write a call. Most programmers use this on-line
documentation nearly all of the time, and thereby avoid the need to
handle bulky manuals and perform the translation from barbarous
6.4 Type Translations
Lisp data types have very different
representations from those used by conventional languages such as
C. Since the system interfaces are designed for conventional
languages, Lisp must translate objects to and from the Lisp
representations. Many simple objects have a direct translation:
integers, characters, strings and floating point numbers are
translated to the corresponding Lisp object. A number of types,
however, are implemented differently in Lisp for reasons of clarity
Instances of enumerated types are expressed as keywords in Lisp.
Records, arrays, and pointer types are implemented with the Alien
facility (see section 8).
Access functions are defined for these types which convert fields
of records, elements of arrays, or data referenced by pointers into
Lisp objects (possibly another object to be referenced with another
One should dispose of Alien objects created by constructor
functions or returned from remote procedure calls when they are no
longer of any use, freeing the virtual memory associated with that
object. Since Aliens contain pointers to non-Lisp data, the garbage
collector cannot do this itself. If the memory was obtained from
make-alien or from a
foreign function call to a routine that used malloc, then free-alien should be used.
6.5 System Area Pointers
Note that in some cases an address is
represented by a Lisp integer, and in other cases it is represented
by a real pointer. Pointers are usually used when an object in the
current address space is being referred to. The MACH virtual memory
manipulation calls must use integers, since in principle the
address could be in any process, and Lisp cannot abide random
pointers. Because these types are represented differently in Lisp,
one must explicitly coerce between these representations.
System Area Pointers (SAPs) provide a mechanism that bypasses the
Alien type system and accesses virtual memory directly. A SAP is a
raw byte pointer into the lisp process
address space. SAPs are represented with a pointer descriptor, so
SAP creation can cause consing. However, the compiler uses a
non-descriptor representation for SAPs when possible, so the
consing overhead is generally minimal. See section 5.11.2.
The function sap-int is used to generate an
integer corresponding to the system area pointer, suitable for
passing to the kernel interfaces (which want all addresses
specified as integers). The function int-sap
is used to do the opposite conversion. The integer representation
of a SAP is the byte offset of the SAP from the start of the
system:sap+ sap offset
This function adds a byte offset to
sap, returning a new SAP.
These functions return the 8, 16 or 32 bit unsigned integer at
offset from sap. The offset is always
a byte offset, regardless of the number of bits accessed.
setf may be used with the these functions to
deposit values into virtual memory.
system:signed-sap-ref-16 sap offset
system:signed-sap-ref-32 sap offset
These functions are the same as the above unsigned operations,
except that they sign-extend, returning a negative number if the
high bit is set.
6.6 Unix System Calls
You probably won't have much cause to use them, but all the Unix
system calls are available. The Unix system call functions are in
the Unix package. The name of the interface
for a particular system call is the name of the system call
prepended with unix-. The system usually
defines the associated constants without any prefix name. To find
out how to use a particular system call, try using describe on it. If that is unhelpful, look at the
source in unix.lisp or consult your
The Unix system calls indicate an error by returning nil as the first value and the Unix error number as the
second value. If the call succeeds, then the first value will
always be non-nil, often t.
For example, to use the chdir syscall:
(multiple-value-bind (success errno)
(error "Can't change working directory: ~a"
This function returns a string describing the Unix error number
error (this is similar to the Unix
6.7 File Descriptor Streams
Many of the UNIX system calls
return file descriptors. Instead of using other UNIX system calls
to perform I/O on them, you can create a stream around them. For
this purpose, fd-streams exist. See also read-n-bytes.
system:make-fd-stream descriptor &key
This function creates a file descriptor stream using descriptor. If :input is
non-nil, input operations are allowed. If
:output is non-nil,
output operations are allowed. The default is input only. These
keywords are defined:
- is the type of the unit of transaction for the
stream, which defaults to string-char. See
the Common Lisp description of open for valid
- is the kind of output buffering desired for the
stream. Legal values are :none for no
buffering, :line for buffering up to each
newline, and :full for full buffering.
- is a simple-string name to use for descriptive
purposes when the system prints an fd-stream. When printing
fd-streams, the system prepends the streams name with Stream for . If name is
unspecified, it defaults to a string containing file or descriptor, in
order of preference.
- :file, :original
- file specifies the
defaulted namestring of the associated file when creating a file
stream (must be a simple-string). original is the simple-string
name of a backup file containing the original contents of
file while writing file.
When you abort the stream by passing t to
close as the second argument, if you supplied
both file and original, close will rename
the original name to the file name. When you close the
stream normally, if you supplied original, and delete-original is non-nil,
close deletes original. If auto-close
is true (the default), then descriptor
will be closed when the stream is garbage collected.
- : The original pathname passed to open and
returned by pathname; not defaulted or
- if non-null, then timeout is an integer number of seconds after which
an input wait should time out. If a read does time out, then the
system:io-timeout condition is
This function returns t if object is an fd-stream, and nil if not. Obsolete: use the portable (typep x 'file-stream).
This returns the file descriptor associated with stream.
6.8 Unix Signals
access to all the Unix signals that can be generated under Unix. It
should be noted that if this capability is abused, it is possible
to completely destroy the running Lisp. The following macros and
functions allow access to the Unix interrupt system. The signal
names as specified in section 2 of the Unix Programmer's
Manual are exported from the Unix package.
6.8.1 Changing Signal Handlers
system:with-enabled-interrupts specs &rest body
This macro should be called with a list of signal specifications,
specs. Each element of specs should be a list of two elements: the first
should be the Unix signal for which a handler should be
established, the second should be a function to be called when the
signal is received One or more signal handlers can be established
in this way. with-enabled-interrupts
establishes the correct signal handlers and then executes the forms
in body. The forms are executed in an
unwind-protect so that the state of the signal handlers will be
restored to what it was before the with-enabled-interrupts was entered. A signal handler
function specified as NIL will set the Unix signal handler to the
default which is normally either to ignore the signal or to cause a
core dump depending on the particular signal.
system:without-interrupts &rest body
It is sometimes necessary to execute a piece a code that can not be
interrupted. This macro the forms in body
with interrupts disabled. Note that the Unix interrupts are not
actually disabled, rather they are queued until after body has finished executing.
system:with-interrupts &rest body
When executing an interrupt handler, the system disables
interrupts, as if the handler was wrapped in in a without-interrupts. The macro with-interrupts can be used to enable interrupts while
the forms in body are evaluated. This is
useful if body is going to enter a break
loop or do some long computation that might need to be
system:without-hemlock &rest body
For some interrupts, such as SIGTSTP (suspend the Lisp process and
return to the Unix shell) it is necessary to leave Hemlock and then
return to it. This macro executes the forms in body after exiting Hemlock. When body has been executed, control is returned to
system:enable-interrupt signal function
This function establishes function as the
handler for signal. Unless you want to
establish a global signal handler, you should use the macro
with-enabled-interrupts to temporarily
establish a signal handler. enable-interrupt
returns the old function associated with the signal.
Ignore-interrupt sets the Unix signal mechanism to ignore
signal which means that the Lisp process
will never see the signal. Ignore-interrupt returns the old
function associated with the signal or nil if
none is currently defined.
Default-interrupt can be used to tell the Unix signal mechanism to
perform the default action for signal.
For details on what the default action for a signal is, see section
2 of the Unix Programmer's Manual. In general, it is
likely to ignore the signal or to cause a core dump.
6.8.2 Examples of Signal Handlers
The following code is the signal handler used by the Lisp system
for the SIGINT signal.
The without-hemlock form is used to make sure
that Hemlock is exited before a break loop is entered. The
with-interrupts form is used to enable
interrupts because the user may want to generate an interrupt while
in the break loop. Finally, break is called to enter a break loop,
so the user can look at the current state of the computation. If
the user proceeds from the break loop, the computation will be
restarted from where it was interrupted.
(defun ih-sigint (signal code scp)
(declare (ignore signal code scp))
(break "Software Interrupt" t))))
The following function is the Lisp signal handler for the SIGTSTP
signal which suspends a process and returns to the Unix shell.
Lisp uses this interrupt handler to catch the SIGTSTP signal
because it is necessary to get out of Hemlock in a clean way before
returning to the shell.
(defun ih-sigtstp (signal code scp)
(declare (ignore signal code scp))
(Unix:unix-kill (Unix:unix-getpid) Unix:sigstop)))
To set up these interrupt handlers, the following is recommended:
(with-enabled-interrupts ((Unix:SIGINT #'ih-sigint)
<user code to execute with the above signal handlers enabled.>