4.1cBSD/usr/src/ucb/lisp/lisplib/manual/ch6.r
CHAPTER 6
System Functions
This chapter describes the functions used to interact with
internal components of the Lisp system and operating system.
(allocate 's_type 'x_pages)
WHERE: s_type is one of the FRANZ LISP data types
described in 1.3.
RETURNS: x_pages.
SIDE EFFECT: FRANZ LISP attempts to allocate x_pages of
type s_type. If there aren't x_pages of
memory left, no space will be allocated
and an error will occur. The storage that
is allocated is not given to the caller,
instead it is added to the free storage
list of s_type. The functions _s_e_g_m_e_n_t and
_s_m_a_l_l-_s_e_g_m_e_n_t allocate blocks of storage
and return it to the caller.
(argv 'x_argnumb)
RETURNS: a symbol whose pname is the x_argnumb_t_h argu-
ment (starting at 0) on the command line which
invoked the current lisp.
NOTE: if x_argnumb is less than zero, a fixnum whose
value is the number of arguments on the command
line is returned. (_a_r_g_v _0) returns the name of
the lisp you are running.
(baktrace)
RETURNS: nil
SIDE EFFECT: the lisp runtime stack is examined and the
name of (most) of the functions currently
in execution are printed, most active
first.
NOTE: this will occasionally miss the names of compiled
lisp functions due to incomplete information on
the stack. If you are tracing compiled code,
then _b_a_k_t_r_a_c_e won't be able to interpret the
stack unless (_s_s_t_a_t_u_s _t_r_a_n_s_l_i_n_k _n_i_l) was done.
See the function _s_h_o_w_s_t_a_c_k for another way of
System Functions 6-1
System Functions 6-2
printing the lisp runtime stack.
(boundp 's_name)
RETURNS: nil if s_name is unbound, that is it has
never be given a value. If x_name has the
value g_val, then (nil . g_val) is returned.
(chdir 's_path)
RETURNS: t iff the system call succeeds.
SIDE EFFECT: the current directory set to s_path. Among
other things, this will affect the default
location where the input/output functions
look for and create files.
NOTE: _c_h_d_i_r follows the standard UNIX conventions, if
s_path does not begin with a slash, the default
path is changed to the current path with s_path
appended.
(dumplisp s_name)
RETURNS: nil
SIDE EFFECT: the current lisp is dumped to the disk
with the file name s_name. When s_name is
executed, you will be in a lisp in the
same state as when the dumplisp was done.
NOTE: dumplisp will fail if one tries to write over
the current running file. UNIX does not allow you
to modify the file you are running.
(eval-when l_time g_exp1 ...)
SIDE EFFECT: l_time may contain any combination of the
symbols _l_o_a_d, _e_v_a_l, and _c_o_m_p_i_l_e. The
effects of load and compile is discussed
in the section on the compiler. If eval
is present however, this simply means that
the expressions g_exp1 and so on are
evaluated from left to right. If eval is
not present, the forms are not evaluated.
9
9 Printed: October 7, 1982
System Functions 6-3
(exit ['x_code])
RETURNS: nothing (it never returns).
SIDE EFFECT: the lisp system dies with exit code x_code
or 0 if x_code is not specified.
(fake 'x_addr)
RETURNS: the lisp object at address x_addr.
NOTE: This is intended to be used by people debugging
the lisp system.
(fork)
RETURNS: nil to the child process and the process
number of the child to the parent.
SIDE EFFECT: A copy of the current lisp system is made
in memory and both lisp systems now begin
to run. This function can be used
interactively to temporarily save the
state of Lisp (as shown below), but you
must be careful that only one of the
lisp's interacts with the terminal after
the fork. The _w_a_i_t function is useful for
this.
____________________________________________________
-> (_s_e_t_q _f_o_o '_b_a_r) ;; set a variable
bar
-> (_c_o_n_d ((_f_o_r_k)(_w_a_i_t))) ;; duplicate the lisp system and
nil ;; make the parent wait
-> _f_o_o ;; check the value of the variable
bar
-> (_s_e_t_q _f_o_o '_b_a_z) ;; give it a new value
baz
-> _f_o_o ;; make sure it worked
baz
-> (_e_x_i_t) ;; exit the child
(5274 . 0) ;; the _w_a_i_t function returns this
-> _f_o_o ;; we check to make sure parent was
bar ;; not modified.
____________________________________________________
9
9 Printed: October 7, 1982
System Functions 6-4
(gc)
RETURNS: nil
SIDE EFFECT: this causes a garbage collection.
NOTE: The function _g_c_a_f_t_e_r is not called automatically
after this function finishes. Normally the user
doesn't have to call _g_c since garbage collection
occurs automatically whenever internal free lists
are exhausted.
(gcafter s_type)
WHERE: s_type is one of the FRANZ LISP data types
listed in 1.3.
NOTE: this function is called by the garbage collector
after a garbage collection which was caused by
running out of data type s_type. This function
should determine if more space need be allocated
and if so should allocate it. There is a default
gcafter function but users who want control over
space allocation can define their own -- but note
that it must be an nlambda.
(getenv 's_name)
RETURNS: a symbol whose pname is the value of s_name in
the current UNIX environment. If s_name
doesn't exist in the current environment, a
symbol with a null pname is returned.
(hashtabstat)
RETURNS: a list of fixnums representing the number of
symbols in each bucket of the oblist.
NOTE: the oblist is stored a hash table of buckets.
Ideally there would be the same number of symbols
in each bucket.
9
9 Printed: October 7, 1982
System Functions 6-5
(help [sx_arg])
SIDE EFFECT: If sx_arg is a symbol then the portion of
this manual beginning with the description
of sx_arg is printed on the terminal. If
sx_arg is a fixnum or the name of one of
the appendicies, that chapter or appendix
is printed on the terminal. If no argu-
ment is provided, _h_e_l_p prints the options
that it recognizes. The program `more' is
used to print the manual on the terminal;
it will stop after each page and will con-
tinue after the space key is pressed.
(include s_filename)
RETURNS: nil
SIDE EFFECT: The given filename is _l_o_a_ded into the
lisp.
NOTE: this is similar to load except the argument is
not evaluated. Include means something special
to the compiler.
(includef 's_filename)
RETURNS: nil
SIDE EFFECT: this is the same as _i_n_c_l_u_d_e except the
argument is evaluated.
(maknum 'g_arg)
RETURNS: the address of its argument converted into a
fixnum.
(monitor ['xs_maxaddr])
RETURNS: t
SIDE EFFECT: If xs_maxaddr is t then profiling of the
entire lisp system is begun. If
xs_maxaddr is a fixnum then profiling is
done only up to address xs_maxaddr. If
xs_maxaddr is not given, then profiling is
stopped and the data obtained is written
to the file 'mon.out' where it can be
analyzed with the UNIX 'prof' program.
NOTE: this function only works if the lisp system has
been compiled in a special way.
9
9 Printed: October 7, 1982
System Functions 6-6
(opval 's_arg ['g_newval])
RETURNS: the value associated with s_arg before the
call.
SIDE EFFECT: If g_newval is specified, the value asso-
ciated with s_arg is changed to g_newval.
NOTE: _o_p_v_a_l keeps track of storage allocation. If s_arg
is one of the data types then _o_p_v_a_l will return a
list of three fixnums representing the number of
items of that type in use, the number of pages
allocated and the number of items of that type
per page. You should never try to change the
value _o_p_v_a_l associates with a data type using
_o_p_v_a_l.
If s_arg is _p_a_g_e_l_i_m_i_t then _o_p_v_a_l will return (and
set if g_newval is given) the maximum amount of
lisp data pages it will allocate. This limit
should remain small unless you know your program
requires lots of space as this limit will catch
programs in infinite loops which gobble up
memory.
(*process 'st_command ['g_readp ['g_writep]])
RETURNS: either a fixnum if one argument is given, or a
list of two ports and a fixnum if two or three
arguments are given.
NOTE: *_p_r_o_c_e_s_s starts another process by passing
st_command to the shell (it first tries csh, then
it tries sh if csh doesn't exist). If only one
argument is given to *_p_r_o_c_e_s_s, *_p_r_o_c_e_s_s_P _w_a_i_t_s
_f_o_r _t_h_e _n_e_w _p_r_o_c_e_s_s _t_o _d_i_e _a_n_d _t_h_e_n _r_e_t_u_r_n_s _t_h_e
_e_x_i_t _c_o_d_e _o_f _t_h_e _n_e_w _p_r_o_c_e_s_s. _I_f _m_o_r_e _t_w_o _o_r
_t_h_r_e_e _a_r_g_u_m_e_n_t_s _a_r_e _g_i_v_e_n, *_p_r_o_c_e_s_s _s_t_a_r_t_s _t_h_e
_p_r_o_c_e_s_s _a_n_d _t_h_e_n _r_e_t_u_r_n_s _a _l_i_s_t _w_h_i_c_h, _d_e_p_e_n_d_i_n_g
_o_n _t_h_e _v_a_l_u_e _o_f _g__r_e_a_d_p _a_n_d _g__w_r_i_t_e_p, _m_a_y _c_o_n_t_a_i_n
_i/_o _p_o_r_t_s _f_o_r _c_o_m_m_u_n_c_a_t_i_n_g _w_i_t_h _t_h_e _n_e_w _p_r_o_c_e_s_s.
_I_f _g__w_r_i_t_e_p _i_s _n_o_n _n_i_l, _t_h_e_n _a _p_o_r_t _w_i_l_l _b_e
_c_r_e_a_t_e_d _w_h_i_c_h _t_h_e _l_i_s_p _p_r_o_g_r_a_m _c_a_n _u_s_e _t_o _s_e_n_d
_c_h_a_r_a_c_t_e_r_s _t_o _t_h_e _n_e_w _p_r_o_c_e_s_s. _I_f _g__r_e_a_d_p _i_s _n_o_n
_n_i_l, _t_h_e_n _a _p_o_r_t _w_i_l_l _b_e _c_r_e_a_t_e_d _w_h_i_c_h _t_h_e _l_i_s_p
_p_r_o_g_r_a_m _c_a_n _u_s_e _t_o _r_e_a_d _c_h_a_r_a_c_t_e_r_s _f_r_o_m _t_h_e _n_e_w
_p_r_o_c_e_s_s. _T_h_e _v_a_l_u_e _r_e_t_u_r_n_e_d _b_y *_p_r_o_c_e_s_s _i_s
(_r_e_a_d_p_o_r_t _w_r_i_t_e_p_o_r_t _p_i_d) _w_h_e_r_e _r_e_a_d_p_o_r_t _a_n_d _w_r_i_-
_t_e_p_o_r_t _a_r_e _e_i_t_h_e_r _n_i_l _o_r _a _p_o_r_t _b_a_s_e_d _o_n _t_h_e
_v_a_l_u_e _o_f _g__r_e_a_d_p _a_n_d _g__w_r_i_t_e_p. _p_i_d _i_s _t_h_e _p_r_o_-
_c_e_s_s _i_d _o_f _t_h_e _n_e_w _p_r_o_c_e_s_s. _S_i_n_c_e _i_t _i_s _h_a_r_d _t_o
_r_e_m_e_m_b_e_r _t_h_e _o_r_d_e_r _o_f _g__r_e_a_d_p _a_n_d _g__w_r_i_t_e_p, _t_h_e
_f_u_n_c_t_i_o_n_s *_p_r_o_c_e_s_s-_s_e_n_d _a_n_d *_p_r_o_c_e_s_s-_r_e_c_e_i_v_e _w_e_r_e
_w_r_i_t_t_e_n _t_o _p_e_r_f_o_r_m _t_h_e _c_o_m_m_o_n _f_u_n_c_t_i_o_n_s.
Printed: October 7, 1982
System Functions 6-7
(*process-receive '_s_t__c_o_m_m_a_n_d)
RETURNS: a port which can be read.
SIDE EFFECT: The command st_command is given to the
shell and it is started runing in the
background. The output of that command is
available for reading via the port
returned. The input of the command pro-
cess is set to /dev/null.
(*process-send 'st_command)
RETURNS: a port which can be written to.
SIDE EFFECT: The command st_command is given to the
shell and it is started runing in the
background. The lisp program can provide
input for that command by sending charac-
ters to the port returned by this func-
tion. The output of the command process
is set to /dev/null.
(process s_pgrm [s_frompipe s_topipe])
RETURNS: if the optional arguments are not present a
fixnum which is the exit code when s_prgm
dies. If the optional arguments are present,
it returns a fixnum which is the process id of
the child.
NOTE: This command is obsolete. New programs should
use one of the *_p_r_o_c_e_s_s commands given above.
SIDE EFFECT: If s_frompipe and s_topipe are given, they
are bound to ports which are pipes which
direct characters from FRANZ LISP to the
new process and to FRANZ LISP from the new
process respectively. _P_r_o_c_e_s_s forks a
process named s_prgm and waits for it to
die iff there are no pipe arguments given.
9
9 Printed: October 7, 1982
System Functions 6-8
(ptime)
RETURNS: a list of two elements, the first is the
amount of processor time used by the lisp sys-
tem so far, the second is the amount of time
used by the garbage collector so far.
NOTE: the time is measured in 60_t_hs of a second. The
first number includes the second number. The
amount of time used by garbage collection is not
recorded until the first call to ptime. This is
done to prevent overhead when the user is not
interested in garbage collection times.
(reset)
SIDE EFFECT: the lisp runtime stack is cleared and the
system restarts at the top level by exe-
cuting a (_f_u_n_c_a_l_l _t_o_p-_l_e_v_e_l _n_i_l).
(restorelisp 's_name)
SIDE EFFECT: this reads in file s_name (which was
created by _s_a_v_e_l_i_s_p) and then does a
(_r_e_s_e_t).
NOTE: This is only used on VMS systems since _d_u_m_p_l_i_s_p
cannot be used.
(retbrk ['x_level])
WHERE: x_level is a small integer of either sign.
SIDE EFFECT: The default error handler keeps a notion
of the current level of the error caught.
If x_level is negative, control is thrown
to this default error handler whose level
is that many less than the present, or to
_t_o_p-_l_e_v_e_l if there aren't enough. If
x_level is non-negative, control is passed
to the handler at that level. If x_level
is not present, the value -1 is taken by
default.
9
9 Printed: October 7, 1982
System Functions 6-9
(*rset 'g_flag)
RETURNS: g_flag
SIDE EFFECT: If g_flag is non nil then the lisp system
will maintain extra information about
calls to _e_v_a_l and _f_u_n_c_a_l_l. This record
keeping slows down the evaluation but this
is required for the functions _e_v_a_l_h_o_o_k,
_f_u_n_c_a_l_l_h_o_o_k, and _e_v_a_l_f_r_a_m_e to work. To
debug compiled lisp code the transfer
tables should be unlinked:
(_s_s_t_a_t_u_s _t_r_a_n_s_l_i_n_k _n_i_l)
(savelisp 's_name)
RETURNS: t
SIDE EFFECT: the state of the Lisp system is saved in
the file s_name. It can be read in by
_r_e_s_t_o_r_e_l_i_s_p.
NOTE: This is only used on VMS systems since _d_u_m_p_l_i_s_p
cannot be used.
(segment 's_type 'x_size)
WHERE: s_type is one of the data types given in 1.3
RETURNS: a segment of contiguous lispvals of type
s_type.
NOTE: In reality, _s_e_g_m_e_n_t returns a new data cell of
type s_type and allocates space for x_size - 1
more s_type's beyond the one returned. _S_e_g_m_e_n_t
always allocates new space and does so in 512
byte chunks. If you ask for 2 fixnums, segment
will actually allocate 128 of them thus wasting
126 fixnums. The function _s_m_a_l_l-_s_e_g_m_e_n_t is a
smarter space allocator and should be used when-
ever possible.
9
9 Printed: October 7, 1982
System Functions 6-10
(shell)
RETURNS: the exit code of the shell when it dies.
SIDE EFFECT: this forks a new shell and returns when
the shell dies.
(showstack)
RETURNS: nil
SIDE EFFECT: all forms currently in evaluation are
printed, beginning with the most recent.
For compiled code the most that showstack
will show is the function name and it may
miss some functions.
(signal 'x_signum 's_name)
RETURNS: nil if no previous call to signal has been
made, or the previously installed s_name.
SIDE EFFECT: this declares that the function named
s_name will handle the signal number
x_signum. If s_name is nil, the signal is
ignored. Presently only four UNIX signals
are caught, they and their numbers are:
Interrupt(2), Floating exception(8),
Alarm(14), and Hang-up(1).
(sizeof 'g_arg)
RETURNS: the number of bytes required to store one
object of type g_arg, encoded as a fixnum.
(small-segment 's_type 'x_cells)
WHERE: s_type is one of fixnum, flonum and value.
RETURNS: a segment of x_cells data objects of type
s_type.
SIDE EFFECT: This may call _s_e_g_m_e_n_t to allocate new
space or it may be able to fill the
request on a page already allocated. The
value returned by _s_m_a_l_l-_s_e_g_m_e_n_t is usually
stored in the data subpart of an array
object.
9
9 Printed: October 7, 1982
System Functions 6-11
(sstatus g_type g_val)
RETURNS: g_val
SIDE EFFECT: If g_type is not one of the special
sstatus codes described in the next few
pages this simply sets g_val as the value
of status type g_type in the system status
property list.
(sstatus appendmap g_val)
RETURNS: g_val
SIDE EFFECT: If g_val is non nil then when _f_a_s_l is told
to create a load map, it will append to
the file name given in the _f_a_s_l command,
rather than creating a new map file. The
initial value is nil.
(sstatus automatic-reset g_val)
RETURNS: g_val
SIDE EFFECT: If g_val is non nil then when an error
occurs which no one wants to handle, a
_r_e_s_e_t will be done instead of entering a
primitive internal break loop. The ini-
tial value is t.
(sstatus chainatom g_val)
RETURNS: g_val
SIDE EFFECT: If g_val is non nil and a _c_a_r or _c_d_r of a
symbol is done, then nil will be returned
instead of an error being signaled. This
only affects the interpreter, not the com-
piler. The initial value is nil.
(sstatus dumpcore g_val)
RETURNS: g_val
SIDE EFFECT: If g_val is nil, FRANZ LISP tells UNIX
that a segmentation violation or bus error
should cause a core dump. If g_val is non
nil then FRANZ LISP will catch those
errors and print a message advising the
user to reset.
NOTE: The initial value for this flag is nil, and only
those knowledgeable of the innards of the lisp
Printed: October 7, 1982
System Functions 6-12
system should ever set this flag non nil.
(sstatus dumpmode x_val)
RETURNS: x_val
SIDE EFFECT: All subsequent _d_u_m_p_l_i_s_p's will be done in
mode x_val. x_val may be either 413 or
410 (decimal).
NOTE: the advantage of mode 413 is that the dumped Lisp
can be demand paged in when first started, which
will make it start faster and disrupt other users
less. The initial value is 413.
(sstatus evalhook g_val)
RETURNS: g_val
SIDE EFFECT: When g_val is non nil, this enables the
evalhook and and funcallhook traps in the
evaluator. See 14.4 for more details.
(sstatus feature g_val)
RETURNS: g_val
SIDE EFFECT: g_val is added to the (_s_t_a_t_u_s _f_e_a_t_u_r_e_s)
list,
(sstatus gcstrings g_val)
RETURNS: g_val
SIDE EFFECT: if g_val is non nil and if string garbage
collection was enabled when the lisp sys-
tem was created, string space will be gar-
bage collected.
NOTE: the default value for this is nil since in most
applications garbage collecting strings is a
waste of time.
9
9 Printed: October 7, 1982
System Functions 6-13
(sstatus ignoreeof g_val)
RETURNS: g_val
SIDE EFFECT: If g_val is non nil then if a end of file
(CNTL D on UNIX) is typed to the top level
interpreter it will be ignored rather then
cause the lisp system to exit. If the the
standard input is a file or pipe then
this has no effect, a EOF will always
cause lisp to exit. The initial value is
nil.
(sstatus nofeature g_val)
RETURNS: g_val
SIDE EFFECT: g_val is removed from the status features
list if it was present.
(sstatus translink g_val)
RETURNS: g_val
SIDE EFFECT: If g_val is nil then all transfer tables
are cleared and further calls through the
transfer table will not cause the fast
links to be set up. If g_val is the sym-
bol _o_n then all possible transfer table
entries will be linked and the flag will
be set to cause fast links to be set up
dynamically. Otherwise all that is done
is to set the flag to cause fast links to
be set up dynamically. The initial value
is nil.
NOTE: For a discussion of transfer tables, see the Sec-
tion on the compiler.
(sstatus uctolc g_val)
RETURNS: g_val
SIDE EFFECT: If g_val is not nil then all unescaped
capital letters in symbols read by the
reader will be converted to lower case.
NOTE: This allows FRANZ LISP to be compatible with sin-
gle case lisp systems (e.g. Maclisp, Interlisp
and UCILisp).
9
9 Printed: October 7, 1982
System Functions 6-14
(status g_code)
RETURNS: the value associated with the status code
g_code if g_code is not one of the special
cases given below
(status ctime)
RETURNS: a symbol whose print name is the current time
and date.
EXAMPLE: (_s_t_a_t_u_s _c_t_i_m_e) ==> |Sun Jun 29 16:51:26 1980|
(status feature g_val)
RETURNS: t iff g_val is in the status features list.
(status features)
RETURNS: the value of the features code, which is a
list of features which are present in this
system. You add to this list with
(_s_s_t_a_t_u_s _f_e_a_t_u_r_e '_g__v_a_l) and test if feature
g_feat is present with
(_s_t_a_t_u_s _f_e_a_t_u_r_e '_g__f_e_a_t).
(status isatty)
RETURNS: t iff the standard input is a terminal.
(status localtime)
RETURNS: a list of fixnums representing the current
time.
EXAMPLE: (_s_t_a_t_u_s _l_o_c_a_l_t_i_m_e) ==> (3 51 13 31 6 81 5 211
1)
means 3_r_d second, 51_s_t minute, 13_t_h hour (1
p.m), 31_s_t day, month 6 (0 = January), year 81
(0 = 1900), day of the week 5 (0 = Sunday),
211_t_h day of the year and daylight savings
time is in effect.
9
9 Printed: October 7, 1982
System Functions 6-15
(status syntax s_char)
NOTE: This function should not be used. See the
description of _g_e_t_s_y_n_t_a_x (in Chapter 7) for a
replacement.
(status undeffunc)
RETURNS: a list of all functions which transfer table
entries point to but which are not defined at
this point.
NOTE: Some of the undefined functions listed could be
arrays which have yet to be created.
(status version)
RETURNS: a string which is the current lisp version
name.
EXAMPLE: (_s_t_a_t_u_s _v_e_r_s_i_o_n) ==> "Franz Lisp, Opus 33b"
(syscall 'x_index ['xst_arg1 ...])
RETURNS: the result of issuing the UNIX system call
number x_index with arguments xst_arg_i.
NOTE: The UNIX system calls are described in section 2
of the UNIX manual. If xst_arg_i is a fixnum, then
its value is passed as an argument, if it is a
symbol then its pname is passed and finally if it
is a string then the string itself is passed as
an argument. Some useful syscalls are:
(_s_y_s_c_a_l_l _2_0) returns process id.
(_s_y_s_c_a_l_l _1_3) returns the number of seconds since
Jan 1, 1970.
(_s_y_s_c_a_l_l _1_0 '_f_o_o) will unlink (delete) the file
foo.
(top-level)
RETURNS: nothing (it never returns)
NOTE: This function is the top-level read-eval-print
loop. It never returns any value. Its main
utility is that if you redefine it, and do a
(reset) then the redefined (top-level) is then
invoked.
9
9 Printed: October 7, 1982
System Functions 6-16
(wait)
RETURNS: a dotted pair (_p_r_o_c_e_s_s_i_d . _s_t_a_t_u_s) when the
next child process dies.
9
9 Printed: October 7, 1982