![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to ch6.n CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [CSRG BSD Unix] / 43BSDReno / share / doc / ps2 / 09.lisp|
Return to ch6.n CVS log | Up to [CSRG BSD Unix] / 43BSDReno / share / doc / ps2 / 09.lisp |
1.1 root 1: .\" Copyright (c) 1980 Regents of the University of California.
2: .\" All rights reserved. The Berkeley software License Agreement
3: .\" specifies the terms and conditions for redistribution.
4: .\"
5: .\" @(#)ch6.n 6.1 (Berkeley) 4/29/86
6: .\"
7: ." $Header: ch6.n,v 1.4 83/07/21 21:08:16 sklower Exp $
8: .Lc System\ Functions 6
9: .pp
10: This chapter describes the functions used to interact
11: with internal components of the Lisp system and operating system.
12: .Lf allocate "'s_type 'x_pages"
13: .Wh
14: s_type is one of the
15: .Fr
16: data types described in \(sc1.3.
17: .Re
18: x_pages.
19: .Se
20: .Fr
21: attempts to allocate x_pages of type s_type.
22: If there aren't x_pages of memory left, no space will be
23: allocated and an error will occur.
24: The storage that is allocated is not given to the caller, instead it is
25: added to the free storage list of s_type.
26: The functions
27: .i segment
28: and
29: .i small-segment
30: allocate blocks of storage and return it to the caller.
31: .Lf argv "'x_argnumb"
32: .Re
33: a symbol whose pname is the x_argnumb\fIth\fP argument (starting at 0)
34: on the command
35: line which invoked the current lisp.
36: .No
37: if x_argnumb is less than zero, a fixnum whose value is the number of arguments
38: on the command line is returned.
39: \fI(argv\ 0)\fP returns the name of the lisp you are running.
40: .Lf baktrace
41: .Re
42: nil
43: .Se
44: the lisp runtime stack is examined and the name of (most) of the functions
45: currently in execution are printed, most active first.
46: .No
47: this will occasionally miss the names of compiled lisp functions due to
48: incomplete information on the stack.
49: If you are tracing compiled code, then \fIbaktrace\fP won't be able
50: to interpret the stack unless
51: .i (sstatus\ translink\ nil)
52: was done.
53: See the function
54: .i showstack
55: for another way of printing the lisp runtime
56: stack.
57: This misspelling is from Maclisp.
58: .Lf chdir "'s_path"
59: .Re
60: t iff the system call succeeds.
61: .Se
62: the current directory set to s_path.
63: Among other things, this will affect the default location
64: where the input/output functions look for and create files.
65: .No
66: \fIchdir\fP follows the standard UNIX conventions, if s_path does not begin
67: with a slash, the default path is changed to the current path with
68: s_path appended.
69: .i Chdir
70: employs tilde-expansion (discussed in Chapter 5).
71: .Lf command-line-args
72: .Re
73: a list of the arguments typed on the command line, either to the
74: lisp interpreter, or saved lisp dump, or application compiled
75: with the autorun option (liszt -r).
76: .Lf deref "'x_addr"
77: .Re
78: The contents of x_addr, when thought of as a longword memory
79: location.
80: .No
81: This may be useful in constructing arguments to C functions
82: out of `dangerous' areas of memory.
83: .Lf dumplisp "s_name"
84: .Re
85: nil
86: .Se
87: the current lisp is dumped to the named file.
88: When s_name is executed, you will be in a lisp in the
89: same state as when the dumplisp was done.
90: .No
91: dumplisp will fail if one tries to
92: write over the current running file.
93: UNIX does not allow you to modify the file you are running.
94: .Lf eval-when "l_time g_exp1 ..."
95: .Se
96: l_time may contain any combination of the symbols
97: .i load ,
98: .i eval ,
99: and
100: .i compile .
101: The effects of load and compile is discussed in \(sc12.3.2.1
102: compiler.
103: If eval is present however, this simply means that the expressions g_exp1
104: and so on are evaluated from left to right.
105: If eval is not present, the forms are not evaluated.
106: .Lf exit "['x_code]"
107: .Re
108: nothing (it never returns).
109: .Se
110: the lisp system dies with exit code x_code or 0 if x_code is not
111: specified.
112: .Lf fake "'x_addr"
113: .Re
114: the lisp object at address x_addr.
115: .No
116: This is intended to be used by people debugging the lisp system.
117: .Lf fork
118: .Re
119: nil to the child process and the process number of the child to
120: the parent.
121: .Se
122: A copy of the current lisp system is made in memory and both
123: lisp systems now begin to run.
124: This function can be used interactively to temporarily
125: save the state of Lisp (as shown below), but you must be careful that only one
126: of the lisp's interacts with the terminal after the fork.
127: The
128: .i wait
129: function is useful for this.
130: .Eb
131: \-> \fI(setq foo 'bar)\fP ;; set a variable
132: bar
133: \-> \fI(cond ((fork)(wait)))\fP ;; duplicate the lisp system and
134: nil ;; make the parent wait
135: \-> \fIfoo\fP ;; check the value of the variable
136: bar
137: \-> \fI(setq foo 'baz)\fP ;; give it a new value
138: baz
139: \-> \fIfoo\fP ;; make sure it worked
140: baz
141: \-> \fI(exit)\fP ;; exit the child
142: (5274 . 0) ;; the \fIwait\fP function returns this
143: \-> \fIfoo\fP ;; we check to make sure parent was
144: bar ;; not modified.
145: .Ee
146: .Lf gc
147: .Re
148: nil
149: .Se
150: this causes a garbage collection.
151: .No
152: The function
153: .i gcafter
154: is not called automatically after this function finishes.
155: Normally the user doesn't have to call
156: .i gc
157: since
158: garbage collection occurs automatically whenever internal free lists
159: are exhausted.
160: .Lf gcafter "s_type"
161: .Wh
162: s_type is one of the
163: .Fr
164: data types listed in \(sc1.3.
165: .No
166: this function is called by the garbage collector
167: after a garbage collection which was caused by running out of
168: data type s_type.
169: This function should determine if more space need be allocated
170: and if so should allocate it.
171: There is a default gcafter function but users who want control over
172: space allocation can define their own -- but note that it must be
173: an nlambda.
174: .Lf getenv "'s_name"
175: .Re
176: a symbol whose pname is the value of s_name in the current
177: UNIX environment.
178: If s_name doesn't exist in the current environment, a symbol with a null pname
179: is returned.
180: .Lf hashtabstat
181: .Re
182: a list of fixnums representing the number of symbols in each bucket of
183: the oblist.
184: .No
185: the oblist is stored a hash table of buckets.
186: Ideally there would be the same number of symbols in each bucket.
187: .Lf help "[sx_arg]"
188: .Se
189: If sx_arg is a symbol then
190: the portion of this manual beginning with the description of sx_arg
191: is printed on the terminal.
192: If sx_arg is a fixnum or the name of one of the appendicies, that
193: chapter or appendix is printed on the terminal.
194: If no argument is provided,
195: .i help
196: prints the options that it recognizes.
197: The program `more' is used to print the manual on the terminal; it will
198: stop after each page and will continue after the space key is pressed.
199: .Lf include "s_filename"
200: .Re
201: nil
202: .Se
203: The given filename is
204: .i load ed
205: into the lisp.
206: .No
207: this is similar to load except the argument is not evaluated.
208: Include means something special to the compiler.
209: .Lf include-if "'g_predicate s_filename"
210: .Re
211: nil
212: .Se
213: This has the same effect as include, but is only actuated
214: if the predicate is non-nil.
215: .Lf includef "'s_filename"
216: .Re
217: nil
218: .Se
219: this is the same as
220: .i include
221: except the argument is evaluated.
222: .Lf includef-if "'g_predicate s_filename"
223: .Re
224: nil
225: .Se
226: This has the same effect as includef, but is only actuated
227: if the predicate is non-nil.
228: .Lf maknum "'g_arg"
229: .Re
230: the address of its argument converted into a fixnum.
231: .Lf monitor "['xs_maxaddr]"
232: .Re
233: t
234: .Se
235: If xs_maxaddr is t then profiling of the entire lisp system is begun.
236: If xs_maxaddr is a fixnum then profiling is done only up to address
237: xs_maxaddr.
238: If xs_maxaddr is not given, then profiling is stopped and the data
239: obtained is written to the file 'mon.out' where it can be analyzed
240: with the UNIX 'prof' program.
241: .No
242: this function only works if the lisp system has been compiled
243: in a special way, otherwise, an error is invoked.
244: .Lf opval "'s_arg ['g_newval]"
245: .Re
246: the value associated with s_arg before the call.
247: .Se
248: If g_newval is specified, the value associated with s_arg is changed to
249: g_newval.
250: .No
251: \fIopval\fP keeps track of storage allocation. If s_arg is one of the data types
252: then \fIopval\fP will return a list of three fixnums representing the number of
253: items of that type in use, the number of pages allocated and the number
254: of items of that type per page.
255: You should never try to change the value \fIopval\fP associates
256: with a data type using
257: \fIopval\fP.
258: .br
259: If s_arg is
260: .i pagelimit
261: then
262: .i opval
263: will return (and set if g_newval is given)
264: the maximum amount of lisp data pages
265: it will allocate.
266: This limit should remain small unless you know your program requires
267: lots of space as this limit will catch programs in infinite loops which
268: gobble up memory.
269: .Lf *process "'st_command ['g_readp ['g_writep]]"
270: .Re
271: either a fixnum if one argument is given, or a list of two ports and a
272: fixnum if two or three arguments are given.
273: .No
274: \fI*process\fP starts another process by passing st_command to the shell
275: (it first tries /bin/csh, then it tries /bin/sh if /bin/csh doesn't exist).
276: If only one argument is given to \fI*process\fP,
277: \fI*process\fP waits for the new
278: process to die and then returns the exit code of the new process.
279: If more two or three arguments are given, \fI*process\fP starts the process
280: and then returns a list which, depending on the value of g_readp
281: and g_writep, may contain i/o ports for communcating with the new
282: process.
283: If g_writep is non-null, then a port will be created which the lisp program
284: can use to send characters to the new process.
285: If g_readp is non-null, then a port will be created which the lisp program
286: can use to read characters from the new process.
287: The value returned by \fI*process\fP is (readport\ writeport\ pid)
288: where readport and writeport are either nil or a port based on the value
289: of g_readp and g_writep. Pid is the process id of the new process.
290: Since it is hard to remember the order of g_readp and g_writep, the
291: functions \fI*process-send\fP and \fI*process-receive\fP were written to
292: perform the common functions.
293: .Lf *process-receive "'st_command"
294: .Re
295: a port which can be read.
296: .Se
297: The command st_command is given to the shell and it is started running in the
298: background.
299: The output of that command is available for reading via the port returned.
300: The input of the command process is set to /dev/null.
301: .Lf *process-send "'st_command"
302: .Re
303: a port which can be written to.
304: .Se
305: The command st_command is given to the shell and it is started runing in the
306: background.
307: The lisp program can provide input for that command
308: by sending characters to the port returned by this function.
309: The output of the command process is set to /dev/null.
310: .Lf process "s_pgrm [s_frompipe s_topipe]"
311: .Re
312: if the optional arguments are
313: not present a fixnum which is the exit code when s_prgm dies.
314: If the optional arguments are present, it returns a fixnum which
315: is the process id of the child.
316: .No
317: This command is obsolete.
318: New programs should use one of the \fI*process\fP commands
319: given above.
320: .Se
321: If s_frompipe and s_topipe are given, they are bound to
322: ports which are pipes which
323: direct characters from
324: .Fr
325: to the new process
326: and to
327: .Fr
328: from the new process respectively.
329: .i Process
330: forks a process named s_prgm and waits for it to die iff there
331: are no pipe arguments given.
332: .Lf ptime
333: .Re
334: a list of two elements.
335: The first is the amount of processor time used
336: by the lisp system so far, and the
337: second is the amount of time used by the garbage collector so far.
338: .No
339: the time is measured in those units used by the
340: .i times (2)
341: system call, usually 60\fIth\fPs of a second.
342: The first number includes the second number.
343: The amount of time used by garbage collection is not recorded
344: until the first call to ptime.
345: This is done to prevent overhead when the user is not interested in
346: garbage collection times.
347: .Lf reset
348: .Se
349: the lisp runtime stack is cleared and the system restarts at the top level
350: by executing a \fI(funcall\ top-level\ nil)\fP.
351: .Lf restorelisp "'s_name"
352: .Se
353: this reads in file s_name (which was created by
354: .i savelisp )
355: and then does a \fI(reset)\fP.
356: .No
357: This is only used on VMS systems where
358: .i dumplisp
359: cannot be used.
360: .Lf retbrk "['x_level]
361: .Wh
362: x_level is a small integer of either sign.
363: .Se
364: The default error handler keeps a notion of the current level
365: of the error caught. If x_level is negative, control is thrown
366: to this default error handler whose level is that many less than
367: the present, or to \fItop-level\fP if there aren't enough.
368: If x_level is non-negative, control is passed to the handler at
369: that level. If x_level is not present, the value -1 is taken by
370: default.
371: .Lf *rset "'g_flag"
372: .Re
373: g_flag
374: .Se
375: If g_flag is non nil then the lisp system will maintain extra information
376: about calls to \fIeval\fP and \fIfuncall\fP.
377: This record keeping slows down the evaluation but this is
378: required for the functions
379: \fIevalhook\fP, \fIfuncallhook\fP, and \fIevalframe\fP to work.
380: To debug compiled lisp code the transfer tables should be unlinked:
381: \fI(sstatus\ translink\ nil)\fP
382: .Lf savelisp "'s_name"
383: .Re
384: t
385: .Se
386: the state of the Lisp system is saved in the file s_name.
387: It can be read in by
388: .i restorelisp .
389: .No
390: This is only used on VMS systems where
391: .i dumplisp
392: cannot be used.
393: .Lf segment "'s_type 'x_size"
394: .Wh
395: s_type is one of the data types given in \(sc1.3
396: .Re
397: a segment of contiguous lispvals of type s_type.
398: .No
399: In reality,
400: .i segment
401: returns a new data cell of type s_type and allocates
402: space for x_size \- 1 more s_type's beyond the one returned.
403: .i Segment
404: always allocates new space and does so in 512 byte chunks.
405: If you ask for 2 fixnums, segment will actually allocate 128 of them
406: thus wasting 126 fixnums.
407: The function
408: .i small-segment
409: is a smarter space allocator and should be used whenever possible.
410: .Lf shell
411: .Re
412: the exit code of the shell when it dies.
413: .Se
414: this forks a new shell and returns when the shell dies.
415: .Lf showstack
416: .Re
417: nil
418: .Se
419: all forms currently in evaluation are printed, beginning with the most recent.
420: For compiled code the most that
421: showstack will show is the function name and it may miss
422: some functions.
423: .Lf signal "'x_signum 's_name"
424: .Re
425: nil if no previous call to signal has been made, or the previously
426: installed s_name.
427: .Se
428: this declares that the function named s_name
429: will handle the signal number x_signum.
430: If s_name is nil, the signal is ignored. Presently only
431: four UNIX signals are caught.
432: They and their numbers are:
433: Interrupt(2), Floating exception(8), Alarm(14), and
434: Hang-up(1).
435: .Lf sizeof "'g_arg"
436: .Re
437: the number of bytes required to store one object of type g_arg, encoded
438: as a fixnum.
439: .Lf small-segment "'s_type 'x_cells"
440: .Wh
441: s_type is one of fixnum, flonum and value.
442: .Re
443: a segment of x_cells data objects of type s_type.
444: .Se
445: This may call
446: .i segment
447: to allocate new space or it may be able to fill the request on a page
448: already allocated.
449: The value returned by
450: .i small-segment
451: is usually stored in the data subpart
452: of an array object.
453: .Lf sstatus "g_type g_val"
454: .Re
455: g_val
456: .Se
457: If g_type is not one of the special sstatus codes described in the
458: next few pages
459: this simply sets g_val as the value of status
460: type g_type in the system status property list.
461: .Lf sstatus\ appendmap "g_val"
462: .Re
463: g_val
464: .Se
465: If g_val is non-null when
466: .i fasl
467: is told to create a load map, it will append to the file name given in
468: the
469: .i fasl
470: command, rather than creating a new map file.
471: The initial value is nil.
472: .Lf sstatus\ automatic-reset "g_val"
473: .Re
474: g_val
475: .Se
476: If g_val is non-null when an error occurs which no one wants to
477: handle, a
478: .i reset
479: will be done instead of entering a primitive internal break loop.
480: The initial value is t.
481: .Lf sstatus\ chainatom "g_val"
482: .Re
483: g_val
484: .Se
485: If g_val is non nil and a
486: .i car
487: or
488: .i cdr
489: of a symbol is done, then nil will be returned instead of an error
490: being signaled.
491: This only affects the interpreter, not the compiler.
492: The initial value is nil.
493: .Lf sstatus\ dumpcore "g_val"
494: .Re
495: g_val
496: .Se
497: If g_val is nil,
498: .Fr
499: tells UNIX that a segmentation violation or
500: bus error should cause a core dump.
501: If g_val is non nil then
502: .Fr
503: will catch those errors and print a message advising the user to reset.
504: .No
505: The initial value for this flag is nil, and only those knowledgeable of
506: the innards of the lisp system should ever set this flag non nil.
507: .Lf sstatus\ dumpmode "x_val"
508: .Re
509: x_val
510: .Se
511: All subsequent
512: .i dumplisp 's
513: will be done in mode x_val.
514: x_val may be either 413 or 410 (decimal).
515: .No
516: the advantage of mode 413 is that the dumped Lisp can be demand paged in when
517: first started, which will make it start faster and disrupt other users less.
518: The initial value is 413.
519: .Lf sstatus\ evalhook "g_val"
520: .Re
521: g_val
522: .Se
523: When g_val is non nil, this enables the
524: evalhook and funcallhook traps in the evaluator.
525: See \(sc14.4 for more details.
526: .Lf sstatus\ feature "g_val"
527: .Re
528: g_val
529: .Se
530: g_val is added to the \fI(status\ features)\fP list,
531: .Lf sstatus\ gcstrings "g_val"
532: .Re
533: g_val
534: .Se
535: if g_val is non-null, and if string garbage collection was enabled when
536: the lisp system was compiled, string space will be garbage collected.
537: .No
538: the default value for this is nil since in most applications garbage
539: collecting strings is a waste of time.
540: .Lf sstatus\ ignoreeof "g_val"
541: .Re
542: g_val
543: .Se
544: If g_val is non-null when
545: an end of file (CNTL-D on UNIX) is typed to the standard top-level interpreter,
546: it will be ignored rather then cause the lisp system to exit.
547: If the the standard input is a file or pipe then this has no effect,
548: an EOF will always cause lisp to exit.
549: The initial value is nil.
550: .Lf sstatus\ nofeature "g_val"
551: .Re
552: g_val
553: .Se
554: g_val is removed from the status features list if it was present.
555: .Lf sstatus\ translink "g_val"
556: .Re
557: g_val
558: .Se
559: If g_val is nil then all transfer tables are cleared and further calls
560: through the transfer table will not cause the fast links to be set up.
561: If g_val is the symbol
562: .i on
563: then all possible transfer table entries will be linked and the flag
564: will be set to cause fast links to be set up dynamically.
565: Otherwise all that is done is to set the flag to cause fast links
566: to be set up dynamically.
567: The initial value is nil.
568: .No
569: For a discussion of transfer tables, see \(sc12.8.
570: .Lf sstatus\ uctolc "g_val"
571: .Re
572: g_val
573: .Se
574: If g_val is not nil then all unescaped capital letters
575: in symbols read by the reader will be converted to lower case.
576: .No
577: This allows
578: .Fr
579: to be compatible with single case lisp
580: systems (e.g. Maclisp, Interlisp and UCILisp).
581: .Lf status "g_code"
582: .Re
583: the value associated with the status code g_code
584: if g_code is not one of the special cases given below
585: .Lf status\ ctime
586: .Re
587: a symbol whose print name is the current time and date.
588: .Ex
589: \fI(status ctime)\fP = |Sun Jun 29 16:51:26 1980|
590: .No
591: This has been made obsolete by \fItime-string\fP, described below.
592: .Lf status\ feature "g_val"
593: .Re
594: t iff g_val is in the status features list.
595: .Lf status\ features
596: .Re
597: the value of the features code, which is a list of features which
598: are present in this system.
599: You add to this list with \fI(sstatus\ feature\ 'g_val)\fP
600: and test if feature g_feat is present with \fI(status\ feature\ 'g_feat)\fP.
601: .Lf status\ isatty
602: .Re
603: t iff the standard input is a terminal.
604: .Lf status\ localtime
605: .Re
606: a list of fixnums representing the current time.
607: .Ex
608: \fI(status localtime)\fP = (3 51 13 31 6 81 5 211 1)
609: .br
610: means 3\fIrd\fP second, 51\fIst\fP minute, 13\fIth\fP hour (1 p.m),
611: 31\fIst\fP day, month 6 (0\ =\ January), year 81 (0\ =\ 1900),
612: day of the week 5 (0\ =\ Sunday), 211\fIth\fP day of the year
613: and daylight savings time is in effect.
614: .Lf status\ syntax "s_char"
615: .No
616: This function should not be used.
617: See the description of
618: .i getsyntax
619: (in Chapter 7) for a replacement.
620: .Lf status\ undeffunc
621: .Re
622: a list of all functions which transfer table entries point to but which
623: are not defined at this point.
624: .No
625: Some of the undefined functions listed could be arrays which have yet
626: to be created.
627: .Lf status\ version
628: .Re
629: a string which is the current lisp version name.
630: .Ex
631: \fI(status version)\fP = "Franz Lisp, Opus 38.61"
632: .Lf syscall "'x_index ['xst_arg1 ...]"
633: .Re
634: the result of issuing the UNIX system call number x_index with arguments
635: xst_arg\fIi\fP.
636: .No
637: The UNIX system calls are described in section 2 of the
638: UNIX Programmer's manual.
639: If xst_arg\fIi\fP is a fixnum, then
640: its value is passed as an argument, if it is a symbol then
641: its pname is passed and finally if it is a string then the string itself
642: is passed as an argument.
643: Some useful syscalls are:
644: .br
645: \fI(syscall\ 20)\fP returns process id.
646: .br
647: \fI(syscall\ 13)\fP returns the number of seconds since Jan 1, 1970.
648: .br
649: \fI(syscall\ 10\ 'foo)\fP will unlink (delete) the file foo.
650: .Lf sys:access "'st_filename 'x_mode"
651: .Lx sys:chmod "'st_filename 'x_mode"
652: .Lx sys:gethostname
653: .Lx sys:getpid
654: .Lx sys:getpwnam 'st_username
655: .Lx sys:link "'st_oldfilename 'st_newfilename"
656: .Lx sys:time
657: .Lx sys:unlink 'st_filename
658: .No
659: We have been warned that the actual system call numbers may vary
660: among different UNIX systems. Users concerned about portability
661: may wish to use this group of functions.
662: Another advantage is that tilde-expansion is performed on
663: all filename arguments.
664: These functions do what is described
665: in the system call section of your UNIX manual.
666: .br
667: .sp
668: .i sys:getpwnam
669: returns a vector of four entries from the password file, being
670: the user name, user id, group id, and home directory.
671: .Lf time-string "['x_seconds]"
672: .Re
673: an ascii string giving the time and date which was
674: x_seconds after UNIX's idea of creation
675: (Midnight, Jan 1, 1970 GMT). If no argument is given,
676: time-string returns the current date.
677: This supplants \fI(status ctime)\fP, and may be used
678: to make the results of \fIfilestat\fP more intelligible.
679: .Lf top-level
680: .Re
681: nothing (it never returns)
682: .No
683: This function is the top-level read-eval-print loop.
684: It never returns any value.
685: Its main utility is that if you redefine it, and do a (reset) then the
686: redefined (top-level) is then invoked.
687: The default top-level for Franz, allow one to specify
688: his own printer or reader, by binding the symbols \fBtop-level-printer\fP
689: and \fBtop-level-reader\fP.
690: One can let the default top-level do most of the drudgery in catching
691: .i reset 's,
692: and reading in .lisprc files,
693: by binding the symbol \fBuser-top-level\fP, to a routine that
694: concerns itself only with the read-eval-print loop.
695: .Lf wait
696: .Re
697: a dotted pair \fI(processid . status)\fP when the
698: next child process dies.
This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.