1 /* do not edit automatically generated by mc from FIO. */
2 /* FIO.def provides a simple buffered file input/output library.
3
4 Copyright (C) 2001-2023 Free Software Foundation, Inc.
5 Contributed by Gaius Mulley <gaius.mulley@southwales.ac.uk>.
6
7 This file is part of GNU Modula-2.
8
9 GNU Modula-2 is free software; you can redistribute it and/or modify
10 it under the terms of the GNU General Public License as published by
11 the Free Software Foundation; either version 3, or (at your option)
12 any later version.
13
14 GNU Modula-2 is distributed in the hope that it will be useful, but
15 WITHOUT ANY WARRANTY; without even the implied warranty of
16 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
17 General Public License for more details.
18
19 Under Section 7 of GPL version 3, you are granted additional
20 permissions described in the GCC Runtime Library Exception, version
21 3.1, as published by the Free Software Foundation.
22
23 You should have received a copy of the GNU General Public License and
24 a copy of the GCC Runtime Library Exception along with this program;
25 see the files COPYING3 and COPYING.RUNTIME respectively. If not, see
26 <http://www.gnu.org/licenses/>. */
27
28
29 #if !defined (_FIO_H)
30 # define _FIO_H
31
32 #include "config.h"
33 #include "system.h"
34 # ifdef __cplusplus
35 extern "C" {
36 # endif
37 #include <stdbool.h>
38 # if !defined (PROC_D)
39 # define PROC_D
40 typedef void (*PROC_t) (void);
41 typedef struct { PROC_t proc; } PROC;
42 # endif
43
44 # include "GSYSTEM.h"
45
46 # if defined (_FIO_C)
47 # define EXTERN
48 # else
49 # define EXTERN extern
50 # endif
51
52 typedef unsigned int FIO_File;
53
54 EXTERN FIO_File FIO_StdIn;
55 EXTERN FIO_File FIO_StdOut;
56 EXTERN FIO_File FIO_StdErr;
57
58 /*
59 IsNoError - returns a TRUE if no error has occured on file, f.
60 */
61
62 EXTERN bool FIO_IsNoError (FIO_File f);
63
64 /*
65 IsActive - returns TRUE if the file, f, is still active.
66 */
67
68 EXTERN bool FIO_IsActive (FIO_File f);
69
70 /*
71 Exists - returns TRUE if a file named, fname exists for reading.
72 */
73
74 EXTERN bool FIO_Exists (const char *fname_, unsigned int _fname_high);
75
76 /*
77 OpenToRead - attempts to open a file, fname, for reading and
78 it returns this file.
79 The success of this operation can be checked by
80 calling IsNoError.
81 */
82
83 EXTERN FIO_File FIO_OpenToRead (const char *fname_, unsigned int _fname_high);
84
85 /*
86 OpenToWrite - attempts to open a file, fname, for write and
87 it returns this file.
88 The success of this operation can be checked by
89 calling IsNoError.
90 */
91
92 EXTERN FIO_File FIO_OpenToWrite (const char *fname_, unsigned int _fname_high);
93
94 /*
95 OpenForRandom - attempts to open a file, fname, for random access
96 read or write and it returns this file.
97 The success of this operation can be checked by
98 calling IsNoError.
99 towrite, determines whether the file should be
100 opened for writing or reading.
101 newfile, determines whether a file should be
102 created if towrite is TRUE or whether the
103 previous file should be left alone,
104 allowing this descriptor to seek
105 and modify an existing file.
106 */
107
108 EXTERN FIO_File FIO_OpenForRandom (const char *fname_, unsigned int _fname_high, bool towrite, bool newfile);
109
110 /*
111 Close - close a file which has been previously opened using:
112 OpenToRead, OpenToWrite, OpenForRandom.
113 It is correct to close a file which has an error status.
114 */
115
116 EXTERN void FIO_Close (FIO_File f);
117 EXTERN bool FIO_exists (void * fname, unsigned int flength);
118 EXTERN FIO_File FIO_openToRead (void * fname, unsigned int flength);
119 EXTERN FIO_File FIO_openToWrite (void * fname, unsigned int flength);
120 EXTERN FIO_File FIO_openForRandom (void * fname, unsigned int flength, bool towrite, bool newfile);
121
122 /*
123 FlushBuffer - flush contents of the FIO file, f, to libc.
124 */
125
126 EXTERN void FIO_FlushBuffer (FIO_File f);
127
128 /*
129 ReadNBytes - reads nBytes of a file into memory area, dest, returning
130 the number of bytes actually read.
131 This function will consume from the buffer and then
132 perform direct libc reads. It is ideal for large reads.
133 */
134
135 EXTERN unsigned int FIO_ReadNBytes (FIO_File f, unsigned int nBytes, void * dest);
136
137 /*
138 ReadAny - reads HIGH(a) bytes into, a. All input
139 is fully buffered, unlike ReadNBytes and thus is more
140 suited to small reads.
141 */
142
143 EXTERN void FIO_ReadAny (FIO_File f, unsigned char *a, unsigned int _a_high);
144
145 /*
146 WriteNBytes - writes nBytes from memory area src to a file
147 returning the number of bytes actually written.
148 This function will flush the buffer and then
149 write the nBytes using a direct write from libc.
150 It is ideal for large writes.
151 */
152
153 EXTERN unsigned int FIO_WriteNBytes (FIO_File f, unsigned int nBytes, void * src);
154
155 /*
156 WriteAny - writes HIGH(a) bytes onto, file, f. All output
157 is fully buffered, unlike WriteNBytes and thus is more
158 suited to small writes.
159 */
160
161 EXTERN void FIO_WriteAny (FIO_File f, unsigned char *a, unsigned int _a_high);
162
163 /*
164 WriteChar - writes a single character to file, f.
165 */
166
167 EXTERN void FIO_WriteChar (FIO_File f, char ch);
168
169 /*
170 EOF - tests to see whether a file, f, has reached end of file.
171 */
172
173 EXTERN bool FIO_EOF (FIO_File f);
174
175 /*
176 EOLN - tests to see whether a file, f, is about to read a newline.
177 It does NOT consume the newline. It reads the next character
178 and then immediately unreads the character.
179 */
180
181 EXTERN bool FIO_EOLN (FIO_File f);
182
183 /*
184 WasEOLN - tests to see whether a file, f, has just read a newline
185 character.
186 */
187
188 EXTERN bool FIO_WasEOLN (FIO_File f);
189
190 /*
191 ReadChar - returns a character read from file, f.
192 Sensible to check with IsNoError or EOF after calling
193 this function.
194 */
195
196 EXTERN char FIO_ReadChar (FIO_File f);
197
198 /*
199 UnReadChar - replaces a character, ch, back into file, f.
200 This character must have been read by ReadChar
201 and it does not allow successive calls. It may
202 only be called if the previous read was successful,
203 end of file or end of line seen.
204 */
205
206 EXTERN void FIO_UnReadChar (FIO_File f, char ch);
207
208 /*
209 WriteLine - writes out a linefeed to file, f.
210 */
211
212 EXTERN void FIO_WriteLine (FIO_File f);
213
214 /*
215 WriteString - writes a string to file, f.
216 */
217
218 EXTERN void FIO_WriteString (FIO_File f, const char *a_, unsigned int _a_high);
219
220 /*
221 ReadString - reads a string from file, f, into string, a.
222 It terminates the string if HIGH is reached or
223 if a newline is seen or an error occurs.
224 */
225
226 EXTERN void FIO_ReadString (FIO_File f, char *a, unsigned int _a_high);
227
228 /*
229 WriteCardinal - writes a CARDINAL to file, f.
230 It writes the binary image of the CARDINAL.
231 to file, f.
232 */
233
234 EXTERN void FIO_WriteCardinal (FIO_File f, unsigned int c);
235
236 /*
237 ReadCardinal - reads a CARDINAL from file, f.
238 It reads a bit image of a CARDINAL
239 from file, f.
240 */
241
242 EXTERN unsigned int FIO_ReadCardinal (FIO_File f);
243
244 /*
245 GetUnixFileDescriptor - returns the UNIX file descriptor of a file.
246 Useful when combining FIO.mod with select
247 (in Selective.def - but note the comments in
248 Selective about using read/write primatives)
249 */
250
251 EXTERN int FIO_GetUnixFileDescriptor (FIO_File f);
252
253 /*
254 SetPositionFromBeginning - sets the position from the beginning
255 of the file.
256 */
257
258 EXTERN void FIO_SetPositionFromBeginning (FIO_File f, long int pos);
259
260 /*
261 SetPositionFromEnd - sets the position from the end of the file.
262 */
263
264 EXTERN void FIO_SetPositionFromEnd (FIO_File f, long int pos);
265
266 /*
267 FindPosition - returns the current absolute position in file, f.
268 */
269
270 EXTERN long int FIO_FindPosition (FIO_File f);
271
272 /*
273 GetFileName - assigns, a, with the filename associated with, f.
274 */
275
276 EXTERN void FIO_GetFileName (FIO_File f, char *a, unsigned int _a_high);
277
278 /*
279 getFileName - returns the address of the filename associated with, f.
280 */
281
282 EXTERN void * FIO_getFileName (FIO_File f);
283
284 /*
285 getFileNameLength - returns the number of characters associated with
286 filename, f.
287 */
288
289 EXTERN unsigned int FIO_getFileNameLength (FIO_File f);
290
291 /*
292 FlushOutErr - flushes, StdOut, and, StdErr.
293 */
294
295 EXTERN void FIO_FlushOutErr (void);
296 # ifdef __cplusplus
297 }
298 # endif
299
300 # undef EXTERN
301 #endif