-." @(#)ch6.n 34.1 1/29/81
-.Lc System\ Functions 6
-This chapter describes the functions which one uses to interact
-with
-.Fr
-running in the UNIX
-environment.
-.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.
-It allocates pages one at a time so that if an error occurs
-this means that all free storage has been allocated.
-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_argnumb\fIth\fP argument (starting at 0)
-on the command
-line which invoked the current lisp.
-.No
-if x_argnumb is less that zero, a fixnum whose value is the number of arguments
-on the command line is returned.
-\fI(argv\ 0)\fP 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 \fIbaktrace\fP 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.
-.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 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
-\fIchdir\fP 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 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 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 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 includef "'s_filename"
-.Re
-nil
-.Se
-this is the same as
-.i include
-except the argument is evaluated.
-.Lf maknum "'g_arg"
-.Re
-the address of its argument converted into a fixnum.
-.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
-\fIopval\fP keeps track of storage allocation. If s_arg is one of the data types
-then \fIopval\fP 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 \fIopval\fP associates
-with a data type using
-\fIopval\fP.
-.br
-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 "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 reset
-.Se
-the lisp runtime stack is cleared and the system restarts at the top level
-by executing a \fI(funcall\ top-level\ nil)\fP.
-.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 \fItop-level\fP 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
-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 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, 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 nil then 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.
-.Lf sstatus\ automatic-reset "g_val"
-.Re
-g_val
-.Se
-If g_val is non nil then when an error occurs which no one wants to
-handle, a
-.i reset
-will be done instead of entering a primitive internal break loop.
-.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.
-.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.
-.Lf sstatus\ feature "g_val"
-.Re
-g_val
-.Se
-g_val is added to the \fI(status\ features)\fP list,
-.Lf sstatus\ ignoreeof "g_val"
-.Re
-g_val
-.Se
-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.
-.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.
-.No
-For a discussion of transfer tables, see the Section on the compiler.
-.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. \s-2MAC\s0lisp).
-.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
-\fI(status ctime)\fP ==> |Sun Jun 29 16:51:26 1980|
-.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 \fI(sstatus\ feature\ 'g_val)\fP
-and test if feature g_feat is present with \fI(status\ feature\ 'g_feat)\fP.
-.Lf status\ isatty
-.Re
-t iff the standard input is a terminal.
-.Lf status\ localtime
-.Re
-a list of fixnums representing the current time as described in the
-UNIX manual under LOCALTIME(3).
-.Ex
-\fI(status localtime)\fP ==> (20 51 16 29 5 80 0 1 nil)
-.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 \fI(sstatus\ syntax\ ch)\fP,
-you must use
-.i setsyntax.
-.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
-\fI(status version)\fP ==> "Franz Lisp, Opus 33b"
-.Lf syscall "'x_index ['xst_arg1 ...]"
-.Re
-the result of issuing the UNIX system call number x_index with arguments
-xst_arg\fIi\fP.
-.No
-The UNIX system calls are described in section 2 of the UNIX manual.
-If xst_arg\fIi\fP 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:
-.br
-\fI(syscall\ 20)\fP returns process id.
-.br
-\fI(syscall\ 13)\fP returns the number of seconds since Jan 1, 1970.
-.br
-\fI(syscall\ 10\ 'foo)\fP will unlink (delete) the file foo.
-.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.