Commit | Line | Data |
---|---|---|
f9211498 JF |
1 | .Lc Input/Output 5 |
2 | .\".ch 5 | |
3 | The following functions are used to read and write to and from external devices | |
4 | and programs (through pipes). | |
5 | All I/O goes through the lisp data type called the port. | |
6 | A port may be open for either reading or writing but not both | |
7 | simultaneously. | |
8 | There are only a limited number of ports (20) and they will not be reclaimed | |
9 | unless you | |
10 | .i close | |
11 | them. | |
12 | All ports are reclaimed by a | |
13 | .i resetio | |
14 | call but this drastic step won't be necessary if the program closes | |
15 | what it uses. | |
16 | If you don't supply a port argument to a function which requires one | |
17 | or if you supply a bad port argument (such as nil) | |
18 | then | |
19 | .Fr | |
20 | will use the default port according to this scheme. | |
21 | If you are reading then the default port is the value of the symbol | |
22 | .i piport | |
23 | and if you are writing it is the value of the symbol | |
24 | .i poport . | |
25 | Furthermore if the value of piport or poport is not a valid port then | |
26 | the standard input or standard output will be used, respectively. | |
27 | The standard input and standard output are usually the keyboard and | |
28 | terminal display unless your job is running in the background and its | |
29 | input or output is connected to a pipe. | |
30 | .Lf close "'p_port" | |
31 | .Re | |
32 | t | |
33 | .Se | |
34 | the specified port is drained and closed, releasing the port. | |
35 | .No | |
36 | The standard defaults are not used in this case since you probably never | |
37 | want to close the standard output or standard input. | |
38 | .Lf drain "['p_port]" | |
39 | .Re | |
40 | nil | |
41 | .Se | |
42 | If this is an output port then | |
43 | the characters in the output buffer are all sent to the device. | |
44 | If this is an input port then all pending characters are flushed. | |
45 | The default port for this function is the default output port. | |
46 | .Lf flatsize "'g_form 'x_max" | |
47 | .Re | |
48 | the minumum of x_max and | |
49 | the number of characters required to print g_form using patom (that is, | |
50 | no escapes). | |
51 | .No | |
52 | flatsize only knows about lists, symbols, fixnums and flonums. | |
53 | .\".pg | |
54 | .Lf infile "'s_filename" | |
55 | .Re | |
56 | a port ready to read s_filename. | |
57 | .Se | |
58 | this tries to open s_filename and if it cannot or if there are no | |
59 | ports available it gives an error message. | |
60 | .No | |
61 | to allow your program to continue on a file not found error you can | |
62 | use something like: | |
63 | .br | |
64 | (cond ((null (setq myport (car (errset (infile name) nil)))) | |
65 | .br | |
66 | \ \ \ \ \ \ \ \ (patom '"couldn't open the file"))) | |
67 | .br | |
68 | which will set myport to the port to read from if the file exists | |
69 | or will print a message if it couldn't open it and also set myport to nil. | |
70 | .Lf load "'s_filename" | |
71 | .Re | |
72 | nil | |
73 | .Se | |
74 | the given filename or one similar to it is loaded. | |
75 | The sequence of places searched is this: | |
76 | .in +12n | |
77 | .np | |
78 | s_filename.l in the current directory | |
79 | .np | |
80 | /usr/lib/lisp/s_filename.l | |
81 | .np | |
82 | s_filename in the current directory | |
83 | .np | |
84 | /usr/lib/lisp/s_filename | |
85 | .No | |
86 | load required a port to open the file s_filename. | |
87 | It then lambda binds the symbol piport to this port and reads and | |
88 | evaluates the form. | |
89 | .Lf makereadtable "['s_flag]" | |
90 | .Wh | |
91 | if s_flag is not present it is assumed to be nil. | |
92 | .Re | |
93 | a readtable equal to the original readtable if s_flag is non nil, or else | |
94 | equal to the current readtable. | |
95 | See chapter XX for a description of readtables and their uses. | |
96 | .Lf nwritn "['p_port]" | |
97 | .Re | |
98 | the number of characters in the buffer | |
99 | of the given port but not yet written out to the file or device. | |
100 | The buffer is flushed | |
101 | automatically after the buffer (of 512 characters) is filled | |
102 | or when | |
103 | .i terpr | |
104 | is called. | |
105 | .Lf outfile "'s_filename" | |
106 | .Re | |
107 | a port or nil | |
108 | .Se | |
109 | this opens a port to write s_filename. | |
110 | The file opened is truncated by the outfile if it existed beforehand. | |
111 | If there are no free ports, outfile returns nil. | |
112 | .\".pg | |
113 | .Lf patom "'g_exp ['p_port]" | |
114 | .Re | |
115 | g_exp | |
116 | .Se | |
117 | g_exp is printed to the given port or the default port. | |
118 | If g_exp is a symbol then the print name is printed without | |
119 | any escape characters around special characters in the print name. | |
120 | If g_exp is a list then patom has the same effect as print. | |
121 | .Lf pntlen "'xfs_arg" | |
122 | .Wh | |
123 | xfs_arg is a fixnum, flonum or symbol. | |
124 | .Re | |
125 | the number of characters needed to print xfs_arg. | |
126 | .Lf portp "'g_arg" | |
127 | .Re | |
128 | t iff g_arg is a port. | |
129 | .Lf princ "'g_arg ['p_port]" | |
130 | .Eq | |
131 | patom. | |
132 | .Lf print "'g_arg ['p_port]" | |
133 | .Re | |
134 | nil | |
135 | .Se | |
136 | prints g_arg on the port p_port or the default port. | |
137 | .Im | |
138 | we must decide soon whether we will print a cr-lf too. | |
139 | .Lf ratom "['p_port]" | |
140 | .Re | |
141 | the next atom read from the given or default port. | |
142 | .Lf read "['p_port]" | |
143 | .Re | |
144 | the next lisp exppression read from the given or default port. | |
145 | .Lf readc "['p_port]" | |
146 | .Re | |
147 | the next character read from the given or default port. | |
148 | .Lf readlist "'l_arg" | |
149 | .Re | |
150 | the lisp expression read from the list of characters in l_arg. | |
151 | .Im | |
152 | check this one out. | |
153 | .\".pg | |
154 | .Lf resetio | |
155 | .Re | |
156 | nil | |
157 | .Se | |
158 | all ports except the standard intput, output and error | |
159 | are closed. | |
160 | .Lf setsyntax "'s_symbol 'x_code" | |
161 | .Re | |
162 | t | |
163 | .Se | |
164 | this sets the code for s_symbol to x_code in the current readtable. | |
165 | See the section on the reader, \(sc X.Y, for details. | |
166 | .Lf terpr "['p_port]" | |
167 | .Re | |
168 | nil | |
169 | .Se | |
170 | a terminate line character sequence | |
171 | is sent to the given port or the default port. | |
172 | This will also flush the buffer. | |
173 | .Lf terpri "['p_port]" | |
174 | .Eq | |
175 | terpr. | |
176 | .Lf tyi "['p_port]" | |
177 | .Re | |
178 | the fixnum representation of the next character read. | |
179 | .No | |
180 | Upon end of file, -1 is returned. | |
181 | If you are reading from a file then succeeding | |
182 | .b tyi 's | |
183 | will return -1 without waiting. | |
184 | .Lf tyipeek "['p_port]" | |
185 | .Re | |
186 | the fixnum representation of the next character to be read. | |
187 | .No | |
188 | This does not actually read the character, it just peeks at it. | |
189 | .Lf tyo "'x_char ['p_port]" | |
190 | .Re | |
191 | x_char. | |
192 | .Se | |
193 | the fixnum representation of a character, x_code, is printed as a | |
194 | character on the given output port or the default output port. | |
195 | .Lf zapline | |
196 | .Re | |
197 | nil | |
198 | .Se | |
199 | all characters up to and including the line termination character | |
200 | are read and discarded from the last port used | |
201 | for input. | |
202 | .No | |
203 | this is used as the macro function for the semicolon character when | |
204 | it acts as a comment character. |