+.Lc System\ Functions 6
+.\".ch 6
+This chapter describes the functions which one uses to interact
+with
+.Fr
+running in the UNIX
+enviroment.
+.Lf allocate "'s_type 'x_pages"
+.Wh
+s_type is one of the
+.Fr
+data types described in \(sc1.3.
+.Re
+the number of pages actually allocated.
+.Se
+.Fr
+attempts to allocate x_pages of type s_type.
+.Lf argv "'x_argnumb"
+.Re
+a symbol whose pname is the x_argnumb\fIth\fP argument on the command
+line which invoked the current lisp.
+.No
+if x_argnumb is zero or less, a fixnum whose value is the number of arguments
+on the command line is returned.
+(argv\ 1) returns the name of the lisp you are running which is always
+the first argument.
+.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.
+See the function showstack for another way of printing the lisp runtime
+stack.
+.Lf bindstack
+.Lf boundp "'s_name"
+.Re
+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.
+.\".pg
+.Lf chdir "'s_path"
+.Re
+t iff the system call suceeds.
+.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.
+.Lf cont
+.Eq
+return
+.No
+cont should not be used in compiled code as the compiler does not
+believe that return and cont are equivalent.
+.Lf dumplisp "s_name"
+.Re
+nil
+.Se
+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.
+.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 will 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.
+.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.
+.\".pg
+.Lf gc
+.Re
+nil
+.Se
+this causes a garbage collection.
+.No
+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 enviroment.
+If s_name doesn't exist in the current enviroment, a symbol with a null pname
+is returned.
+.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 namestack
+.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.
+.br
+If s_arg is
+.i pagelimit
+then 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.
+.\".pg
+.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.
+.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.
+this 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, the
+second is the amount of time used by the garbage collector so far.
+.No
+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
+garbage collection times.
+.Lf rematom "'s_symb"
+.Re
+t
+.Se
+s_symb is placed on the free list of symbols.
+.No
+You must not do this unless s_symb is an uninterned atom.
+.Lf remob
+.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 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 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
+this is useful when making arrays.
+.Im
+what if there is no room.
+.\".pg
+.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 not show all of them.
+.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: Interrupt, Floating exception, Alarm, and
+Hang-up.
+.Lf sizeof "'g_arg"
+.Re
+the number of bytes required to store one object of type g_arg, encoded
+as a fixnum.
+.Lf sstatus "g_type g_val"
+.Re
+g_val
+.Se
+If g_type is not one of the special sstatus codes listed below
+this simply sets g_val as the value of status
+type g_type in the system status property list.
+.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 default 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.
+.\".pg
+.Lf sstatus\ feature "g_val"
+.Re
+g_val
+.Se
+g_val is added to the status features list,
+.Lf sstatus\ nofeature "g_val"
+.Re
+g_val
+.Se
+g_val is removed from the status features list if it was present.
+.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\ 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\ syntax "s_char"
+.Re
+a fixnum which is the syntax code associated with the character s_char
+in the current readtable.
+.No
+You cannot set the syntax code with with sstatus syntax, you must use
+.i setsyntax.
+.Lf syscall
+.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.
+.\".pg
+.Lf what "'g_arg"
+.Re
+the address of its argument converted into a fixnum. (Cf. fake).
projects / unix-history / commitdiff