All rights reserved.
%sccs.include.redist.roff%
@(#)ch6.n 6.2 (Berkeley) 04/17/91
." $Header: ch6.n,v 1.4 83/07/21 21:08:16 sklower Exp $ .Lc System Functions 6 .pp This chapter describes the functions used to interact with internal components of the Lisp system and operating system. .Lf allocate "'s_type 'x_pages" .Wh s_type is one of the .Fr data types described in \(sc1.3. .Re x_pages. .Se .Fr 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 .i segment and .i small-segment allocate blocks of storage and return it to the caller. .Lf argv "'x_argnumb" .Re a symbol whose pname is the x_argnumbth argument (starting at 0) on the command line which invoked the current lisp. .No if x_argnumb is less than zero, a fixnum whose value is the number of arguments on the command line is returned. (argv 0) returns the name of the lisp you are running. .Lf baktrace .Re nil .Se the lisp runtime stack is examined and the name of (most) of the functions currently in execution are printed, most active first. .No this will occasionally miss the names of compiled lisp functions due to incomplete information on the stack. If you are tracing compiled code, then baktrace won't be able to interpret the stack unless .i (sstatus translink nil) was done. See the function .i showstack for another way of printing the lisp runtime stack. This misspelling is from Maclisp. .Lf chdir "'s_path" .Re t iff the system call succeeds. .Se 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. .No chdir 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. .i Chdir employs tilde-expansion (discussed in Chapter 5). .Lf command-line-args .Re 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). .Lf deref "'x_addr" .Re The contents of x_addr, when thought of as a longword memory location. .No This may be useful in constructing arguments to C functions out of `dangerous' areas of memory. .Lf dumplisp "s_name" .Re nil .Se 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. .No 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. .Lf eval-when "l_time g_exp1 ..." .Se l_time may contain any combination of the symbols .i load , .i eval , and .i compile . The effects of load and compile is discussed in \(sc12.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. .Lf exit "['x_code]" .Re nothing (it never returns). .Se the lisp system dies with exit code x_code or 0 if x_code is not specified. .Lf fake "'x_addr" .Re the lisp object at address x_addr. .No This is intended to be used by people debugging the lisp system. .Lf fork .Re nil to the child process and the process number of the child to the parent. .Se 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 .i wait function is useful for this. .Eb -> (setq foo 'bar) ;; set a variable bar -> (cond ((fork)(wait))) ;; duplicate the lisp system and nil ;; make the parent wait -> foo ;; check the value of the variable bar -> (setq foo 'baz) ;; give it a new value baz -> foo ;; make sure it worked baz -> (exit) ;; exit the child (5274 . 0) ;; the wait function returns this -> foo ;; we check to make sure parent was bar ;; not modified. .Ee .Lf gc .Re nil .Se this causes a garbage collection. .No The function .i gcafter is not called automatically after this function finishes. Normally the user doesn't have to call .i gc since garbage collection occurs automatically whenever internal free lists are exhausted. .Lf gcafter "s_type" .Wh s_type is one of the .Fr data types listed in \(sc1.3. .No 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. .Lf getenv "'s_name" .Re 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. .Lf hashtabstat .Re a list of fixnums representing the number of symbols in each bucket of the oblist. .No the oblist is stored a hash table of buckets. Ideally there would be the same number of symbols in each bucket. .Lf help "[sx_arg]" .Se 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 argument is provided, .i help 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 continue after the space key is pressed. .Lf include "s_filename" .Re nil .Se The given filename is .i load ed into the lisp. .No this is similar to load except the argument is not evaluated. Include means something special to the compiler. .Lf include-if "'g_predicate s_filename" .Re nil .Se This has the same effect as include, but is only actuated if the predicate is non-nil. .Lf includef "'s_filename" .Re nil .Se this is the same as .i include except the argument is evaluated. .Lf includef-if "'g_predicate s_filename" .Re nil .Se This has the same effect as includef, but is only actuated if the predicate is non-nil. .Lf maknum "'g_arg" .Re the address of its argument converted into a fixnum. .Lf monitor "['xs_maxaddr]" .Re t .Se 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. .No this function only works if the lisp system has been compiled in a special way, otherwise, an error is invoked. .Lf opval "'s_arg ['g_newval]" .Re the value associated with s_arg before the call. .Se If g_newval is specified, the value associated with s_arg is changed to g_newval. .No opval keeps track of storage allocation. If s_arg is one of the data types then opval 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 opval associates with a data type using opval.
If s_arg is .i pagelimit then .i opval 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. .Lf *process "'st_command ['g_readp ['g_writep]]" .Re either a fixnum if one argument is given, or a list of two ports and a fixnum if two or three arguments are given. .No *process 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 *process, *process 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, *process 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 *process is (readport writeport pid) where readport 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 *process-send and *process-receive were written to perform the common functions. .Lf *process-receive "'st_command" .Re a port which can be read. .Se 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 process is set to /dev/null. .Lf *process-send "'st_command" .Re a port which can be written to. .Se 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 characters to the port returned by this function. The output of the command process is set to /dev/null. .Lf process "s_pgrm [s_frompipe s_topipe]" .Re 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. .No This command is obsolete. New programs should use one of the *process commands given above. .Se If s_frompipe and s_topipe are given, they are bound to ports which are pipes which direct characters from .Fr to the new process and to .Fr from the new process respectively. .i Process forks a process named s_prgm and waits for it to die iff there are no pipe arguments given. .Lf ptime .Re a list of two elements. The first is the amount of processor time used by the lisp system so far, and the second is the amount of time used by the garbage collector so far. .No the time is measured in those units used by the .i times (2) system call, usually 60ths 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. .Lf reset .Se the lisp runtime stack is cleared and the system restarts at the top level by executing a (funcall top-level nil). .Lf restorelisp "'s_name" .Se this reads in file s_name (which was created by .i savelisp ) and then does a (reset). .No This is only used on VMS systems where .i dumplisp cannot be used. .Lf retbrk "['x_level] .Wh x_level is a small integer of either sign. .Se 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 top-level 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. .Lf *rset "'g_flag" .Re g_flag .Se If g_flag is non nil then the lisp system will maintain extra information about calls to eval and funcall. This record keeping slows down the evaluation but this is required for the functions evalhook, funcallhook, and evalframe to work. To debug compiled lisp code the transfer tables should be unlinked: (sstatus translink nil) .Lf savelisp "'s_name" .Re t .Se the state of the Lisp system is saved in the file s_name. It can be read in by .i restorelisp . .No This is only used on VMS systems where .i dumplisp cannot be used. .Lf segment "'s_type 'x_size" .Wh s_type is one of the data types given in \(sc1.3 .Re a segment of contiguous lispvals of type s_type. .No In reality, .i segment returns a new data cell of type s_type and allocates space for x_size - 1 more s_type's beyond the one returned. .i Segment 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 .i small-segment is a smarter space allocator and should be used whenever possible. .Lf shell .Re the exit code of the shell when it dies. .Se this forks a new shell and returns when the shell dies. .Lf showstack .Re nil .Se 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. .Lf signal "'x_signum 's_name" .Re nil if no previous call to signal has been made, or the previously installed s_name. .Se 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). .Lf sizeof "'g_arg" .Re the number of bytes required to store one object of type g_arg, encoded as a fixnum. .Lf small-segment "'s_type 'x_cells" .Wh s_type is one of fixnum, flonum and value. .Re a segment of x_cells data objects of type s_type. .Se This may call .i segment to allocate new space or it may be able to fill the request on a page already allocated. The value returned by .i small-segment is usually stored in the data subpart of an array object. .Lf sstatus "g_type g_val" .Re g_val .Se 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. .Lf sstatus appendmap "g_val" .Re g_val .Se If g_val is non-null when .i fasl is told to create a load map, it will append to the file name given in the .i fasl command, rather than creating a new map file. The initial value is nil. .Lf sstatus automatic-reset "g_val" .Re g_val .Se If g_val is non-null when an error occurs which no one wants to handle, a .i reset will be done instead of entering a primitive internal break loop. The initial value is t. .Lf sstatus chainatom "g_val" .Re g_val .Se If g_val is non nil and a .i car or .i cdr of a symbol is done, then nil will be returned instead of an error being signaled. This only affects the interpreter, not the compiler. The initial value is nil. .Lf sstatus dumpcore "g_val" .Re g_val .Se If g_val is nil, .Fr tells UNIX that a segmentation violation or bus error should cause a core dump. If g_val is non nil then .Fr will catch those errors and print a message advising the user to reset. .No 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. .Lf sstatus dumpmode "x_val" .Re x_val .Se All subsequent .i dumplisp 's will be done in mode x_val. x_val may be either 413 or 410 (decimal). .No 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. .Lf sstatus evalhook "g_val" .Re g_val .Se When g_val is non nil, this enables the evalhook and funcallhook traps in the evaluator. See \(sc14.4 for more details. .Lf sstatus feature "g_val" .Re g_val .Se g_val is added to the (status features) list, .Lf sstatus gcstrings "g_val" .Re g_val .Se if g_val is non-null, and if string garbage collection was enabled when the lisp system was compiled, string space will be garbage collected. .No the default value for this is nil since in most applications garbage collecting strings is a waste of time. .Lf sstatus ignoreeof "g_val" .Re g_val .Se 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. .Lf sstatus nofeature "g_val" .Re g_val .Se g_val is removed from the status features list if it was present. .Lf sstatus translink "g_val" .Re g_val .Se 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 symbol .i on 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. .No For a discussion of transfer tables, see \(sc12.8. .Lf sstatus uctolc "g_val" .Re g_val .Se If g_val is not nil then all unescaped capital letters in symbols read by the reader will be converted to lower case. .No This allows .Fr to be compatible with single case lisp systems (e.g. Maclisp, Interlisp and UCILisp). .Lf status "g_code" .Re the value associated with the status code g_code if g_code is not one of the special cases given below .Lf status ctime .Re a symbol whose print name is the current time and date. .Ex (status ctime) = |Sun Jun 29 16:51:26 1980| .No This has been made obsolete by time-string, described below. .Lf status feature "g_val" .Re t iff g_val is in the status features list. .Lf status features .Re the value of the features code, which is a list of features which are present in this system. You add to this list with (sstatus feature 'g_val) and test if feature g_feat is present with (status feature 'g_feat). .Lf status isatty .Re t iff the standard input is a terminal. .Lf status localtime .Re a list of fixnums representing the current time. .Ex (status localtime) = (3 51 13 31 6 81 5 211 1)
means 3rd second, 51st minute, 13th hour (1 p.m), 31st day, month 6 (0 = January), year 81 (0 = 1900), day of the week 5 (0 = Sunday), 211th day of the year and daylight savings time is in effect. .Lf status syntax "s_char" .No This function should not be used. See the description of .i getsyntax (in Chapter 7) for a replacement. .Lf status undeffunc .Re a list of all functions which transfer table entries point to but which are not defined at this point. .No Some of the undefined functions listed could be arrays which have yet to be created. .Lf status version .Re a string which is the current lisp version name. .Ex (status version) = "Franz Lisp, Opus 38.61" .Lf syscall "'x_index ['xst_arg1 ...]" .Re the result of issuing the UNIX system call number x_index with arguments xst_argi. .No The UNIX system calls are described in section 2 of the UNIX Programmer's manual. If xst_argi 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:
(syscall 20) returns process id.
(syscall 13) returns the number of seconds since Jan 1, 1970.
(syscall 10 'foo) will unlink (delete) the file foo. .Lf sys:access "'st_filename 'x_mode" .Lx sys:chmod "'st_filename 'x_mode" .Lx sys:gethostname .Lx sys:getpid .Lx sys:getpwnam 'st_username .Lx sys:link "'st_oldfilename 'st_newfilename" .Lx sys:time .Lx sys:unlink 'st_filename .No 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.
.i sys:getpwnam returns a vector of four entries from the password file, being the user name, user id, group id, and home directory. .Lf time-string "['x_seconds]" .Re 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 (status ctime), and may be used to make the results of filestat more intelligible. .Lf top-level .Re nothing (it never returns) .No 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 .i reset '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. .Lf wait .Re a dotted pair (processid . status) when the next child process dies.