;;; -*- Mode:gate; Fonts:(HL12 HL12I HL12B CPTFONTB HL12BI HL12B HL12I ) -*- =Node: 4Documentation* =Text: 3DOCUMENTATION documentation* 1name* 1doc-type* Returns the documentation string of 1name* in the role 1doc-type*. 1doc-type* should be a symbol, but only its print-name matters. 2function* as 1doc-type* requests the documentation of 1name* as a function, 2variable* as 1doc-type* requests the documentation of 1name* as a variable, and so on. When 1doc-type* is 2function*, 1name* can be any function spec, and the documentation string of its function definition is returned. Otherwise, 1name* must be a symbol, and 1doc-type* may be anything. However, only these values of 1doc-type* are standardly used: 2variable* Documentation of 1name* as a special variable. Such documentation is recorded automatically by 2defvar*, 2defconst*, 2defconstant*, 2defparameter* (4(EVAL-1)Defining Global Variables*). 2type* Documentation of 1name* as a type for 2typep*. Recorded automatically when a documentation string is given in a 2deftype* form (4(PRIMOBJTYPE-1)User-Defined Type Specifiers*). 2structure* Documentation of 1name* as a 2defstruct* type. Recorded automatically by a 2defstruct* for 1name* (4(DEFSTRUCT-0)Defstruct*). 2setf* Documentation on what it means to 2setf* a form that starts with 1name*. Recorded when there is a documentation string in a 2defsetf* of 1name* (4(MACROS-3)Extending setf and locf*). 2flavor* Documentation of the flavor named 1name*. Put on by the 2:documentation* option in a 2defflavor* for 1name* (4(FLAVOR-2)Flavor Functions*). 2resource* Documentation of the resource named 1name*. Put on when there is a documentation string in a 2defresource* of 1name* (4(MANLISTSTR-3)Defining Resources*). 2signal* Documentation for 1name* as a signal name. Put on when there is a documentation string in a 2defsignal* or 2defsignal-explicit* for 1name* (4(DEBUGGING-2)Creating Condition Instances*). Documentation strings for any 1doc-type* can be added to 1name* by doing 2(setf (documentation* 1name2 *doc-type2) *string2)**. The command 2Control-Shift-D* in Zmacs and the rubout handler, used within a call to a function, prints the documentation of that function. 2Control-Shift-V*, within a symbol, prints the documentation of that symbol as a variable. =Node: 4Hardcopy* =Text: 3HARDCOPY* The hardcopy functions allow you to specify the printer to use on each call. The default is set up by the site files for your site, but can be overridden for a particular machine in the 2LMLOCS* file or by a user in his INIT file. Any kind of printer can be used, no matter how it is actually driven, if it is hooked into the software properly as described below. A 1printer-type* is a keyword that has appropriate properties; a 1printer* is either a printer-type or a list starting with one. The rest of the list can specify 1which* printer of that type you want to use (perhaps with a host name or filename). The printer types defined by the system are: This printer type is used by itself as a printer, and refers to the Dover at MIT. 2:xgp* This printer type indicates a printer that is accessed by writing spool files in MIT XGP format. A printer would be specified as a list, 2(:xgp 1filename*)*, specifying where to write the spool file. 2:press-file* This printer type is used in a list together with a file name, as in 2(:press-file* 2"OZ:FOO.PRESS")*. Something is ``printed'' on such a printer by being converted to a press file and written under that name. 3hardcopy-file* 1filename* &rest 1options* Print the file 1filename* in hard copy on the specified printer or the default printer. 1options* is a list of keyword argument names and values. There are only two keywords that are always meaningful: 2:format* and 2:printer*. Everything else is up to the individual printer to interpret. The list here is only a paradigm or suggestion. 2:printer* The value is the printer to use. The default is the value of 2si:*default-printer**. 2:format* The value is a keyword that specifies the format of file to be parsed. The standard possibilities are 2:text* (an ordinary file of text), 2:xgp* (a file of the sort once used by the XGP at MIT), 2:press* (a Xerox-style press file) and 2:suds-plot* (a file produced by the Stanford drawing program). However, each kind of printer may define its own format keywords. 2:font* 2:font-list* The value of 1font* is the name of a font to print the file in (a string). Alternatively, you can give 2:font-list* and specify a list of such font names, for use if the file contains font-change commands. The interpretation of a font name is dependent on the printer being used. There is no necessary relation to Lisp machine display fonts. However, printers are encouraged to use, by default, fonts that are similar in appearance to the Lisp machine fonts listed in the file's attribute list, if it is a text file. 2:heading-font* The value is the name of the font for use in page headers, if there are any. 2:vsp* The value is the extra spacing to use between lines, in over and beyond the height of the fonts. 2:page-headings* If the value is non-2nil*, a heading is added to each page. 2:copies* The value is the number of copies to print. 2:spool* If the printer provides optional spooling, this argument says whether to spool (default is 2nil*). Some printers may intrinsically always spool; others may have no way to spool. 3set-printer-default-option* 1printer-type* 1option* 1value* Sets a default for 1option* for printers of type 1printer-type*. Any use of the hardcopy functions with a printer of that type and no value specified for 1option* will use the value 1value*. For example, 3(set-printer-default-option :dover :spool t)* causes output to Dover printers to be spooled unless the 2:spool* option is explicitly specified with value 2nil*. Currently defaultable options are 2:font*, 2:font-list*, 2:heading-font*, 2:page-headings*, 2:vsp*, 2:copies*, and 2:spool*. 3hardcopy-stream* 1stream* &rest 1options* Like 2hardcopy-file* but uses the text read from 1stream* rather than opening a file. The 2:format* option is not allowed (since implementing it requires the ability to open the file with unusual 2open* options). 3hardcopy-bit-array* 1array* 1left* 1top* 1right* 1bottom* &rest 1options* Print all or part of the bit-array 1array* on the specified or default printer. 1options* is a list of keyword argument names and values; the only standard option is 2:printer*, which specifies the printer to use. The default printer is 2si:*default-bit-array-printer**, or, if that is 2nil*, 2si:*default-printer*. 1left*, 1top*, 1right* and 1bottom* specify the subrectangle of the array to be printed. All four numbers measure from the top left corner (which is element 0, 0). 3hardcopy-status* &optional 1printer* 1(stream* 3*standard-output*1)** Prints the status of 1printer*, or the default printer. This should include if possible such things as whether the printer has paper and what is in the queue. 3si:*default-printer** 1Variable* This is the default printer. It is set from the 2:default-printer* site option. 3si:*default-bit-array-printer** 1Variable* If non-2nil*, this is the default printer for printing bit arrays, overriding 2si:*default-printer**. A separate default is provided for bit arrays since some printers that can print files cannot print bit arrays. This variable is set initially from the 2:default-bit-array-printer* site option. Defining a printer type: A printer type is any keyword that has suitable functions on the appropriate properties. To be used with the function 2hardcopy-file*, the printer type must have a 2si:print-file* property. To be used with 2hardcopy-stream*, the printer type must have a 2si:print-stream* property. 2hardcopy-bit-array* uses the 2si:print-bit-array* property. 2hardcopy-status* uses the 2si:print-status* property. (The hardcopy functions' names are not themselves used simply to avoid using a symbol in the global package as a property name of a symbol that might be in the global package as well). Each property, to be used, should be a function whose first argument will be the printer and whose remaining arguments will fit the same pattern as those of the hardcopy function the user called. (They will not necessarily be the same arguments, as some additional keywords may be added to the list of keyword arguments; but they will fit the same description.) For example, 3(hardcopy-file "foo" :printer '(:press-file "bar.press"))* results in the execution of 3(funcall (get :press-file 'si:print-file)* 3 '(:press-file "bar.press")* 3 "foo" :printer '(:press-file "bar.press"))* A printer type need not support operations that make no sense on it. For example, there is no 2si:print-status* property on 2:press-file*. =Node: 4Metering* =Text: 3METERING* The metering system is a way of finding out what parts of your program use up the most time. When you run your program with metering, every function call and return is recorded, together with the time at which it took place. Page faults are also recorded. Afterward, the metering system analyzes the records and tells you how much time was spent executing withain each function. Because the records are stored in the disk partition called 2METR*, there is room for a lot of data. Before you meter a program, you must enable metering in some or all stack groups. 2meter:enable* is used for this. Then you evaluate one or more forms with metering, perhaps by using 2meter:test* or 2meter:run*. Finally, you use 2meter:analyze* to summarize and print the metering data. There are two parameters that control whether metering data are recorded. First of all, the variable 2sys:%meter-microcode-enables* contains bits that enable recording of various kinds of events. Secondly, each stack group has a flag that controls whether events are recorded while running in that stack group. 3sys:%meter-microcode-enables* 1Variable* Enables recording of metering data. Each bit controls recording of one kind of event. 21* This bit enables recording of page faults. 22* This bit enables recording of consing. 24* This bit enables recording of function entry and exit. 28* This bit enables recording of stack group switching. The value is normally zero, which turns off all recording. These are the functions used to control which stack groups do metering: 3meter:enable* &rest 1things* Enables metering in the stack groups specified by 1things*. Each thing in 1things* may be a stack group, a process (which specifies the process's stack group), or a window (which specifies the window's process's stack group). 2t* is also allowed. It enables metering in all stack groups. 3meter:disable* &rest 1things* Disables metering in the stack groups specified by 1things*. The arguments allowed are the same as for 2meter:enable*. 2(meter:disable t)* turns off 2(meter:enable t)*, but does not disable stack groups enabled individually. 2(meter:disable)* disables all stack groups no matter how you specified to enable them. 3meter:metered-objects* 1Variable* This is a list of all the 1things* you have enabled with 2meter:enable* and not disabled. These are the functions to evaluate forms with metering: 3meter:run* 1forms* Clears out the metering data and evaluates the 1forms* with 2sys:%meter-microcode-enables* bound to 14 octal (record function entry and exit, and stack group switching). Any of the evaluation that takes place in enabled stack groups will record metering data. 3meter:test* 1form* 1(enables* 3#o141)** Clears out the metering data, enables metering for the current stack group only, and evaluates 1form* with 2sys:%meter-microcode-enables* bound to 1enables*. This is how you print the results: 3meter:analyze* &key 1analyzer* 1stream* 1file* 1buffer* 1return* 1info* &allow-other-keys Analyzes the data recorded by metering. 1analyzer* is a keyword specifies a kind of analysis. 2:tree* is the default. Another useful alternative is 2:list-events*. Particular analyzers handle other keyword arguments in addition to those listed above. The output is printed on 1stream*, written to a file named 1file*, or put in an editor buffer named 1buffer* (at most one of these three arguments should be specified). The default is to print on 2*standard-output**. Analyzing the metering data involves creating a large intermediate data base. Normally this is created afresh each time 2meter:analyze* is called. If you specify a non-2nil* value for 1return*, the intermediate data structure is returned by 2meter:analyze*, and can be passed in on another call as the 1info* argument. This can save time. But you can only do this if you use the same 1analyzer* each time, as different analyzers use different termporary data structures. The default analyzer 2:tree* prints out the amount of run time and real time spent executing each function that was called. The real time includes time spend waiting and time spent writing metering data to disk; for computational tasks, the latter makes the real time less useful than the run time. 2:tree* handles these additional keyword arguments to 2meter:analyze*: 2:find-callers* The argument for this keyword is a function spec or a list of function specs. A list of who called the specified functions, and how often, is printed instead of the usual output. 2:stack-group* The argument is a stack group or a list of them; only the activities in those stack groups are printed. 2:sort-function* The argument is the name of a suitable sorting function that is used to sort the items for the various functions that were called. Sorting functions provided include 2meter:max-page-faults*, 2meter:max-calls*, 2meter:max-run-time* (the default), 2meter:max-real-time*, and 2meter:max-run-time-per-call*. 2:summarize* The argument is a function spec or a list of function specs; only those functions' statistics are printed. 2:inclusive* If this is non-2nil*, the times for each function include the time spent in executing subroutines called from the function. Note: if a function is called recursively, the time spent in the inner call(s) is counted twice (or more). The analyzer 2:list-events* prints out one line about each event recorded. The line contains the run time and real time (in microseconds), the running count of page faults, the stack group name, the function that was running, the stack depth, the type of event, and a piece of data. For example: 3 0 0 0 ZMACS-WINDOWS METER:TEST 202 CALL SI:EVAL* 3 115 43 0 ZMACS-WINDOWS METER:TEST 202 RET SI:EVAL* 3 180 87 0 ZMACS-WINDOWS METER:TEST 202 RET CATCH* 3real run pf stack-group function stack event data* 3time time level type* 2:list-events* is often useful with recording of page faults (2sys:%meter-microcode-enables* set to 1). 3meter:reset* Clears out all metering data. Because metering records pointers to Lisp objects in a disk partition which is not part of the Lisp address space, garbage collection is inhibited (by arresting the gc process) when you turn on metering. 3meter:resume-gc-process* Allows garbage collection to continue (if it is already turned on) by unarresting it. =Node: 4Poking Around in the Lisp World* =Text: 3POKING AROUND IN THE LISP WORLD who-calls* 1x* &optional 1package* 1(inheritors* 3t1)** 1(inherited* 3t1)** 1x* must be a symbol or a list of symbols. 2who-calls* tries to find all of the functions in the Lisp world that call 1x* as a function, use 1x* as a variable, or use 1x* as a constant. (Constants which are lists containing 1x* are not found.) It tries to find all of the functions by searching all of the function cells of all of the symbols in 1package* and packages that inherit from 1package* (unless 1inheritors* is 2nil*) and packages 1package* inherits from (unless 1inherited* is 2nil*). 1package* defaults to the 2global* package, which means that all normal packages are checked. If 2who-calls* encounters an interpreted function definition, it simply tells you if 1x* appears anywhere in the interpreted code. 2who-calls* is smarter about compiled code, since it has been nicely predigested by the compiler. Macros expanded in the compilation of the code can be found because they are recorded in the caller's debugging info alist, even though they are not actually referred to by the compiled code. If 1x* is a list of symbols, 2who-calls* does them all simultaneously, which is faster than doing them one at a time. 2who-uses* is an obsolete name for 2who-calls*. The editor has a command,2 Meta-X List Callers*, which is similar to 2who-calls*. The symbol 2:unbound-function* is treated specially by 2who-calls*. 2(who-calls* 2:unbound-function)* searches all the compiled code for any calls through a symbol that 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. 2who-calls* prints one line of information for each caller it finds. It also returns a list of the names of all the callers. 3what-files-call* 1x* &optional 1package* 1(inheritors* 3t1)** 1(inherited* 3t1)** Similar to 2who-calls* but returns a list of the pathnames of all the files that contain functions that 2who-calls* would have printed out. This is useful if you need to recompile and/or edit all of those files. 3apropos* 1substring* &optional 1package* &key 1(inheritors* 3t1)** 1inherited* 1dont-print* 1predicate* 1boundp* 1fboundp* 2(apropos 1substring*)* tries to find all symbols whose print-names contain 1substring* 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. If 1predicate* is non-2nil*, it should be a function; only symbols on which the function returns non-2nil* are counted. In addition, 1fboundp* non-2nil* means only symbols with function definitions are considered, and 1boundp* non-2nil* means that only symbols with values are considered. 2apropos* looks for symbols on 1package*, and all packages that use 1package* (unless 1inheritors* is 2nil*). If 1inherited* is non-2nil*, all packages used by 1package* are searched as well. 1package* can be a package or a symbol or string naming a package. It can also be a list of packages, symbols and strings; all of the packages thus specified are searched. 1package* defaults to a list of all packages except invisible ones. 2apropos* returns a list of all the symbols it finds. If 1dont-print* is non-2nil*, that is all it does. 3sub-apropos* 1substring* 1starting-list* &key 1predicate* 1dont-print* Finds all symbols in 1starting-list* whose names contain 1substring*, and that satisfy 1predicate*. If 1predicate* is 2nil*, the substring is the only condition. The symbols are printed if 1dont-print* is 2nil*. A list of the symbols found is returned, in any case. This function is most useful when applied to the value of 3**, after 2apropos* has returned a long list. 3where-is* 1pname* &optional 1package* Prints the names of all packages that contain a symbol with the print-name 1pname*. If 1pname* is a string it gets upper-cased. The package 1package* and all packages that inherit from it are searched. 1package* can be a package or the name of a package, or a list of packages and names. It defaults to a list of all packages except invisible ones. 2where-is* returns a list of all the symbols it finds. 3describe* 1x* 2describe* tries to tell you all of the interesting information about any object 1x* (except for array contents). 2describe* knows about arrays, symbols, floats, packages, stack groups, closures, and FEFs, and prints out the attributes of each in human-readable form. Sometimes objects found inside 1x* are described also; such recursive descriptions are indented appropriately. For instance, 2describe* of a symbol also describes the symbol's value, its definition, and each of its properties. 2describe* of a float (full-size or short) shows you its internal representation in a way that is useful for tracking down roundoff errors and the like. If 1x* is a named-structure, 2describe* invokes the 2:describe* operation to print the description, if that is supported. To understand this, you should read the section on named structures (see 4(DEFSTRUCT-2)Named Structures*). If the 2:describe* operation is not supported, 2describe* looks on the named-structure symbol for information that might have been left by 2defstruct*; this information would tell it what the symbolic names for the entries in the structure are, and 2describe* knows how to use the names to print out what each field's name and contents is. 2describe* of an instance always invokes the 2:describe* operation. All flavors support it, since 2si:vanilla-flavor* defines a method for it. 2describe* always returns its argument, in case you want to do something else to it. 3inspect* 1x* A window-oriented version of 2describe*. See the window system documentation for details, or try it and type 2Help*. 3disassemble* 1function* Prints out a human-readable version of the macro-instructions in 1function*. 1function* should be a FEF, or a function spec whose definition is a FEF. The macro-code instruction set is explained in 4(ASSEMBLER-0)How to Read Assembly Language*. The 2grindef* function (see 4(READPRINT-3)Pretty-Printing Output Functions*) may be used to display the definition of a non-compiled function. 3room* &rest 1areas* Prints a summary of memory usage. The first line of output 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). Following lines tell 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 that currently make up the area, the current size of the area in kilowords, and the amount of the area that has been allocated, also in kilowords. If the area cannot grow, the percentage that is free is displayed. 2(room)* tells you about those areas that are in the list that is the value of the variable 2room*. These are the most interesting ones. 2(room 1area1* 1area2*...)* tells you about those areas, which can be either the names or the numbers. 2(room t)* tells you about all the areas. 2(room nil)* does not tell you about any areas; it only prints the first line of output. 3room* 1Variable* The value of 2room* is a list of area names and/or area numbers, denoting the areas that the function 2room* should describe if given no arguments. Its initial value is: 3(working-storage-area macro-compiled-program)