![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to ch5.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 ch5.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: .\" @(#)ch5.n 6.1 (Berkeley) 4/29/86
6: .\"
7: ." $Header: ch5.n,v 1.3 83/07/23 12:40:05 layer Exp $
8: .Lc Input/Output 5
9: .pp
10: The following functions are used to read from and write to external devices
11: (e.g. files)
12: and programs (through pipes).
13: All I/O goes through the lisp data type called the port.
14: A port may be open for either reading or writing, but usually not both
15: simultaneously (see
16: .i fileopen
17: ).
18: There are only a limited number of ports (20) and they will not be reclaimed
19: unless they are
20: .i close d.
21: All ports are reclaimed by a
22: .i resetio
23: call,
24: but this drastic step won't be necessary if the program closes
25: what it uses.
26: .pp
27: If a port argument is not supplied to a function which requires one,
28: or if a bad port argument (such as nil) is given,
29: then
30: .Fr
31: will use the default port according to this scheme:
32: If input is being done then the default port is the value
33: of the symbol
34: .b piport
35: and if output is being done then the default port is the value
36: of the symbol
37: .b poport .
38: Furthermore,
39: if the value of piport or poport is not a valid port,
40: then the standard input or standard output will be used, respectively.
41: .pp
42: The standard input and standard output are usually the keyboard and
43: terminal display unless your job is running in the background and its
44: input or output is connected to a pipe.
45: All output which goes to the standard output will also go to the
46: port
47: .b ptport
48: if it is a valid port.
49: Output destined for the standard output will not reach
50: the standard output if the symbol
51: .b ^w
52: is non nil (although it will still go to
53: .b ptport
54: if
55: .b ptport
56: is a valid port).
57: .pp
58: Some of the functions listed below reference files directly.
59: .Fr
60: has borrowed a convenient shorthand notation from
61: .i /bin/csh ,
62: concerning naming files.
63: If a file name begins with ~ (tilde),
64: and the symbol
65: .b tilde-expansion
66:
67: is bound to something other than nil,
68: then
69: .Fr
70: expands the file name.
71: It takes the string of characters between the leading tilde, and
72: the first slash as a user-name.
73: Then, that initial segment of the filename is replaced by the home
74: directory of the user. The null username is taken to be the current
75: user.
76: .pp
77: .Fr
78: keeps a cache of user home directory information, to minimize
79: searching the password file.
80: Tilde-expansion is performed in the following functions:
81: \fIcfasl, chdir, fasl, ffasl, fileopen, infile, load, outfile,
82: probef, sys:access, sys:unlink\fP.
83: .Lf cfasl "'st_file 'st_entry 'st_funcname ['st_disc ['st_library]]"
84: .Re
85: t
86: .Se
87: This is used to load in a foreign function (see \(sc8.4).
88: The object file st_file is loaded into the lisp system.
89: St_entry should be an entry point in the file just loaded.
90: The function binding of the symbol s_funcname will be set to point
91: to st_entry, so that when the lisp function s_funcname is called,
92: st_entry will be run.
93: st_disc is the discipline to be given to s_funcname.
94: st_disc defaults to "subroutine" if it is not given or if it is given as nil.
95: If st_library is non-null, then after st_file is loaded, the libraries
96: given in st_library will be searched to resolve external references.
97: The form of st_library should be something like "-lm".
98: The C library (" -lc " ) is always searched so when loading in a C
99: file you probably won't need to specify a library.
100: For Fortran files, you should specify "-lF77" and if you are doing
101: any I/O, the library entry should be "-lI77 -lF77".
102: For Pascal files "-lpc" is required.
103: .No
104: This function may be used to load the output of the assembler, C compiler,
105: Fortran compiler, and Pascal compiler but NOT the lisp compiler (use
106: .i fasl
107: for that).
108: If a file has more than one entry point, then use
109: .i getaddress
110: to locate and setup other foreign functions.
111: .br
112: It is an error to load in a file which has a global entry point of the same
113: name as a global entry point in the running lisp.
114: As soon as you load in a file with
115: .i cfasl ,
116: its global entry points become part of the
117: lisp's entry points.
118: Thus you cannot
119: .i cfasl
120: in the same file twice unless you
121: use
122: .i removeaddress
123: to change certain global entry points to local entry points.
124: .Lf close "'p_port"
125: .Re
126: t
127: .Se
128: the specified port is drained and closed, releasing the port.
129: .No
130: The standard defaults are not used in this case since you probably never
131: want to close the standard output or standard input.
132: .Lf cprintf "'st_format 'xfst_val ['p_port]"
133: .Re
134: xfst_val
135: .Se
136: The UNIX formatted output function printf is called with arguments st_format
137: and xfst_val.
138: If xfst_val is a symbol then its print name is passed to printf.
139: The format string may contain characters which are just printed literally
140: and it may contain special formatting commands preceded by a percent
141: sign.
142: The complete set of formatting characters is described in the UNIX manual.
143: Some useful ones are %d for printing a fixnum in decimal, %f or %e for printing
144: a flonum, and %s for printing a character string (or print name of a symbol).
145: .Ex
146: \fI(cprintf "Pi equals %f" 3.14159)\fP prints `Pi equals 3.14159'
147: .Lf drain "['p_port]"
148: .Re
149: nil
150: .Se
151: If this is an output port then
152: the characters in the output buffer are all sent to the device.
153: If this is an input port then all pending characters are flushed.
154: The default port for this function is the default output port.
155: .Lf ex "[s_filename]"
156: .Lx vi "[s_filename]"
157: .Lx exl "[s_filename]"
158: .Lx vil "[s_filename]"
159: .Re
160: nil
161: .Se
162: The lisp system starts up an editor on the file named as the argument.
163: It will try appending .l to the file if it can't find it.
164: The functions \fIexl\fP and \fIvil\fP will load the file after
165: you finish editing it. These functions will also remember the name
166: of the file so that on subsequent invocations, you don't need to
167: provide the argument.
168: .No
169: These functions do not evaluate their argument.
170: .Lf fasl "'st_name ['st_mapf ['g_warn]]"
171: .Wh
172: st_mapf and g_warn default to nil.
173: .Re
174: t if the function succeeded, nil otherwise.
175: .Se
176: this function is designed to load in an object file generated by
177: the lisp compiler Liszt.
178: File names for object files usually end in `.o', so
179: .i fasl
180: will append `.o' to st_name (if it is not already present).
181: If st_mapf is non nil, then it is the name of the map file to
182: create.
183: .i Fasl
184: writes in the map file the names and addresses of the functions
185: it loads and defines.
186: Normally the map file is created (i.e. truncated if it
187: exists), but if \fI(sstatus\ appendmap\ t)\fP is done then the map file
188: will be appended.
189: If g_warn is non nil and if a function is loaded from the file which
190: is already defined, then a warning message will be printed.
191: .No
192: .i fasl
193: only looks in the current directory for the file to load.
194: The function
195: .i load
196: looks through a user-supplied search path and will call
197: .i fasl
198: if it finds a file with the same root name and a `.o' extension.
199: In most cases the user
200: would be better off using the function
201: .i load
202: rather than calling
203: .i fasl
204: directly.
205: .Lf ffasl "'st_file 'st_entry 'st_funcname ['st_discipline ['st_library]]"
206: .Re
207: the binary object created.
208: .Se
209: the Fortran object file st_file is loaded into the lisp system.
210: St_entry should be an entry point in the file just loaded.
211: A binary object will be created and its entry field will be set to point
212: to st_entry.
213: The discipline field of the binary will be set to st_discipline or
214: "subroutine" by default.
215: If st_library is present and non-null, then after st_file is loaded, the libraries
216: given in st_library will be searched to resolve external references.
217: The form of st_library should be something like "-lS -ltermcap".
218: In any case, the standard Fortran libraries will be
219: searched also to resolve external references.
220: .No
221: in F77 on Unix, the entry point for the fortran function foo
222: is named `_foo_'.
223: .Lf filepos "'p_port ['x_pos]"
224: .Re
225: the current position in the file if x_pos is not
226: given or else x_pos if x_pos is given.
227: .Se
228: If x_pos is given, the next byte to be read or written to the
229: port will be at
230: position x_pos.
231: .Lf filestat 'st_filename
232: .Re
233: a vector containing various numbers which the UNIX operating
234: system assigns to files. if the file doesn't exist, an error is
235: invoked. Use \fIprobef\fP to determine if the file exists.
236: .No
237: The individual entries can be accesed by mnemonic functions
238: of the form filestat:\fIfield\fP, where field may be any of
239: atime, ctime, dev, gid, ino, mode,mtime, nlink, rdev, size,
240: type, uid. See the UNIX programmers manual for a more detailed
241: description of these quantities.
242: .Lf flatc "'g_form ['x_max]"
243: .Re
244: the number of characters required to print g_form using \fIpatom\fP.
245: If x_max is given and if \fIflatc\fP determines that it will return a value
246: greater than x_max, then it gives up and returns the current value it
247: has computed.
248: This is useful if you just want to see if an expression is larger than
249: a certain size.
250: .Lf flatsize "'g_form ['x_max]"
251: .Re
252: the number of characters required to print g_form using \fIprint\fP.
253: The meaning of x_max is the same as for flatc.
254: .No
255: Currently this just
256: .i explode 's
257: g_form and checks its length.
258: .Lf fileopen "'st_filename 'st_mode"
259: .Re
260: a port for reading or writing (depending on st_mode) the file st_name.
261: .Se
262: the given file is opened (or created if opened for writing and it
263: doesn't yet exist).
264: .No
265: this function call provides a direct
266: interface to the operating system's fopen function.
267: The mode may be more than just "r" for read, "w" for write or "a" for
268: append. The modes "r+", "w+" and "a+" permit both reading and writing
269: on a port provided that
270: .i fseek
271: is done between changes in direction.
272: See the UNIX manual description of fopen for more details.
273: This routine does not look through a search path for a given file.
274: .Lf fseek "'p_port 'x_offset 'x_flag"
275: .Re
276: the position in the file after the function is performed.
277: .Se
278: this function positions the read/write pointer before a certain byte
279: in the file.
280: If x_flag is 0 then the pointer is set to x_offset bytes from the
281: beginning of the file.
282: If x_flag is 1 then the pointer is set to x_offset bytes from the
283: current location in the file.
284: If x_flag is 2 then the pointer is set to x_offset bytes from the
285: end of the file.
286: .Lf infile "'s_filename"
287: .Re
288: a port ready to read s_filename.
289: .Se
290: this tries to open s_filename and if it cannot or if there are no
291: ports available it gives an error message.
292: .No
293: to allow your program to continue on a file-not-found error,
294: you can use something like:
295: .br
296: \fI(cond ((null (setq myport (car (errset (infile name) nil))))
297: .br
298: \ \ \ \ \ \ \ \ \ \ \ \ (patom '"couldn't open the file")))\fP
299: .br
300: which will set myport to the port to read from if the file exists
301: or will print a message if it couldn't open it and also set myport to nil.
302: To simply determine if a file exists, use
303: .i probef .
304: .Lf load "'s_filename ['st_map ['g_warn]]"
305: .Re
306: t
307: .No
308: The function of
309: .i load
310: has changed since previous releases of
311: .Fr
312: and the following description should be read carefully.
313: .Se
314: .i load
315: now serves the function of both
316: .i fasl
317: and the old
318: .i load .
319: .i Load
320: will search a user defined search path for a lisp source or object file
321: with the filename s_filename (with the extension .l or .o added as
322: appropriate).
323: The search path which
324: .i load
325: uses is the value of \fI(status\ load-search-path)\fP.
326: The default is (|.|\ /usr/lib/lisp) which means look in the current
327: directory first and then /usr/lib/lisp.
328: The file which
329: .i load
330: looks for depends on the last two characters of s_filename.
331: If s_filename ends with ".l" then
332: .i load
333: will only look for a file name
334: s_filename and will assume that this is a
335: .Fr
336: source file.
337: If s_filename ends with ".o" then
338: .i load
339: will only look for a file named s_filename and will assume that this is
340: a
341: .Fr
342: object file to be
343: .i fasl ed
344: in.
345: Otherwise,
346: .i load
347: will first look for s_filename.o, then s_filename.l and finally
348: s_filename itself.
349: If it finds s_filename.o it will assume that this is an object file,
350: otherwise it will assume that it is a source file.
351: An object file is loaded using
352: .i fasl
353: and a source file is loaded by reading and evaluating each form in the
354: file.
355: The optional arguments st_map and g_warn are passed to
356: .i fasl
357: should
358: .i fasl
359: be called.
360: .No
361: \fIload\fP requires a port to open the file s_filename.
362: It then lambda binds the symbol piport to this port and reads and
363: evaluates the forms.
364: .Lf makereadtable "['s_flag]"
365: .Wh
366: if s_flag is not present it is assumed to be nil.
367: .Re
368: a readtable equal to the original readtable if s_flag is non-null, or else
369: equal to the current readtable.
370: See chapter 7 for a description of readtables and their uses.
371: .Lf msg "[l_option ...] ['g_msg ...]"
372: .No
373: This function is intended for printing short messages.
374: Any of the arguments or options
375: presented can be used any number of times, in any
376: order. The messages themselves (g_msg) are evaluated, and then
377: they are transmitted to
378: .i patom .
379: Typically, they are strings, which evaluate to themselves.
380: The options are interpreted specially:
381: .Eb
382: \fImsg Option Summary\fP
383:
384: \fI(P\ p_portname)\fP causes subsequent output to go to the port p_portname
385: (port should be opened previously)
386:
387: \fIB\fP print a single blank.
388:
389: \fI(B\ 'n_b)\fP\ \ evaluate n_b and print that many blanks.
390:
391: \fIN\fP print a single by calling \fIterpr\fP.
392:
393: \fI(N\ 'n_n)\fP\ \ evaluate n_n and transmit
394: that many newlines to the stream.
395:
396: \fID\fP \fIdrain\fP the current port.
397: .Ee
398: .Lf nwritn "['p_port]"
399: .Re
400: the number of characters in the buffer
401: of the given port but not yet written out to the file or device.
402: The buffer is flushed
403: automatically when filled,
404: or when
405: .i terpr
406: is called.
407: .Lf outfile "'s_filename ['st_type]"
408: .Re
409: a port or nil
410: .Se
411: this opens a port to write s_filename.
412: If st_type is given and if it is a symbol or string whose name
413: begins with `a', then the file will be opened in append mode,
414: that is the current contents will not be lost and the next data
415: will be written at the end of the file.
416: Otherwise,
417: the file opened is truncated by \fIoutfile\fP if it existed beforehand.
418: If there are no free ports, outfile returns nil.
419: If one cannot write on s_filename, an error is signalled.
420: .\".pg
421: .Lf patom "'g_exp ['p_port]"
422: .Re
423: g_exp
424: .Se
425: g_exp is printed to the given port or the default port.
426: If g_exp is a symbol or string, the print name is printed without
427: any escape characters around special characters in the print name.
428: If g_exp is a list then \fIpatom\fP has the same effect as \fIprint\fP.
429: .Lf pntlen "'xfs_arg"
430: .Re
431: the number of characters needed to print xfs_arg.
432: .Lf portp "'g_arg"
433: .Re
434: t iff g_arg is a port.
435: .Lf pp "[l_option] s_name1 ..."
436: .Re
437: t
438: .Se
439: If s_name\fIi\fP has a function binding, it is pretty-printed,
440: otherwise if s_name\fIi\fP has a value then that is pretty-printed.
441: Normally the output of the pretty-printer goes to the standard
442: output port poport.
443: The options allow you to redirect it.
444: .Eb
445: \fIPP Option Summary\fP
446:
447: \fI(F\ s_filename)\fP direct future printing to s_filename
448:
449: \fI(P\ p_portname)\fP causes output to go to the port p_portname
450: (port should be opened previously)
451:
452: \fI(E\ g_expression)\fP evaluate g_expression and don't print
453: .Ee
454: .Lf princ "'g_arg ['p_port]"
455: .Eq
456: patom.
457: .Lf print "'g_arg ['p_port]"
458: .Re
459: nil
460: .Se
461: prints g_arg on the port p_port or the default port.
462: .Lf probef "'st_file"
463: .Re
464: t iff the file st_file exists.
465: .No
466: Just because it exists doesn't mean you can read it.
467: .Lf pp-form "'g_form ['p_port]"
468: .Re
469: t
470: .Se
471: g_form is pretty-printed to the port p_port (or poport if
472: p_port is not given).
473: This is the function which \fIpp\fP uses.
474: \fIpp-form\fP does not look for
475: function definitions or values of variables, it just prints out the form
476: it is given.
477: .No
478: This is useful as a top-level-printer, c.f.
479: .i top-level
480: in Chapter 6.
481: .Lf ratom "['p_port ['g_eof]]"
482: .Re
483: the next atom read from the given or default port.
484: On end of file, g_eof (default nil) is returned.
485: .Lf read "['p_port ['g_eof]]"
486: .Re
487: the next lisp expression read from the given or default port.
488: On end of file, g_eof (default nil) is returned.
489: .No
490: An error will occur if the reader is given an ill formed expression.
491: The most common error is too many right parentheses (note that this is
492: not considered an error in Maclisp).
493: .Lf readc "['p_port ['g_eof]]"
494: .Re
495: the next character read from the given or default port.
496: On end of file, g_eof (default nil) is returned.
497: .Lf readlist "'l_arg"
498: .Re
499: the lisp expression read from the list of characters in l_arg.
500: .Lf removeaddress "'s_name1 ['s_name2 ...]"
501: .Re
502: nil
503: .Se
504: the entries for the s_name\fIi\fP in the Lisp symbol table are removed.
505: This is useful if you wish to
506: .i cfasl
507: or
508: .i ffasl
509: in a file twice, since it is illegal for a symbol in the file you
510: are loading to already exist in the lisp symbol table.
511: .Lf resetio
512: .Re
513: nil
514: .Se
515: all ports except the standard input, output and error
516: are closed.
517: .Lf setsyntax "'s_symbol 's_synclass ['ls_func]"
518: .Re
519: t
520: .Se
521: this sets the code for s_symbol to sx_code in the current readtable.
522: If s_synclass is
523: .i macro
524: or
525: .i splicing
526: then ls_func is the associated function.
527: See Chapter 7 on the reader for more details.
528: .Lf sload "'s_file"
529: .Se
530: the file s_file (in the current directory) is opened for reading and
531: each form is read, printed and evaluated.
532: If the form is recognizable as a function definition, only its name
533: will be printed, otherwise the whole form is printed.
534: .No
535: This function is useful when a file refuses to load because
536: of a syntax error and you would like to narrow down
537: where the error is.
538: .Lf tab "'x_col ['p_port]"
539: .Se
540: enough spaces are printed to put the cursor on column x_col.
541: If the cursor is beyond x_col to start with, a
542: .i terpr
543: is done first.
544: .Lf terpr "['p_port]"
545: .Re
546: nil
547: .Se
548: a terminate line character sequence
549: is sent to the given port or the default port.
550: This will also drain the port.
551: .Lf terpri "['p_port]"
552: .Eq
553: terpr.
554: .Lf tilde-expand 'st_filename
555: .Re
556: a symbol whose pname is the tilde-expansion of the argument,
557: (as discussed at the beginning of this chapter).
558: If the argument does not begin with a tilde, the argument itself is
559: returned.
560: .Lf tyi "['p_port]"
561: .Re
562: the fixnum representation of the next character read.
563: On end of file, -1 is returned.
564: .Lf tyipeek "['p_port]"
565: .Re
566: the fixnum representation of the next character to be read.
567: .No
568: This does not actually read the character, it just peeks at it.
569: .Lf tyo "'x_char ['p_port]"
570: .Re
571: x_char.
572: .Se
573: the character whose fixnum representation is
574: x_code, is printed as a
575: on the given output port or the default output port.
576: .Lf untyi "'x_char ['p_port]"
577: .Se
578: x_char is put back in the input buffer so a subsequent
579: .i tyi
580: or
581: .i read
582: will read it first.
583: .No
584: a maximum of one character may be put back.
585: .Lf username-to-dir 'st_name
586: .Re
587: the home directory of the given user.
588: The result is stored, to avoid unnecessarily searching the
589: password file.
590: .Lf zapline
591: .Re
592: nil
593: .Se
594: all characters up to and including the line termination character
595: are read and discarded from the last port used
596: for input.
597: .No
598: this is used as the macro function for the semicolon character when
599: it acts as a comment character.
This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.