Previous Up Next

Chapter 6  UNIX Interface

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 system documentation.

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.


[Variable]
extensions:*command-line-strings*    

[Variable]
extensions:*command-line-utility-name*    

[Variable]
extensions:*command-line-words*    

[Variable]
extensions:*command-line-switches*    

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*

.

The following functions may be used to examine

command-line-switch

structures.


[Function]
extensions:cmd-switch-name switch    

Returns the name of the switch, less the preceding hyphen and trailing equal sign (if any).


[Function]
extensions:cmd-switch-value switch    

Returns the value designated using an embedded equal sign, if any. If the switch has no equal sign, then this is null.


[Function]
extensions:cmd-switch-words switch    

Returns a list of the words between this switch and the next switch or the end of the command line.


[Function]
extensions:cmd-switch-arg switch    

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

.


[Function]
extensions:get-command-line-switch sname    

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 returned.


[Macro]
extensions:defswitch name &optional function    

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


[Variable]
system:*stdin*    

[Variable]
system:*stdout*    

[Variable]
system:*stderr*    

Streams connected to the standard input, output and error file descriptors.


[Variable]
system:*tty*    

A stream connected to

/dev/tty

.


[Variable]
extensions:*environment-list*    
The environment variables inherited by the current process, as a keyword-indexed alist. For example, to access the DISPLAY environment variable, you could use
   (cdr (assoc :display ext:*environment-list*))

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 letters,

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 documentation.

Thus, the C routine declared as

kern_return_t lookup(servport, portsname, portsid)
        port        servport;
        char        *portsname;
        int        *portsid;        /* out */
 
  ...
  *portsid = <expression to compute portsid field>
  return(KERN_SUCCESS);
 

has as its Lisp equivalent something like

(defun lookup (ServPort PortsName)
  ...
  (values
   success
   <expression to compute portsid field>))

If there are multiple out or in-out arguments, then there are multiple additional returns values.

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 tongues.

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 and efficiency.

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 access function).

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.


[Function]
system:sap-int sap    

[Function]
system:int-sap int    

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 address space.


[Function]
system:sap+ sap offset    

This function adds a byte

offset

to

sap

, returning a new SAP.


[Function]
system:sap-ref-8 sap offset    

[Function]
system:sap-ref-16 sap offset    

[Function]
system:sap-ref-32 sap offset    

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.


[Function]
system:signed-sap-ref-8 sap offset    

[Function]
system:signed-sap-ref-16 sap offset    

[Function]
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 system maintainer.

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)
    (unix:unix-chdir "/tmp")
  (unless success
     (error "Can't change working directory: ~a"
            (unix:get-unix-error-msg errno))))


[Function]
Unix:get-unix-error-msg error    

This function returns a string describing the Unix error number

error

(this is similar to the Unix function

perror

).

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

.


[Function]
system:make-fd-stream descriptor &key <TT class=code>:input</TT> <TT class=code>:output</TT> <TT class=code>:element-type</TT>
:buffering :name :file :original
:delete-original :auto-close
:timeout :pathname    

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:

:element-type
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 values.
:buffering
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.
:name
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.

:pathname
: The original pathname passed to open and returned by pathname; not defaulted or translated.
:timeout
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 signalled.


[Function]
system:fd-stream-p object    

This function returns

t

if

object

is an fd-stream, and

nil

if not. Obsolete: use the portable

(typep x 'file-stream)

.


[Function]
system:fd-stream-fd stream    

This returns the file descriptor associated with

stream

.

6.8  Unix Signals

CMUCL allows 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


[Macro]
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.


[Macro]
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.


[Macro]
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 interrupted.


[Macro]
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 Hemlock.


[Function]
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.


[Function]
system:ignore-interrupt 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.


[Function]
system:default-interrupt signal    

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.

(defun ih-sigint (signal code scp)
  (declare (ignore signal code scp))
  (without-hemlock
   (with-interrupts
    (break "Software Interrupt" t))))

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.

The following function is the Lisp signal handler for the SIGTSTP signal which suspends a process and returns to the Unix shell.

(defun ih-sigtstp (signal code scp)
  (declare (ignore signal code scp))
  (without-hemlock
   (Unix:unix-kill (Unix:unix-getpid) Unix:sigstop)))

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.

To set up these interrupt handlers, the following is recommended:

(with-enabled-interrupts ((Unix:SIGINT #'ih-sigint)
                          (Unix:SIGTSTP #'ih-sigtstp))
  <user code to execute with the above signal handlers enabled.>
)

Previous Up Next