BSD 4_1_snap release

[unix-history] / usr / doc / lisp / ch6.n

diff --git a/usr/doc/lisp/ch6.n b/usr/doc/lisp/ch6.n
index 965329a..2ddf951 100644 (file)
--- a/usr/doc/lisp/ch6.n
+++ b/usr/doc/lisp/ch6.n
@@ -1,29 +1,38 @@
+." @(#)ch6.n   34.1 1/29/81

 .Lc System\ Functions 6
 .Lc System\ Functions 6

-.\".ch 6

 This chapter describes the functions which one uses to interact
 with 
 .Fr
 running in the UNIX
 This chapter describes the functions which one uses to interact
 with 
 .Fr
 running in the UNIX

-enviroment.
+environment.

 .Lf allocate "'s_type 'x_pages"
 .Wh
 s_type is one of the 
 .Fr
 data types described in \(sc1.3.
 .Re
 .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.
+x_pages.

 .Se
 .Fr
 attempts to allocate x_pages of type s_type.
 .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
 .Lf argv "'x_argnumb"
 .Re

-a symbol whose pname is the x_argnumb\fIth\fP argument on the command
+a symbol whose pname is the x_argnumb\fIth\fP argument (starting at 0)
+on the command

 line which invoked the current lisp.
 .No
 line which invoked the current lisp.
 .No

-if x_argnumb is zero or less, a fixnum whose value is the number of arguments
+if x_argnumb is less that zero, a fixnum whose value is the number of arguments

 on the command line is returned.
 on the command line is returned.

-(argv\ 1) returns the name of the lisp you are running which is always
-the first argument.
+\fI(argv\ 0)\fP returns the name of the lisp you are running.

 .Lf baktrace 
 .Re
 nil
 .Lf baktrace 
 .Re
 nil


@@ -33,9 +42,14 @@ 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.
 .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
+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.
 stack.

-.Lf bindstack

 .Lf boundp "'s_name"
 .Re
 nil  if s_name is unbound, that is it has never be given a value.
 .Lf boundp "'s_name"
 .Re
 nil  if s_name is unbound, that is it has never be given a value.


@@ -43,21 +57,15 @@ If x_name has the value g_val, then (nil\ .\ g_val) is returned.
 .\".pg
 .Lf chdir "'s_path"
 .Re
 .\".pg
 .Lf chdir "'s_path"
 .Re

-t iff the system call suceeds.
+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
 .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
+\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.
 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
 .Lf dumplisp "s_name"
 .Re
 nil


@@ -118,9 +126,16 @@ an nlambda.
 .Lf getenv "'s_name"
 .Re
 a symbol whose pname is the value of s_name in the current 
 .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
+UNIX environment.
+If s_name doesn't exist in the current environment, a symbol with a null pname

 is returned.
 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
 .Lf include "s_filename"
 .Re
 nil


@@ -131,7 +146,16 @@ into the lisp.
 .No
 this is similar to load except the argument is not evaluated.
 Include means something special to the compiler.
 .No
 this is similar to load except the argument is not evaluated.
 Include means something special to the compiler.

-.Lf namestack
+.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.
 .Lf opval "'s_arg ['g_newval]"
 .Re
 the value associated with s_arg before the call.


@@ -139,23 +163,24 @@ the value associated with s_arg before the call.
 If g_newval is specified, the value associated with s_arg is changed to
 g_newval.
 .No
 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
+\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.  
 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
+You should never try to change the value \fIopval\fP associates

 with a data type using
 with a data type using

-opval.
+\fIopval\fP.

 .br
 If s_arg is 
 .i pagelimit
 .br
 If s_arg is 
 .i pagelimit

-then opval will return (and set if g_newval is given)
+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.
 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
 .Lf process "s_pgrm [s_frompipe s_topipe]"
 .Re
 if the optional arguments are


@@ -184,18 +209,10 @@ 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.
 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 
 .Lf reset
 .Se
 the lisp runtime stack is cleared and the system restarts at the top level 

-by executing a (funcall\ top-level\ nil).
+by executing a \fI(funcall\ top-level\ nil)\fP.

 .Lf retbrk "['x_level]
 .Wh
 x_level is a small integer of either sign.
 .Lf retbrk "['x_level]
 .Wh
 x_level is a small integer of either sign.


@@ -203,7 +220,7 @@ x_level is a small integer of either sign.
 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 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.
+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.
 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.


@@ -213,10 +230,17 @@ s_type is one of the data types given in \(sc1.3
 .Re
 a segment of contiguous lispvals of type s_type.
 .No
 .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
+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.
 .Lf shell
 .Re
 the exit code of the shell when it dies.


@@ -237,25 +261,71 @@ installed s_name.
 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
 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.
+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 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
 .Lf sstatus "g_type g_val"
 .Re
 g_val
 .Se

-If g_type is not one of the special sstatus codes listed below
+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.
 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, 
 .Lf sstatus\ dumpcore "g_val"
 .Re
 g_val
 .Se
 If g_val is nil, 

-.Fr tells UNIX that a segmentation violation or 
+.Fr 
+tells UNIX that a segmentation violation or 

 bus error should cause a core dump.
 If g_val is non nil then 
 .Fr
 bus error should cause a core dump.
 If g_val is non nil then 
 .Fr


@@ -274,21 +344,59 @@ 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.
 .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
 .Lf sstatus\ feature "g_val"
 .Re
 g_val
 .Se

-g_val is added to the status features list, 
+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\ 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 "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\ feature "g_val"
 .Re
 t iff g_val is in the status features list.


@@ -296,16 +404,54 @@ t iff g_val is in the status features list.
 .Re
 the value of the features code, which is a list of features which
 are present in this system.
 .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).
+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
 .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
+You cannot set the syntax code with with \fI(sstatus\ syntax\ ch)\fP, 
+you must use

 .i setsyntax.
 .i setsyntax.

-.Lf syscall
+.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)
 .Lf top-level
 .Re
 nothing (it never returns)


@@ -314,7 +460,3 @@ 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.
 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).