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 System Functions 6-1 System Functions 6-2 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 printing the lisp runtime stack. This misspel- ling is from Maclisp. (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. _C_h_d_i_r employs tilde-expansion (dis- cussed in Chapter 5). (command-line-args) RETURNS: a list of the arguments typed on the command line, either to the lisp interpreter, or saved lisp dump, or application compiled with the autorun option (liszt -r). (deref 'x_addr) RETURNS: The contents of x_addr, when thought of as a longword memory location. NOTE: This may be useful in constructing arguments to C functions out of `dangerous' areas of memory. (dumplisp s_name) RETURNS: nil SIDE EFFECT: the current lisp is dumped to the named file. 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. 9 9 Printed: January 31, 1984 System Functions 6-3 (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 12.3.2.1 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. (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. 9 9 Printed: January 31, 1984 System Functions 6-4 ____________________________________________________ -> (_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. ____________________________________________________ (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. 9 9 Printed: January 31, 1984 System Functions 6-5 (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. (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. (include-if 'g_predicate s_filename) RETURNS: nil SIDE EFFECT: This has the same effect as include, but is only actuated if the predicate is non- nil. 9 9 Printed: January 31, 1984 System Functions 6-6 (includef 's_filename) RETURNS: nil SIDE EFFECT: this is the same as _i_n_c_l_u_d_e except the argument is evaluated. (includef-if 'g_predicate s_filename) RETURNS: nil SIDE EFFECT: This has the same effect as includef, but is only actuated if the predicate is non- nil. (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, otherwise, an error is invoked. (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. Printed: January 31, 1984 System Functions 6-7 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 /bin/csh, then it tries /bin/sh if /bin/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 waits for the new process to die and then returns the exit code of the new process. If more two or three arguments are given, *_p_r_o_c_e_s_s starts the process and then returns a list which, depending on the value of g_readp and g_writep, may contain i/o ports for communcating with the new process. If g_writep is non-null, then a port will be created which the lisp program can use to send characters to the new process. If g_readp is non-null, then a port will be created which the lisp program can use to read characters from the new process. The value returned by *_p_r_o_c_e_s_s is (readport writeport pid) where read- port and writeport are either nil or a port based on the value of g_readp and g_writep. Pid is the process id of the new process. Since it is hard to remember the order of g_readp and g_writep, the functions *_p_r_o_c_e_s_s-_s_e_n_d and *_p_r_o_c_e_s_s-_r_e_c_e_i_v_e were written to perform the common functions. (*process-receive 'st_command) RETURNS: a port which can be read. SIDE EFFECT: The command st_command is given to the shell and it is started running 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. 9 9 Printed: January 31, 1984 System Functions 6-8 (*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. (ptime) RETURNS: a list of two elements. The first is the amount of processor time used by the lisp sys- tem so far, and the second is the amount of time used by the garbage collector so far. NOTE: the time is measured in those units used by the _t_i_m_e_s(2) system call, usually 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. 9 9 Printed: January 31, 1984 System Functions 6-9 (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 where _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. (*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) 9 9 Printed: January 31, 1984 System Functions 6-10 (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 where _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. (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. 9 9 Printed: January 31, 1984 System Functions 6-11 (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. (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. 9 9 Printed: January 31, 1984 System Functions 6-12 (sstatus appendmap g_val) RETURNS: g_val SIDE EFFECT: If g_val is non-null 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-null 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 initial 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 system should ever set this flag non nil. 9 9 Printed: January 31, 1984 System Functions 6-13 (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 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-null, and if string gar- bage collection was enabled when the lisp system was compiled, string space will be garbage collected. NOTE: the default value for this is nil since in most applications garbage collecting strings is a waste of time. (sstatus ignoreeof g_val) RETURNS: g_val SIDE EFFECT: If g_val is non-null when an end of file (CNTL-D on UNIX) is typed to the standard 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, an EOF will always cause lisp to exit. The initial value is nil. Printed: January 31, 1984 System Functions 6-14 (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 12.8. (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). (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 9 9 Printed: January 31, 1984 System Functions 6-15 (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| NOTE: This has been made obsolete by _t_i_m_e-_s_t_r_i_n_g, described below. (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. (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. 9 9 Printed: January 31, 1984 System Functions 6-16 (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 38.61" (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 Programmer's 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. (sys:access 'st_filename 'x_mode) (sys:chmod 'st_filename 'x_mode) (sys:gethostname) (sys:getpid) (sys:getpwnam 'st_username) (sys:link 'st_oldfilename 'st_newfilename) (sys:time) (sys:unlink 'st_filename) NOTE: We have been warned that the actual system call numbers may vary among different UNIX systems. Users concerned about portability may wish to use this group of functions. Another advantage is that tilde-expansion is performed on all filename arguments. These functions do what is described in the system call section of your UNIX manual. _s_y_s:_g_e_t_p_w_n_a_m returns a vector of four entries from the password file, being the user name, user Printed: January 31, 1984 System Functions 6-17 id, group id, and home directory. (time-string ['x_seconds]) RETURNS: an ascii string giving the time and date which was x_seconds after UNIX's idea of creation (Midnight, Jan 1, 1970 GMT). If no argument is given, time-string returns the current date. This supplants (_s_t_a_t_u_s _c_t_i_m_e), and may be used to make the results of _f_i_l_e_s_t_a_t more intelligible. (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. The default top-level for Franz, allow one to specify his own printer or reader, by binding the symbols top-level-printer and top- level-reader. One can let the default top-level do most of the drudgery in catching _r_e_s_e_t's, and reading in .lisprc files, by binding the symbol user-top-level, to a routine that concerns itself only with the read-eval-print loop. (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: January 31, 1984