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, CMU Common Lisp 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.