]>
Commit | Line | Data |
---|---|---|
1eee94d3 GM |
1 | (* FIO.def provides a simple buffered file input/output library. |
2 | ||
a945c346 | 3 | Copyright (C) 2001-2024 Free Software Foundation, Inc. |
1eee94d3 GM |
4 | Contributed by Gaius Mulley <gaius.mulley@southwales.ac.uk>. |
5 | ||
6 | This file is part of GNU Modula-2. | |
7 | ||
8 | GNU Modula-2 is free software; you can redistribute it and/or modify | |
9 | it under the terms of the GNU General Public License as published by | |
10 | the Free Software Foundation; either version 3, or (at your option) | |
11 | any later version. | |
12 | ||
13 | GNU Modula-2 is distributed in the hope that it will be useful, but | |
14 | WITHOUT ANY WARRANTY; without even the implied warranty of | |
15 | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU | |
16 | General Public License for more details. | |
17 | ||
18 | Under Section 7 of GPL version 3, you are granted additional | |
19 | permissions described in the GCC Runtime Library Exception, version | |
20 | 3.1, as published by the Free Software Foundation. | |
21 | ||
22 | You should have received a copy of the GNU General Public License and | |
23 | a copy of the GCC Runtime Library Exception along with this program; | |
24 | see the files COPYING3 and COPYING.RUNTIME respectively. If not, see | |
25 | <http://www.gnu.org/licenses/>. *) | |
26 | ||
27 | DEFINITION MODULE FIO ; | |
28 | ||
29 | (* Provides a simple buffered file input/output library. *) | |
30 | ||
31 | ||
32 | FROM SYSTEM IMPORT ADDRESS, BYTE ; | |
33 | ||
34 | EXPORT QUALIFIED (* types *) | |
35 | File, | |
36 | (* procedures *) | |
37 | OpenToRead, OpenToWrite, OpenForRandom, Close, | |
38 | EOF, EOLN, WasEOLN, IsNoError, Exists, IsActive, | |
39 | exists, openToRead, openToWrite, openForRandom, | |
40 | SetPositionFromBeginning, | |
41 | SetPositionFromEnd, | |
42 | FindPosition, | |
43 | ReadChar, ReadString, | |
44 | WriteChar, WriteString, WriteLine, | |
45 | WriteCardinal, ReadCardinal, | |
46 | UnReadChar, | |
47 | WriteNBytes, ReadNBytes, | |
48 | FlushBuffer, | |
49 | GetUnixFileDescriptor, | |
50 | GetFileName, getFileName, getFileNameLength, | |
51 | FlushOutErr, | |
52 | (* variables *) | |
53 | StdIn, StdOut, StdErr ; | |
54 | ||
55 | TYPE | |
56 | File = CARDINAL ; | |
57 | ||
58 | (* the following variables are initialized to their UNIX equivalents *) | |
59 | VAR | |
60 | StdIn, StdOut, StdErr: File ; | |
61 | ||
62 | ||
63 | ||
64 | (* | |
65 | IsNoError - returns a TRUE if no error has occured on file, f. | |
66 | *) | |
67 | ||
68 | PROCEDURE IsNoError (f: File) : BOOLEAN ; | |
69 | ||
70 | ||
71 | (* | |
72 | IsActive - returns TRUE if the file, f, is still active. | |
73 | *) | |
74 | ||
75 | PROCEDURE IsActive (f: File) : BOOLEAN ; | |
76 | ||
77 | ||
78 | (* | |
79 | Exists - returns TRUE if a file named, fname exists for reading. | |
80 | *) | |
81 | ||
82 | PROCEDURE Exists (fname: ARRAY OF CHAR) : BOOLEAN ; | |
83 | ||
84 | ||
85 | (* | |
86 | OpenToRead - attempts to open a file, fname, for reading and | |
87 | it returns this file. | |
88 | The success of this operation can be checked by | |
89 | calling IsNoError. | |
90 | *) | |
91 | ||
92 | PROCEDURE OpenToRead (fname: ARRAY OF CHAR) : File ; | |
93 | ||
94 | ||
95 | (* | |
96 | OpenToWrite - attempts to open a file, fname, for write and | |
97 | it returns this file. | |
98 | The success of this operation can be checked by | |
99 | calling IsNoError. | |
100 | *) | |
101 | ||
102 | PROCEDURE OpenToWrite (fname: ARRAY OF CHAR) : File ; | |
103 | ||
104 | ||
105 | (* | |
106 | OpenForRandom - attempts to open a file, fname, for random access | |
107 | read or write and it returns this file. | |
108 | The success of this operation can be checked by | |
109 | calling IsNoError. | |
110 | towrite, determines whether the file should be | |
111 | opened for writing or reading. | |
112 | newfile, determines whether a file should be | |
113 | created if towrite is TRUE or whether the | |
114 | previous file should be left alone, | |
115 | allowing this descriptor to seek | |
116 | and modify an existing file. | |
117 | *) | |
118 | ||
119 | PROCEDURE OpenForRandom (fname: ARRAY OF CHAR; | |
120 | towrite, newfile: BOOLEAN) : File ; | |
121 | ||
122 | ||
123 | (* | |
124 | Close - close a file which has been previously opened using: | |
125 | OpenToRead, OpenToWrite, OpenForRandom. | |
126 | It is correct to close a file which has an error status. | |
127 | *) | |
128 | ||
129 | PROCEDURE Close (f: File) ; | |
130 | ||
131 | ||
132 | (* the following functions are functionally equivalent to the above | |
133 | except they allow C style names. | |
134 | *) | |
135 | ||
136 | PROCEDURE exists (fname: ADDRESS; flength: CARDINAL) : BOOLEAN ; | |
137 | PROCEDURE openToRead (fname: ADDRESS; flength: CARDINAL) : File ; | |
138 | PROCEDURE openToWrite (fname: ADDRESS; flength: CARDINAL) : File ; | |
139 | PROCEDURE openForRandom (fname: ADDRESS; flength: CARDINAL; | |
140 | towrite, newfile: BOOLEAN) : File ; | |
141 | ||
142 | ||
143 | (* | |
144 | FlushBuffer - flush contents of the FIO file, f, to libc. | |
145 | *) | |
146 | ||
147 | PROCEDURE FlushBuffer (f: File) ; | |
148 | ||
149 | ||
150 | (* | |
151 | ReadNBytes - reads nBytes of a file into memory area, dest, returning | |
152 | the number of bytes actually read. | |
153 | This function will consume from the buffer and then | |
154 | perform direct libc reads. It is ideal for large reads. | |
155 | *) | |
156 | ||
157 | PROCEDURE ReadNBytes (f: File; nBytes: CARDINAL; | |
158 | dest: ADDRESS) : CARDINAL ; | |
159 | ||
160 | ||
161 | (* | |
73cc6ce1 | 162 | ReadAny - reads HIGH (a) + 1 bytes into, a. All input |
1eee94d3 GM |
163 | is fully buffered, unlike ReadNBytes and thus is more |
164 | suited to small reads. | |
165 | *) | |
166 | ||
167 | PROCEDURE ReadAny (f: File; VAR a: ARRAY OF BYTE) ; | |
168 | ||
169 | ||
170 | (* | |
171 | WriteNBytes - writes nBytes from memory area src to a file | |
172 | returning the number of bytes actually written. | |
173 | This function will flush the buffer and then | |
174 | write the nBytes using a direct write from libc. | |
175 | It is ideal for large writes. | |
176 | *) | |
177 | ||
178 | PROCEDURE WriteNBytes (f: File; nBytes: CARDINAL; | |
179 | src: ADDRESS) : CARDINAL ; | |
180 | ||
181 | ||
182 | (* | |
73cc6ce1 | 183 | WriteAny - writes HIGH (a) + 1 bytes onto, file, f. All output |
1eee94d3 GM |
184 | is fully buffered, unlike WriteNBytes and thus is more |
185 | suited to small writes. | |
186 | *) | |
187 | ||
188 | PROCEDURE WriteAny (f: File; VAR a: ARRAY OF BYTE) ; | |
189 | ||
190 | ||
191 | (* | |
192 | WriteChar - writes a single character to file, f. | |
193 | *) | |
194 | ||
195 | PROCEDURE WriteChar (f: File; ch: CHAR) ; | |
196 | ||
197 | ||
198 | (* | |
199 | EOF - tests to see whether a file, f, has reached end of file. | |
200 | *) | |
201 | ||
202 | PROCEDURE EOF (f: File) : BOOLEAN ; | |
203 | ||
204 | ||
205 | (* | |
206 | EOLN - tests to see whether a file, f, is about to read a newline. | |
207 | It does NOT consume the newline. It reads the next character | |
208 | and then immediately unreads the character. | |
209 | *) | |
210 | ||
211 | PROCEDURE EOLN (f: File) : BOOLEAN ; | |
212 | ||
213 | ||
214 | (* | |
215 | WasEOLN - tests to see whether a file, f, has just read a newline | |
216 | character. | |
217 | *) | |
218 | ||
219 | PROCEDURE WasEOLN (f: File) : BOOLEAN ; | |
220 | ||
221 | ||
222 | (* | |
223 | ReadChar - returns a character read from file, f. | |
224 | Sensible to check with IsNoError or EOF after calling | |
225 | this function. | |
226 | *) | |
227 | ||
228 | PROCEDURE ReadChar (f: File) : CHAR ; | |
229 | ||
230 | ||
231 | (* | |
232 | UnReadChar - replaces a character, ch, back into file, f. | |
233 | This character must have been read by ReadChar | |
234 | and it does not allow successive calls. It may | |
235 | only be called if the previous read was successful, | |
236 | end of file or end of line seen. | |
237 | *) | |
238 | ||
239 | PROCEDURE UnReadChar (f: File ; ch: CHAR) ; | |
240 | ||
241 | ||
242 | (* | |
243 | WriteLine - writes out a linefeed to file, f. | |
244 | *) | |
245 | ||
246 | PROCEDURE WriteLine (f: File) ; | |
247 | ||
248 | ||
249 | (* | |
250 | WriteString - writes a string to file, f. | |
251 | *) | |
252 | ||
253 | PROCEDURE WriteString (f: File; a: ARRAY OF CHAR) ; | |
254 | ||
255 | ||
256 | (* | |
257 | ReadString - reads a string from file, f, into string, a. | |
258 | It terminates the string if HIGH is reached or | |
259 | if a newline is seen or an error occurs. | |
260 | *) | |
261 | ||
262 | PROCEDURE ReadString (f: File; VAR a: ARRAY OF CHAR) ; | |
263 | ||
264 | ||
265 | (* | |
266 | WriteCardinal - writes a CARDINAL to file, f. | |
267 | It writes the binary image of the CARDINAL. | |
268 | to file, f. | |
269 | *) | |
270 | ||
271 | PROCEDURE WriteCardinal (f: File; c: CARDINAL) ; | |
272 | ||
273 | ||
274 | (* | |
275 | ReadCardinal - reads a CARDINAL from file, f. | |
276 | It reads a bit image of a CARDINAL | |
277 | from file, f. | |
278 | *) | |
279 | ||
280 | PROCEDURE ReadCardinal (f: File) : CARDINAL ; | |
281 | ||
282 | ||
283 | (* | |
284 | GetUnixFileDescriptor - returns the UNIX file descriptor of a file. | |
285 | Useful when combining FIO.mod with select | |
286 | (in Selective.def - but note the comments in | |
287 | Selective about using read/write primatives) | |
288 | *) | |
289 | ||
290 | PROCEDURE GetUnixFileDescriptor (f: File) : INTEGER ; | |
291 | ||
292 | ||
293 | (* | |
294 | SetPositionFromBeginning - sets the position from the beginning | |
295 | of the file. | |
296 | *) | |
297 | ||
298 | PROCEDURE SetPositionFromBeginning (f: File; pos: LONGINT) ; | |
299 | ||
300 | ||
301 | (* | |
302 | SetPositionFromEnd - sets the position from the end of the file. | |
303 | *) | |
304 | ||
305 | PROCEDURE SetPositionFromEnd (f: File; pos: LONGINT) ; | |
306 | ||
307 | ||
308 | (* | |
309 | FindPosition - returns the current absolute position in file, f. | |
310 | *) | |
311 | ||
312 | PROCEDURE FindPosition (f: File) : LONGINT ; | |
313 | ||
314 | ||
315 | (* | |
316 | GetFileName - assigns, a, with the filename associated with, f. | |
317 | *) | |
318 | ||
319 | PROCEDURE GetFileName (f: File; VAR a: ARRAY OF CHAR) ; | |
320 | ||
321 | ||
322 | (* | |
323 | getFileName - returns the address of the filename associated with, f. | |
324 | *) | |
325 | ||
326 | PROCEDURE getFileName (f: File) : ADDRESS ; | |
327 | ||
328 | ||
329 | (* | |
330 | getFileNameLength - returns the number of characters associated with | |
331 | filename, f. | |
332 | *) | |
333 | ||
334 | PROCEDURE getFileNameLength (f: File) : CARDINAL ; | |
335 | ||
336 | ||
337 | (* | |
338 | FlushOutErr - flushes, StdOut, and, StdErr. | |
339 | *) | |
340 | ||
341 | PROCEDURE FlushOutErr ; | |
342 | ||
343 | ||
344 | END FIO. |