It is possible to define control characters in Lisp to execute functions at interrupt level. Handlers can be be set with the TTYINT option to STATUS and SSTATUS.

Interrupt handlers are normally functions of two arguments, char and stream (upon which char was typed).

Certain primitive character interrupt handlers are defined which are safe to run even if garbage collection is in progress. Rather than use a function name, these primitive handlers are identified by the numeric code for the character which initially had the desired functionality. For example, the initial handler for Control-G is called 7 (or #^G).

The following control characters are defined as interrupt characters in Maclisp:

Interrupt handlers run with interrupts disabled unless the handler function explicitly re-enables interrupts.

Also, the interrupting character will still be on the input stream. In fact, there may be other characters ahead of it on the input stream since an interrupt runs immediately even before finishing pre-scanning other non-interrupting input.

Note that Control-S has the same definition as Control-W but a different effect. This is because Control-S only disables typeout at the interrupt level. Later, when seen by READ (usually in the Read-Eval-Print loop), it is also a splicing readmacro character which turns type-out back on. Control-W lacks this readmacro definition, so leaves typeout turned off until a Control-V is typed or until the variable ^W is somehow turned back on.

Control-H (backspace), which many Lisp versions ago caused a Lisp breakpoint is now a normal alphabetic character. Control-B has superseded it as the proper way to invoke a breakpoint at interrupt level.

Control-K (which re-types input to the READ and READLINE functions) and Control-L (which clears the screen and then re-types input) are not interrupt characters. They are handled at the tty prescan level.

Control-Q is not an interrupt character, it is a tty force-feed character.

[PDP-10 Only] Sets the tty interrupt information for char on a given tty input file array, fileobj (default T, the terminal), to a given val, which must be a handler such as would be later returned by (STATUS TTYINT ...).

Multics users may want (STATUS INTERRUPT).

Note that an interrupt can be associated with any ASCII character, not just control characters. On ITS, one must use (SSTATUS TTY) to tell ITS that things like "?" or "#" are to be considered interrupt characters (this is similar to the activation character problem).

Note also that initially Control-S is set to be like Control-W as an interrupt character (see below).

[PDP-10 Only] Returns the tty interrupt information for char on a given tty input file array, which defaults to T, the terminal. All argument positions are evaluated.

The char may be a character in fixnum or symbol representation.

In the initial Lisp system, Control-A is an interrupt which sets ^A to T. This was from the early days of Lisp when general tty interrupts were not available -- programs could query the value of ^A to see if it had changed from NIL (and reset the value to NIL so they could detect such interrupts again later).

[ITS Only] The symbol CLI-MESSAGE, if not NIL, should be a function of one argument which handles a interrupt on the Lisp job's CLI device. The argument may be ignored since it is always NIL. To handle the interrupt, the function should open the “CLA:” device in order to read the message. One of the options in OPEN's second argument should be CLA (as opposed to DSK or TTY) because of the format of the input stream read from the CLA device (see ITS system documentation for more about this problem). This causes open to read the first two words of the file and use them as the file names for the truename function. The CLA: file should be opened in block mode for this purpose.

If CLI-MESSAGE is set to NIL, such interrupts are ignored. This is the default case.

[ITS only] Says whether CLI handling is enabled. See documentation on the CLI-MESSAGE variable.

[ITS Only] If flag is T, enables CLI handling using the handler given by the CLI-MESSAGE variable. If flag is NIL, disables CLI interrupt handling.

The value of this variable is a handler to be called if an interrupt is received from the operating system saying that the system is going down.

[ITS Only] Useful in conjunction with the SYS-DEATH interrupt is (STATUS ITS). This returns a list of five numbers:

This information is obtained from the ITS SSTATU system call.

[ITS Only] This is a handler to be run upon return from the superior job.

[ITS and Multics only] ALARMCLOCK is a function for controlling timers. It can start and stop two seperate timers; one is a real-time timer and the other is a cpu-time timer. The first argument to ALARMCLOCK indicates which timer is being referred to: it may be the symbol TIME to indicate the real-time timer or the symbol RUNTIME to indicate the cpu-time timer. The second argument to alarmclock controls what is done to the selected timer. If it is a positive (non-bignum) number the timer is started. Thus if q is a positive fixnum or flonum, then (ALARMCLOCK 'TIME q) sets the real-time timer to go off in q seconds, and (ALARMCLOCK 'RUNTIME q) sets the cpu-time timer to go off in q microseconds. If the timer was already running the old setting is lost. Thus at any given time each timer can only be running for one alarm, but the two timers can run simultaneously. If the second argument to ALARMCLOCK is not a positive number, the timer is shut off, so (ALARMCLOCK timername NIL) or (alarmclock timername -1) shuts off the timer. ALARMCLOCK returns T if it starts a timer, NIL if it shuts it off. When a timer goes off, the handler for that interrupt (controlled by the variable ALARMCLOCK), if any, is run in (NOINTERRUPT T) mode so that it can not be interrupted until it has done its thing. If it wants to allow interrupts, other timers, etc. it can do (NOINTERRUPT NIL). In any case the status of the nointerrupt flag will be restored when the handler function returns (see NOINTERRUPT).

[ITS and Multics only] The value of alarmclock is the handler for the timer interrupt, which is signalled when a timer set up by the ALARMCLOCK function goes off.

The handler function should be a function of one argument, which will be a list of one element, the symbol TIME or the symbol RUNTIME, depending on the first argument in the call to the ALARMCLOCK function which set up the timer.

causes a real-time delay of k seconds, then returns T. k may be a fixnum or a flonum.

[PDP-10 Only] (NOINTERRUPT T) shuts off Lisp interrupts. This prevents alarmclock timers from going off and prevents the use of control characters such as Control-G and Control-B. Any of these interrupts that occur are simply deferred until interrupts are re-enabled. (NOINTERRUPT T) mode is used to protect critical code in large subsystems written in Lisp. It is also used by the Lisp subsystem itself to protect against interrupts in the garbage collector.

(NOINTERRUPT NIL) turns interrupts back on. Any interrupts which were saved will now get processed. NOINTERRUPT returns the previous state of the interruptdisable switch, T or NIL. The normal, initial state is NIL.

In most cases, it is best to bind interrupts using the WITHOUT-INTERRUPTS special form.

Reads the value of the pseudo-variable +INTERNAL-WITHOUT-INTERRUPTS. This variable should never be set, only bound. To set it, use (SSTATUS NOINTERRUPTS ...). Even when bound, it will always appear to be bound to NIL. This is the only right way to read the value it has been bound to.

Sets the value of (STATUS NOINTERRUPTS) to T or NIL according to flag.

Executes form₁, form₂, etc. from left to right returning the value of the last. During execution, interrupts are disabled. After execution, interrupts are restored to the state they had prior to the WITHOUT-INTERRUPTS form. If interrupts had been off, they remain off; if interrupts had been enabled, they are re-enabled.

Returns a list of symbols representing the features implemented in the LISP being used. The main idea behind this STATUS call is that an application package can be loaded into any MACLISP implementation and can decide what to do on the basis of the features it finds available. e.g., possible features include:

The old idiom (CAR (LAST (STATUS FEATURES))), which was generally considered to be an implementation name, such as ITS or DEC10 or Multics is now discouraged. Use (STATUS SITE), (STATUS FILESYSTEM-TYPE), or (STATUS OPSYSTEM-TYPE) as appropriate instead.

The most frequent use of the features list is through the reader macro sequences #+sym and #-sym. This functionality is more fully described elsewhere, but simply put, the form after a #+sym is invisible to READ unless (STATUS FEATURE sym) is true in the readtime environment. Similarly, #-sym is visible only in environments where (STATUS NOFEATURE sym) is true. For example, the expression

is read by a Lisp reader running on ITS as (ABC DEF). In a Maclisp under some other operating system, (ABC GHI) would be the result of READ on the above text. And on a Lisp Machine, (ABC GHI JKL) would be seen by READ. Use of the #+ and #- readtime conditionalization is, however, not recommended for novices.

Returns T if sym is on the features list, else NIL. The sym is not evaluated.

Adds sym to the features list. The sym is not evaluated.

Returns T if sym is not on the features list, else NIL. The sym is not evaluated.

Removes sym from the features list. The sym is not evaluated.

Returns the version number of this Maclisp as an atomic symbol.

[PDP-10 Only] Returns a site name such as AI, ML, MC, CMU, SAIL, etc., or the kind of operating system if Lisp does not know the site name (i.e., TOPS-20, TENEX, or TOPS-10).

System maintainers: To get it to return the name of a site rather than just the site type, try creating a file LISP:SITE.TXT whose only contents is the string which is the printname of the symbol (STATUS SITE) should return.

[PDP-10 Only] Returns one of ITS, DEC20, OR DEC10.

[PDP-10 Only] Returns one of ITS, TOPS-20, TENEX, TOPS-10, CMU, or SAIL.

[Multics Only] Returns the n+1th argument of the lisp command, as an interned atomic symbol. NIL is returned if n is more than the number of arguments on the lisp command.

In the PDP-10 implementation, returns the “job command line” as a list of characters (see EXPLODEC).

In Multics, jcl is more structured. The first “argument” to the Multics lisp command, if given, is used to designate a saved environment to start Lisp with. The second “argument,” if present, is returned (in EXPLODEC'd format) by (STATUS JCL). If no second argument was given, (STATUS JCL) returns NIL.

[PDP-10 Only] Obsolete. Replaced by (STATUS SUBSYSTEM).

[PDP-10 Only] Returns the true name this job (ITS) or fork (Tops-20) wanted to run under. For example, on ITS, if multiple LISP jobs are started, they are called LISP0, LISP1, etc. (STATUS JNAME) will get the names with the digits, but (STATUS SUBSYSTEM) should always return just LISP for this case.

Eventually this will be made meaningful on TOPS-10 and multics implementations. The intended interpretation is “the generic name of this program.”

[PDP-10 Only] This returns “the unique identifier of this job within the time-sharing system.” For example, on systems where the first of many Lisp forks for a user is LISP, the second is LISP0, etc., (STATUS JNAME) will return values like LISP0. See also (STATUS SUBSYSTEM).

On Tops-10, returns a job identifier of form nnnLSP, where nnn is a TOPS-10 job number.

[PDP-10 Only] Returns the job's job number.

[ITS Only] Returns information about the superior job. The following return values are defined:

This information is determined from information in the ITS job's .OPTION user variable.

Returns an atomic symbol whose pname is the current user's name or ppn. In the Multics implementation this is in the format User.Project; the dot will be slashified if print is used to display this.

[PDP-10 Only] Returns the user's real user name. On ITS, multiple logins of a user JDOE will get names like JDOE0 and JDOE1 assigned for that login session. (STATUS USERID) will always return the real name, JDOE in this case. To get names like JDOE0, you want (STATUS UNAME).

[PDP-10 Only] Archaic. Use (STATUS USERID).

Returns the name of the file directory the user was connected to at the time the Lisp was started.

[PDP-10 Only] Returns the user's home directory as an interned symbol.

[PDP-10 Only] For non-ITS sites, this is like (STATUS HOMEDIR). The arguments uname and sitename are only meaningful on ITS sites. Elsewhere they are likely to be ignored or an error. On ITS, however, they may find the home directory of user on a given ITS site. The value of uname defaults to the Lisp user's name, and sitename defaults to the current site.

Returns the number of microseconds of cpu time used so far by the process in which LISP is running. The difference between two values of (RUNTIME) indicates the amount of computation that was done between the two calls to runtime.

Returns the time that the system has been up as a flonum in seconds.

Returns the day of the week as an interned symbol in uppercase. For example, on Monday, (STATUS DOW) returns the symbol MONDAY.

Returns the current date as a 3-list of fixnums, representing the date as (year month date), where year is based on 1900 and where month and date are based on 1. So July 4, 1976 would be (76. 7. 4.).

Returns a 3-list of fixnums representing the current time of day as 24-hour clock time in the form of a list, (hour minute second), where all elements are based on 0. So the time 4:15:37pm would be given by (16. 15. 37.).

Archaic. The same as (TIME), the number of seconds the system has been up.

Archaic. The same as (RUNTIME), the number of microseconds of cpu time that has been used.

SUSPEND is used to save an entire loaded environment as an executable image for later invocation. This is how subsystems built on top of Lisp are created. To use SUSPEND, you must first load your system, then close any files you have opened except TYI and TYO. Then call SUSPEND. On the next page is a sample of an init file to dump a system.

The optional arguments to SUSPEND have meaning only on ITS. The data argument may be a string to VALRET after doing the argument, or bits to use in a .BREAK 16,, or NIL meaning to not suspend at all (only useful when file is also specified). If file is given, the current environment is dumped as an executable file (a TS file). If file is not specified, the user is expected to use DDT to dump the file. Also, if the filename is specified and the value of (STATUS FLUSH) is not NIL, then the shared parts of the Lisp will not be saved.

On non-ITS sites, just call (SUSPEND) with no arguments and save according to the site-specific saving protocol. For example, on Tops-20...

A suspended Lisp can be continued on ITS (with $P or :CONTINUE). On non-ITS sites, a suspended Lisp must be restarted (e.g., by START from the Tops-20 Exec).

Alternatively, after having saved the Lisp to a file (either by the file argument to SUSPEND or by some Exec or DDT save command), it is appropriate to kill the Lisp. This can be done all at once on ITS by something like:

[ITS Only] This does system calls. n should be the number of values that will be returned. they will be returned as a list, unless an error occurs, in which case a numeric code describing the error will be returned.

(VALRET) is supposed to be like the now-obsolete (IOC Z); that is, it does a .LOGOUT if LISP is a top level procedure, and otherwise valrets ":VK " to DDT.

*** Warning: There is a bad bug wherein (VALRET) will kill your Lisp rather than returning harmlessly, making it work more like (QUIT). Hence, this form should probably be avoided.

If an argument is provided but is not a symbol, it will be converted to a symbol.

If the string of characters making up sym is one of "$^X.", ":KILL ", or ":KILL^M" (the letters of KILL must be capitalized) then valret performs a "silent kill" by executing a .BREAK 16,20000. This may also allow programs that VALRET these forms to be transported to non-ITS sites and still work, though in practice it's not wise to depend on such a feature.

If the sym isn't one of those special configurations, it is passed to the superior (usually DDT) on ITS or placed in the rescan buffer on Tops-20. The superior job (ITS) or fork (Tops-20) will then usually execute the commands it has been passed.

Here are some examples from the ITS implementation:

[PDP-10 Only] Returns the machine location represented by the symbolic name which is the argument. This works only if symbols have been loaded for the job. If symbols are not loaded, NIL is returned.

[PDP-10 Only] Assigns sym as the DDT symbolic name of location i.

[PDP-10 Only] Supposedly an ITS-only feature. Allocates a piece of memory of datatype space, n words big (actually rounds up to enough words to fill a page). The returned value is a fixnum which is the address of the first word of the chunk of memory or 0 if the memory could not be gotten. GC will mark through the space if it is of type LIST, BIGNUM, or HUNK. The data in the memory itself is not marked or swept. No guarantees are made if space is SYMBOL or ARRAY --- all other types should work.

In spite of its return value convention, do not do (DECLARE (FIXNUM (LH/|))); this is not a fixnum function.

[PDP-10 Only] Returns a fixnum representing the raw contents of address which is given as its argument. (See also LH/| and DEPOSIT.)

[PDP-10 Only] Both arguments must be fixnums. Deposits in a given machine address a fixnum value. A good way to get around using Lisp-pointers for certain specialized applications but highly machine-dependent and not recommended for general use. (See also LH/| and EXAMINE.)

[PDP-10 Only] Returns the address of symbol's value cell. The value cell itself is a cons whose cdr points at the value. Ages ago, when the value cell lived on the property list of a symbol, (GET sym 'VALUE) used to obtain the value cell. In modern Maclisp, (MAKNUM (VALUE-CELL-LOCATION sym)) does that.

A dereferencing operator. Returns the machine address of q. Reasonably machine-dependent. In worlds with relocating garbage-collectors, it may be prone to timing-errors and hence useless.

*** Actually, this does something reasonably useful on Multics, but it doesn't return a machine address. ***

This will return a pointer to the object at machine location specified by its argument. It is not recommended as a way of creating objects, but can be used effectively in undoing a dereference of an object (as done by MAKNUM).

Note: MUNKAM is MAKNUM spelled backwards.

SXHASH computes a hash code of an S-expression, and returns it as a (possibly negative) fixnum. A property of SXHASH is that

The number returned by SXHASH is some possibly large number in the range allowed by fixnums. It is guaranteed that:

[PDP-10 Only] Returns info about which of two SXHASH algorithms is in use. If T, the default, then the old SXHASH algorithm is in effect. If NIL, the new SXHASH algorithm is in effect. This algorithm is incompatible with the old one, so might break some programs and hence is not the default. It tries to fix the bug of SXHASH working too symmetrically on lists. The new SXHASH algorithm defines (SXHASH x) to mean:

[PDP-10 Only] Sets the state of the SXHASH switch to flag. See documentation on (STATUS SXHASH).

The ALLOC function is used to examine and set parameters of various spaces having to do with storage management. To set parameters, the argument to alloc should be a list containing an even number of elements. The first element of a pair is the name of a space, and the second is either a fixnum or a 3-list. A fixnum specifies the PDLSIZE (for a pdl space) or the GCSIZE (for other spaces). A 3-list cannot be used with pdl space. It specifies, from left to right, the GCSIZE, GCMAX, and GCMIN. NIL means "don't change this parameter." Otherwise a fixnum must be supplied, except in the third element (the GCMIN), where a flonum is acceptable.

An example of this use of ALLOC, in the PDP-10 (BiBOP) implementation:

or, in the Multics implementation:

ALLOC may also be called with an argument of T, which causes it to return a list of all the spaces and their parameters. This list is in a form such that it could be given back to ALLOC at some later time to set the parameters back to what they are now.

Valid space names for the PDP-10 are LIST, FIXNUM, FLONUM, BIGNUM, SYMBOL, ARRAY, HUNK2, HUNK4, HUNK8, HUNK16, HUNK32, HUNK64, HUNK128, HUNK256, HUNK512, REGPDL, FLPDL, FXPDL, and SPECPDL.

The REGPDL is the “regular pdl.” It holds control information, compiled local variables, and arguments. The garbage collector marks through the relevant parts of this pdl. Naming conventions are not uniform in Maclisp for this pdl; elsewhere (e.g., in STATUS) this is called just PDL, not REGPDL.

The SPECPDL is the “special pdl.” It holds information about special variables which have been dynamically bound. Bindings are shallow, so the values on this pdl are the inactive values, not the active ones. Relevant parts of this pdl are marked through by the garbage collector.

The FLPDL, or “flonum pdl,” and the FXPDL, or “fixnum pdl,” contain 36-bit fixnum and flonum data which are temporaries being used by compiled code, number-declared compiled local variable storage, etc. These pdls are not marked through by the garbage collector.

Causes a garbage collection and returns NIL.

[PDP-10 Only] If first arg is a symbol, merely sets the flag in the symbol-header which says “compiled code needs me”; such symbols will never be GC'd. Otherwise, it does a hash-table look-up of the s-expresssion on an internal array (stored in the cell labelled “GCPSAR:”) just like INTERN; so you get EQification for random list structure, which is what FASLOAD does in order to minimize duplication in "constant" structures. If second arg is "?", then it merely does a lookup, with no interning - sort of like INTERNDP. One other crinkle added to this function was for the benefit of the OWL system: if the value of the symbol GCPROTECT is not NIL, then this “interning” action is not done, but instead each structure (except symbols, of course) is freshly consed up.

GCTWA is used to control the garbage collection of “truly worthless atoms,” which are atomic symbols which have no value and no special properties, and which are not referenced by any list structure, other than the obarray (the current obarray if there is more than one).

(GCTWA) causes truly worthless atoms to be removed on the next garbage collection.

The flag, if supplied, is not evaluated and must be one of T or NIL.

(GCTWA T) causes truly worthless atoms to be removed on each garbage collection from now on.

(GCTWA NIL) causes this continual removal of truly worthless atoms to be shut off, but it does not affect whether the next garbage collection removes such atoms.

Note: The “A” for “atom” in “GCTWA”is really misleading, since GCTWA affects the behavior of the garbage collector with respect to only symbols and not with respect to other kinds of atoms (such as numbers, arrays, etc.). However, this should cause no problem since the garbage collector can tell what truly worthless numbers, etc. are without needing hints from a switch.

The meaning of the value returned by GCTWA is given by the following table (numbers shown are in octal):

It is possible to test whether subsequent GC's are going to collect truly worthless atoms by checking the value of of the variable GCTWA.

[PDP-10 Only] Holds a value saying whether the default during GC's is for “truly worthless atoms” are to be GC'd (T means Yes, NIL means No). See documentation on the GCTWA function for more information.

Returns a list of the system properties of the atomic symbol sym, which is evaluated. This list may contain SUBR, FSUBR, LSUBR, MACRO, or AUTOLOAD if sym denotes a function; VALUE if it is a variable in the initial system; and will always contain SYMBOL for initial symbols. Note that symbols defined only by out-of-core packages do not answer T to (STATUS SYSTEM sym) so this feature is of limited value. If it answers with something other than NIL, you can be sure the argument was an initial Lisp symbol, but if it returns NIL, you cannot be sure that it is not. Further, this STATUS option must cons the list of properties, so it's somewhat storage inefficient since generally all it gets used for is for boolean value in the first place.

On Multics, the list returned never contains any of the symbols SYMBOL, MACRO, or AUTOLOAD.

Examples:

If sym, which must be a symbol, is the name of a system function (and has not been redefined), SYSP returns the type of function (SUBR, LSUBR, or FSUBR). Otherwise, it returns NIL.

Examples:

[PDP-10 Only] Usually, just calling the garbage collector directly (see GC) or waiting for it to run is the right way to deal with the recycling of storage. For those rare cases where this is not enough, RECLAIM is provided to allow an individual piece of storage to be returned without running the entire garbage collector mechanism.

This function reclaims list structure or numbers; i.e., returns them to the “free list.” The user is responsible for dropping all pointers to RECLAIMed object; failure to do so will leave him with pointers into the free list. Pure cells, value cells, hunks, arrays, objects of type random, and pointers to stack-allocated objects are ignored by RECLAIM. Only heap-consed lists and numbers will be reclaimed.

If flag is NIL, only the top level of obj is reclaimed. If obj is a number, that number is reclaimed. If obj is a list, the top level of conses in that list are reclaimed.

If flag is T, all levels are reclaimed. If obj is a number, that number is reclaimed. If obj is a list, all levels of that list are reclaimed.

Given:

(RECLAIM X5 NIL) would reclaim the three cells of X5.

(RECLAIM FOO NIL) would reclaim the five toplevel cells of FOO, leaving X1, X2, N1, etc. intact.

(RECLAIM FOO T) would reclaim all list cells in FOO except those in X3 because RECLAIM will not recurse into the hunk. The hunk itself will also not be reclaimed. The numbers held by N1 and N3 would also be reclaimed.

(RECLAIM N2 NIL) and (RECLAIM N2 T) would do the same thing; i.e., reclaim the number held by N3.

The behavior of RECLAIM with respect to hunks is not affected by the value of HUNKP.

The value of the variable GC-DAEMON, if not NIL, should be a function of one argument to be called after each garbage collection.

*** What is the nature of the argument? ***

[PDP-10 Only] The value of the variable GC-OVERFLOW is a function of 1 argument to be run when a GC-OVERFLOW condition is signalled.

*** When are they signalled? What does it mean to handle this condition? What happens with return values? ***

[PDP-10 Only] If the value of the symbol "GCPROTECT" is not NIL, then the "interning" action described in documentation for the GCPROTECT function is not done, but instead each structure (except symbols, of course) is freshly consed up.

If the value of the symbol ^D (Uparrow D, not Control-D) is not NIL, the garbage collector prints an informative message after each garbage collection.

Typing Control-D sets the variable ^D to T. By default, typing Control-C interactively to a Lisp sets this variable back to NIL, except on Tops-20 where the system definition of Control-C has precedence over the Lisp definition of Control-C, so there is no easy way to set this variable back to NIL other than (SETQ ^D NIL).

Returns the number of microseconds spent garbage collecting.

Resets the gctime counter to n and returns the previous value of the GCTIME counter. See also (STATUS GCTIME).

[PDP-10 Only] Returns the GCMAX parameter for a given space, which is evaluated. See ALLOC for more information about GCMAX.