48. "Miscellaneous Useful Functions"

This chapter describes a number of functions which don't logically fit in anywhere else. Most of these functions are not normally used in programs, but are "commands", i.e. things that you type directly at Lisp.

48.1 Poking Around in the Lisp World

Function: who-calls x &optional package

Function: who-uses x &optional package

x must be a symbol or a list of symbols. who-calls tries to find all of the functions in the Lisp world which call x as a function, use x as a variable, or use x as a constant. (It won't find things that use constants which contain x, such as a list one of whose elements is x; it will only find it if x itself is used as a constant.) It tries to find all of the functions by searching all of the function cells of all of the symbols on package and package's descendants. package defaults to the global package, and so normally all packages are checked.

If who-calls encounters an interpreted function definition, it simply tells you if x appears anywhere in the interpreted code. who-calls is smarter about compiled code, since it has been nicely predigested by the compiler.

If x is a list of symbols, who-calls does them all simultaneously, which is faster than doing them one at a time.

who-uses is an obsolete name for who-calls.

The editor has a command, Meta-X List Callers, which is similar to who-calls.

The symbol unbound-function is treated specially by who-calls. (who-calls 'unbound-function) will search the compiled code for any calls through a symbol which is not currently defined as a function. This is useful for finding errors such as functions you misspelled the names of or forgot to write.

who-calls prints one line of information for each caller it finds. It also returns a list of the names of all the callers.

Function: what-files-call x &optional package

Similar to who-calls but returns a list of the pathnames of all the files which contain functions that who-calls would have printed out. This is useful if you need to recompile and/or edit all of those files.

Function: apropos string &optional package

(apropos string) tries to find all symbols whose print-names contain string as a substring. Whenever it finds a symbol, it prints out the symbol's name; if the symbol is defined as a function and/or bound to a value, it tells you so, and prints the names of the arguments (if any) to the function. It finds the symbols on package and package's decendants. package defaults to the global package, so normally all packages are searched. apropos returns a list of all the symbols it finds.

Function: where-is pname &optional package

Prints the names of all packages which contain a symbol with the print-name pname. If pname is a string it gets upper-cased. The package package and all its sub-packages are searched; package defaults to the global package, which causes all packages to be searched. where-is returns a list of all the symbols it finds.

Function: describe x

describe tries to tell you all of the interesting information about any object x (except for array contents). describe knows about arrays, symbols, flonums, packages, stack groups, closures, and FEFs, and prints out the attributes of each in human-readable form. Sometimes it will describe something which it finds inside something else; such recursive descriptions are indented appropriately. For instance, describe of a symbol will tell you about the symbol's value, its definition, and each of its properties. describe of a flonum (regular or small) will show you its internal representation in a way which is useful for tracking down roundoff errors and the like.

If x is a named-structure, describe handles it specially. To understand this, you should read the section on named structures (see (named-structure)). First it gets the named-structure symbol, and sees whether its function knows about the :describe operation. If the operation is known, it applies the function to two arguments: the symbol :describe, and the named-structure itself. Otherwise, it looks on the named-structure symbol for information which might have been left by defstruct; this information would tell it what the symbolic names for the entries in the structure are, and describe knows how to use the names to print out what each field's name and contents is.

describe always returns its argument, in case you want to do something else to it.

Function: inspect x

A window-oriented version of describe. See the window system documentation for details, or try it.

Function: disassemble function

function should be a FEF, or a symbol which is defined as a FEF. This prints out a human-readable version of the macro-instructions in function. The macro-code instruction set is explained in (macro-code).

The grindef function (see (grindef-fun)) may be used to display the definition of a non-compiled function.

Function: room &rest areas

room tells you the amount of physical memory on the machine, the amount of available virtual memory not yet filled with data (that is, the portion of the available virtual memory that has not yet been allocated to any region of any area), and the amount of "wired" physical memory (i.e. memory not available for paging). Then it tells you how much room is left in some areas. For each area it tells you about, it prints out the name of the area, the number of regions which currently make up the area, the current size of the area in kilowords, and the amount of the area which has been allocated, also in kilowords. If the area cannot grow, the percentage which is free is displayed.

(room) tells you about those areas which are in the list which is the value of the variable room. These are the most interesting ones.

(room area1 area2...) tells you about those areas, which can be either the names or the numbers.

(room t) tells you about all the areas.

(room nil) does not tell you about any areas; it only prints the header. This is useful if you just want to know how much memory is on the machine or how much virtual memory is available.

Variable: room

The value of room is a list of area names and/or area numbers, denoting the areas which the function room will describe if given no arguments. Its initial value is:

(working-storage-area macro-compiled-program)

Function: set-memory-size n-words

set-memory-size tells the virtual memory system to use only n-words words of main memory for paging. Of course, n-words may not exceed the amount of main memory on the machine.

48.2 Utility Programs

Function: ed &optional x

ed is the main function for getting into the editor, Zwei. Zwei is not yet documented in this manual, but the commands are very similar to Emacs.

(ed) or (ed nil) simply enters the editor, leaving you in the same buffer as the last time you were in the editor.

(ed t) puts you in a fresh buffer with a generated name (like BUFFER-4).

(ed pathname) edits that file. pathname may be an actual pathname or a string.

(ed 'foo) tries hard to edit the definition of the foo function. It will find a buffer or file containing the source code for foo and position the cursor at the beginning of the code. In general, foo can be any function-spec (see (function-spec)).

(ed 'zwei:reload) reinitializes the editor. It will forget about all existing buffers, so use this only as a last resort.

Function: zwei:save-all-files

This function is useful in emergencies in which you have modified material in Zmacs buffers that needs to be saved, but the editor is partially broken. This function does what the editor's Save All Files command does, but it stays away from redisplay and other advanced facilities so that it might work if other things are broken.

Function: dired &optional pathname

Puts up a window and edits the directory named by pathname, which defaults to the last file opened. While editing a directory you may view, edit, compare, hardcopy, and delete the files it contains. While in the directory editor type the HELP key for further information.

Function: mail &optional who what

Sends mail by putting up a window in which you may compose the mail. who is a symbol or a string which is who to send it to. what is a string which is the initial contents of the mail. If these are unspecified they can be typed in during composition of the mail. Type the END key to send the mail and return from the mail function.

Function: bug &optional who what

Reports a bug. who is the name of the faulty program (a symbol or a string). It defaults to lispm (the Lisp Machine system itself). what is a string which is the initial contents of the mail. bug is like mail but includes information about the system version and what machine you are on in the text of the message. This information is important to the maintainers of the faulty program; it aids them in reproducing the bug and in determining whether it is one which is already being worked on or has already been fixed.

Function: qsend who &optional what

Sends a message to another user. qsend is different from mail because it sends the message immediately; it will appear within seconds on the other user's screen, rather than being saved in her mail file.

who is a string of the form "user7@host"; host is the name of the Lisp Machine or timesharing system the user is currently logged-in to. what is a string which is the message. If what is not specified, you will be prompted to type in a message. Unlike mail and bug, qsend does not put up a window to allow you to edit the message; it just sends it.

[qsend currently does not evaluate its arguments, and is implemented as a macro, but this should probably be changed.]

Function: print-sends

Reprints any messages that have been received. This is useful if you want to see a message again.

Function: print-notifications

Reprints any notifications that have been received. The difference between notifications and sends is that sends come from other users, while notifications are asynchronous messages from the Lisp Machine system itself.

Function: si:print-disk-error-log

Prints information about the half dozen most recent disk errors (since the last cold boot).

Function: peek &optional character

peek is similar to the ITS program of the same name. It displays various information about the system, periodically updating it. Like ITS PEEK, it has several modes, which are entered by typing a single key which is the name of the mode. The initial mode is selected by the argument, character. If no argument is given, peek starts out by explaining what its modes are.

Function: hostat &rest hosts

Asks each of the hosts for its status, and prints the results. If no hosts are specified, all hosts on the Chaosnet are asked. Hosts can be specified either by name or by number.

For each host, a line is output which either says that the host is not responding or gives metering information for the host's network attachments. If a host is not responding, that usually means that it is down or there is no such host at that address. A Lisp Machine can fail to respond if it is looping inside without-interrupts or paging extremely heavily, such that it is simply unable to respond within a reasonable amount of time.

Function: supdup &optional host

host may be a string or symbol, which will be taken as a host name, or a number, which will be taken as a host number. If no host is given, the machine you are logged-in to is assumed. This function opens a connection to the host over the Chaosnet using the Supdup protocol, and allows the Lisp Machine to be used as a terminal for any ITS or TOPS-20 system.

To give commands to supdup, type the NETWORK key followed by one character. Type NETWORK followed by HELP for documentation.

Function: telnet &optional host simulate-imlac

telnet is similar to supdup but uses the Arpanet-standard Telnet protocol, simulating a printing terminal rather than a display terminal.

48.3 "The Lisp Top Level"

These functions constitute the Lisp top level, and its associated functions.

Function: si:lisp-top-level

This is the first function called in the initial Lisp environment. It calls lisp-reinitialize, clears the screen, and calls si:lisp-top-level1.

Function: lisp-reinitialize

This function does a wide variety of things, such as resetting the values of various global constants and initializing the error system.

Function: si:lisp-top-level1

This is the actual top level loop. It reads a form from standard-input, evaluates it, prints the result (with slashification) to standard-output, and repeats indefinitely. If several values are returned by the form all of them will be printed. Also the values of *, +, -, //, ++, **, +++, and *** are maintained (see below).

Special Form: break [tag] [conditional-form]

break is used to enter a breakpoint loop, which is similar to a Lisp top level loop. (break tag) will always enter the loop; (break tag conditional-form) will evaluate conditional-form and only enter the break loop if it returns non-nil. If the break loop is entered, break prints out

;Breakpoint tag; Resume to continue, Abort to quit.

and then enters a loop reading, evaluating, and printing forms. A difference between a break loop and the top level loop is that when reading a form, break checks for the following special cases: If the Abort key is typed, control is returned to the previous break or error-handler, or to top-level if there is none. If the Resume key is typed, break returns nil. If the symbol p is typed, break returns nil. If the list (return form) is typed, break evaluates form and returns the result.

Inside the break loop, the streams standard-output, standard-input, and query-io are bound to be synonymous to terminal-io; terminal-io itself is not rebound. Several other internal system variables are bound, and you can add your own symbols to be bound by pushing elements onto the value of the variable sys:*break-bindings* (see (sys:*break-bindings*-var)).

If tag is omitted, it defaults to nil.

Variable: prin1

The value of this variable is normally nil. If it is non-nil, then the read-eval-print loop will use its value instead of the definition of prin1 to print the values returned by functions. This hook lets you control how things are printed by all read-eval-print loops--the Lisp top level, the break function, and any utility programs that include a read-eval-print loop. It does not affect output from programs that call the prin1 function or any of its relatives such as print and format; if you want to do that, read about customizing the printer, on (customizing-the-printer). If you set prin1 to a new function, remember that the read-eval-print loop expects the function to print the value but not to output a return character or any other delimiters.

Variable: -

While a form is being evaluated by a read-eval-print loop, - is bound to the form itself.

Variable: +

While a form is being evaluated by a read-eval-print loop, + is bound to the previous form that was read by the loop.

Variable: *

While a form is being evaluated by a read-eval-print loop, * is bound to the result printed the last time through the loop. If there were several values printed (because of a multiple-value return), * is bound to the first value.

Variable: //

While a form is being evaluated by a read-eval-print loop, // is bound to a list of the results printed the last time through the loop.

Variable: ++

++ holds the previous value of +, that is, the form evaluated two interactions ago.

Variable: +++

+++ holds the previous value of ++.

Variable: **

** holds the previous value of *, that is, the result of the form evaluated two interactions ago.

Variable: ***

*** holds the previous value of **.

Variable: sys:*break-bindings*

When break is called, it binds some special variables under control of the list which is the value of sys:*break-bindings*. Each element of the list is a list of two elements: a variable and a form which is evaluated to produce the value to bind it to. The bindings happen sequentially. Users may push things on this list (adding to the front of it), but should not replace the list wholesale since several of the variable bindings on this list are essential to the operation of break.

Variable: lisp-crash-list

The value of lisp-crash-list is a list of forms. lisp-reinitialize sequentially evaluates these forms, and then sets lisp-crash-list to nil.

In most cases, the initialization facility should be used rather than lisp-crash-list. Refer to (initialization).

48.4 The Garbage Collector

Function: gc-on

Turns garbage collection on. It is off by default, currently.

Function: gc-off

Turns garbage collection off.

Function: number-gc-on &optional (on-p t)

Turns the special bignum/flonum garbage collector on, or off if on-p is nil. This garbage collector is on by default, since it has negligible overhead and significantly improves the performance of computational programs.

Function: si:full-gc

Performs a complete garbage collection immediately, turning off all other processing.

Function: si:set-scavenger-ws number-of-pages

Specifies the number of pages of memory which real-time garbage collection can use. 400 (256.) is a good value for a 256k machine. If the garbage collector gets very poor paging performance, use of this function may fix it.

Variable: si:%scavenger-ws-enable

If nil, garbage collection can compete with the user for all of the machine's memory. Otherwise, this variable should be the number of a page of physical memory. Pages below that one can be used by garbage collection; other pages cannot. The previous function sets this variable.

48.5 "Logging In"

Logging in tells the Lisp Machine who you are, so that other users can see who is logged in, you can receive messages, and your INIT file can be run. An INIT file is a Lisp program which gets loaded when you log in; it can be used to set up a personalized environment.

When you log out, it should be possible to undo any personalizations you have made so that they do not affect the next user of the machine. Therefore, anything done by an INIT file should be undoable. In order to do this, for every form in the INIT file, a Lisp form to undo its effects should be added to the list which is the value of logout-list. The functions login-setq and login-eval help make this easy; see below.

Variable: user-id

The value of user-id is either the name of the logged in user, as a string, or else an empty string if there is no user logged in. It appears in the who-line.

Variable: logout-list

The value of logout-list is a list of forms which are evaluated when a user logs out.

Function: login name &optional host load-init-file

Sets your name (the variable user-id) to name and logs in a file server on host. host also becomes your default file host. If host requires passwords for logging in you will be asked for a password. When logging in to a TOPS-20 host, typing an asterisk before your password will enable any special capabilities you may be authorized to use. The default value of host depends on which Lisp Machine you use using. It is found from the value of chaos:machine-location-alist, which is a list that has one element for every known individual Lisp Machine. login also runs the :login initialization list (see (login-init-list)).

Unless load-init-file is specified as nil, login will load your init file if it exists. On ITS, your init file is name LISPM on your home directory. On TOPS-20 your init file is LISPM.INIT on your directory.

If anyone is logged into the machine already, login logs him out before logging in name. (See logout.) Init files should be written using the login-setq and login-eval functions below so that logout can undo them. Usually, however, you cold-boot the machine before logging in, to remove any traces of the previous user. login returns t.

Function: logout

First, logout evaluates the forms on logout-list. Then it sets user-id to an empty string and logout-list to nil. Then it runs the :logout initialization list (see (login-init-list)), and returns t.

Special Form: login-setq {variable value}...

login-setq is like setq except that it puts a setq form on logout-list to set the variables to their previous values.

Function: login-eval x

login-eval is used for functions which are "meant to be called" from INIT files, such as zwei:set-comtab-return-undo, which conveniently return a form to undo what they did. login-eval adds the result of the form x to the logout-list.

48.6 Dribble Files

Function: dribble-start filename &optional editor-p

dribble-start opens filename as a "dribble file" (also known as a "wallpaper file"). It rebinds standard-input and standard-output so that all of the terminal interaction is directed to the file as well as the terminal. If editor-p is non-nil, then instead of opening filename on the file computer, dribble-start dribbles into a Zmacs buffer whose name is filename, creating it if it doesn't exist.

Function: dribble-end

This closes the file opened by dribble-start and resets the I/O streams.

48.7 Status and SStatus

The status and sstatus special forms exist for compatibility with Maclisp. Programs that wish to run in both Maclisp and Zetalisp can use status to determine which of these they are running in. Also, (sstatus feature ...) can be used as it is in Maclisp.

Special Form: status

(status features) returns a list of symbols indicating features of the Lisp environment. The complete list of all symbols which may appear on this list, and their meanings, is given in the Maclisp manual. The default list for the Lisp Machine is:

(loop defstruct site sort fasload string newio roman trace grindef grind lispm)

The value of this list will be kept up to date as features are added or removed from the Lisp Machine system. Most important is the symbol lispm, which is the last element of the list; this indicates that the program is executing on the Lisp Machine. site is a symbol indicating where the machine is located, such as :mit or :xerox. The order of this list should not be depended on, and may not be the same as shown above.

This features list is used by the #+ read-time conditionalization syntax. See (sharp-plus).

(status feature symbol) returns t if symbol is on the (status features) list, otherwise nil.

(status nofeature symbol) returns t if symbol is not on the (status features) list, otherwise nil.

(status userid) returns the name of the logged-in user.

(status tabsize) returns the number of spaces per tab stop (always 8). Note that this can actually be changed on a per-window basis, however the status function always returns the default value of 8.

(status opsys) returns the name of the operating system, always the symbol :lispm.

(status site) returns the name of the local machine, e.g. "MIT-LISPM-6". Note that this is not the site as described above, under (status features).

(status status) returns a list of all status operations.

(status sstatus) returns a list of all sstatus operations.

Special Form: sstatus

(sstatus feature symbol) adds symbol to the list of features.

(sstatus nofeature symbol) removes symbol from the list of features.