Debian Codegraph @

gcc/m2/gm2-libs-iso/IOChan.mod

raw
1 (* IOChan.mod implement the ISO IOChan specification.
2
3 Copyright (C) 2002-2025 Free Software Foundation, Inc.
4 Contributed by Gaius Mulley <[email protected]>.
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 IMPLEMENTATION MODULE IOChan ;
28
29 IMPORT FIO, EXCEPTIONS, M2EXCEPTION, RTio,
30 RTentity, errno, ErrnoCategory, IOLink, StdChans, M2RTS ;
31
32 FROM EXCEPTIONS IMPORT ExceptionSource, RAISE, AllocateSource,
33 IsCurrentSource, IsExceptionalExecution ;
34 FROM Storage IMPORT ALLOCATE ;
35
36
37 TYPE
38 ChanId = RTio.ChanId ;
39
40 VAR
41 iochan : ExceptionSource ;
42 invalid: ChanId ;
43
44
45 PROCEDURE InvalidChan () : ChanId ;
46 (* Returns the value identifying the invalid channel. *)
47 BEGIN
48 RETURN( invalid )
49 END InvalidChan ;
50
51
52 PROCEDURE CheckValid (cid: ChanId) ;
53 (* internal routine to check whether we have a valid channel *)
54 BEGIN
55 IF cid=InvalidChan()
56 THEN
57 RAISE(iochan, ORD(notAChannel), 'IOChan: ChanId specified is invalid')
58 END
59 END CheckValid ;
60
61
62 (* For each of the following operations, if the device supports the
63 operation on the channel, the behaviour of the procedure conforms
64 with the description below. The full behaviour is defined for
65 each device module. If the device does not support the operation
66 on the channel, the behaviour of the procedure is to raise the
67 exception notAvailable.
68 *)
69
70 (* Text operations - these perform any required translation
71 between the internal and external representation of text.
72 *)
73
74 PROCEDURE Look (cid: ChanId; VAR ch: CHAR; VAR res: IOConsts.ReadResults) ;
75 (* If there is a character as the next item in the input stream cid,
76 assigns its value to ch without removing it from the stream;
77 otherwise the value of ch is not defined.
78 res (and the stored read result) are set to the value
79 allRight, endOfLine, or endOfInput.
80 *)
81 VAR
82 did: IOLink.DeviceId ;
83 dtp: IOLink.DeviceTablePtr ;
84 BEGIN
85 CheckValid(cid) ;
86 did := RTio.GetDeviceId(cid) ;
87 dtp := IOLink.DeviceTablePtrValue(cid, did) ;
88 IF dtp=NIL
89 THEN
90 RAISE(iochan, ORD(hardDeviceError),
91 'IOChan.Look: device table ptr is NIL')
92 ELSE
93 WITH dtp^ DO
94 IF cid=StdChans.NullChan()
95 THEN
96 result := IOConsts.endOfInput
97 ELSIF (ChanConsts.readFlag IN flags) AND (ChanConsts.textFlag IN flags)
98 THEN
99 doLook(dtp, ch, res)
100 ELSE
101 res := IOConsts.wrongFormat
102 END ;
103 result := res
104 END
105 END
106 END Look ;
107
108
109 PROCEDURE Skip (cid: ChanId) ;
110 (* If the input stream cid has ended, the exception skipAtEnd is raised;
111 otherwise the next character or line mark in cid is removed,
112 and the stored read result is set to the value allRight.
113 *)
114 VAR
115 did: IOLink.DeviceId ;
116 dtp: IOLink.DeviceTablePtr ;
117 BEGIN
118 CheckValid(cid) ;
119 did := RTio.GetDeviceId(cid) ;
120 dtp := IOLink.DeviceTablePtrValue(cid, did) ;
121 IF dtp=NIL
122 THEN
123 RAISE(iochan, ORD(hardDeviceError),
124 'IOChan.Skip: device table ptr is NIL')
125 ELSE
126 WITH dtp^ DO
127 IF (cid=StdChans.NullChan()) OR (result=IOConsts.endOfInput)
128 THEN
129 RAISE(iochan, ORD(skipAtEnd),
130 'IOChan.Skip: attempt to skip data from a stream that has ended')
131 ELSIF (ChanConsts.readFlag IN flags) AND (ChanConsts.textFlag IN flags)
132 THEN
133 doSkip(dtp) ;
134 result := IOConsts.allRight
135 ELSE
136 RAISE(iochan, ORD(notAvailable),
137 'IOChan.Skip: attempt to skip data from a channel which is not configured as read and text')
138 END
139 END
140 END
141 END Skip ;
142
143
144 PROCEDURE SkipLook (cid: ChanId;
145 VAR ch: CHAR;
146 VAR res: IOConsts.ReadResults) ;
147 (* If the input stream cid has ended, the exception skipAtEnd is raised;
148 otherwise the next character or line mark in cid is removed.
149 If there is a character as the next item in cid stream,
150 assigns its value to ch without removing it from the stream.
151 Otherwise, the value of ch is not defined.
152 res (and the stored read result) are set to the value allRight,
153 endOfLine, or endOfInput.
154 *)
155 VAR
156 did: IOLink.DeviceId ;
157 dtp: IOLink.DeviceTablePtr ;
158 BEGIN
159 CheckValid(cid) ;
160 did := RTio.GetDeviceId(cid) ;
161 dtp := IOLink.DeviceTablePtrValue(cid, did) ;
162 IF dtp=NIL
163 THEN
164 RAISE(iochan, ORD(hardDeviceError),
165 'IOChan.SkipLook: device table ptr is NIL')
166 ELSE
167 WITH dtp^ DO
168 IF (cid=StdChans.NullChan()) OR (result=IOConsts.endOfInput)
169 THEN
170 RAISE(iochan, ORD(skipAtEnd),
171 'IOChan.SkipLook: attempt to skip data from a stream that has ended')
172 ELSIF (ChanConsts.readFlag IN flags) AND (ChanConsts.textFlag IN flags)
173 THEN
174 doSkipLook(dtp, ch, result)
175 ELSE
176 RAISE(iochan, ORD(notAvailable),
177 'IOChan.SkipLook: attempt to skip data from a channel which is not configured as read and text')
178 END ;
179 res := result
180 END
181 END
182 END SkipLook ;
183
184
185 PROCEDURE WriteLn (cid: ChanId) ;
186 (* Writes a line mark over the channel cid. *)
187 VAR
188 did: IOLink.DeviceId ;
189 dtp: IOLink.DeviceTablePtr ;
190 BEGIN
191 CheckValid(cid) ;
192 did := RTio.GetDeviceId(cid) ;
193 dtp := IOLink.DeviceTablePtrValue(cid, did) ;
194 IF dtp=NIL
195 THEN
196 RAISE(iochan, ORD(hardDeviceError),
197 'IOChan.WriteLn: device table ptr is NIL')
198 ELSE
199 WITH dtp^ DO
200 IF cid=StdChans.NullChan()
201 THEN
202 (* do nothing *)
203 ELSIF (ChanConsts.writeFlag IN flags) AND (ChanConsts.textFlag IN flags)
204 THEN
205 dtp^.doLnWrite(dtp)
206 ELSE
207 RAISE(iochan, ORD(notAvailable),
208 'IOChan.WriteLn: attempting to write to a channel which is not configured as write and text')
209 END
210 END
211 END
212 END WriteLn ;
213
214
215 PROCEDURE TextRead (cid: ChanId;
216 to: SYSTEM.ADDRESS;
217 maxChars: CARDINAL;
218 VAR charsRead: CARDINAL) ;
219 (* Reads at most maxChars characters from the current line in cid,
220 and assigns corresponding values to successive components of an
221 ARRAY OF CHAR variable for which the address of the first
222 component is to. The number of characters read is assigned
223 to charsRead. The stored read result is set to allRight,
224 endOfLine, or endOfInput.
225 *)
226 VAR
227 did: IOLink.DeviceId ;
228 dtp: IOLink.DeviceTablePtr ;
229 BEGIN
230 CheckValid(cid) ;
231 did := RTio.GetDeviceId(cid) ;
232 dtp := IOLink.DeviceTablePtrValue(cid, did) ;
233 IF dtp=NIL
234 THEN
235 RAISE(iochan, ORD(hardDeviceError),
236 'IOChan.TextRead: device table ptr is NIL')
237 ELSE
238 WITH dtp^ DO
239 IF (cid=StdChans.NullChan()) OR (result=IOConsts.endOfInput)
240 THEN
241 charsRead := 0 ;
242 result := IOConsts.endOfInput
243 ELSIF (ChanConsts.readFlag IN flags) AND (ChanConsts.textFlag IN flags)
244 THEN
245 doTextRead(dtp, to, maxChars, charsRead)
246 ELSE
247 RAISE(iochan, ORD(notAvailable),
248 'IOChan.TextRead: attempt to read data from a channel which is not configured as read and text')
249 END
250 END
251 END
252 END TextRead ;
253
254
255 PROCEDURE TextWrite (cid: ChanId;
256 from: SYSTEM.ADDRESS;
257 charsToWrite: CARDINAL) ;
258 (* Writes a number of characters given by the value of charsToWrite,
259 from successive components of an ARRAY OF CHAR variable for which
260 the address of the first component is from, to the channel cid.
261 *)
262 VAR
263 did: IOLink.DeviceId ;
264 dtp: IOLink.DeviceTablePtr ;
265 BEGIN
266 CheckValid(cid) ;
267 did := RTio.GetDeviceId(cid) ;
268 dtp := IOLink.DeviceTablePtrValue(cid, did) ;
269 IF dtp=NIL
270 THEN
271 RAISE(iochan, ORD(hardDeviceError),
272 'IOChan.TextWrite: device table ptr is NIL')
273 ELSE
274 WITH dtp^ DO
275 IF cid=StdChans.NullChan()
276 THEN
277 (* do nothing *)
278 ELSIF (ChanConsts.writeFlag IN flags) AND (ChanConsts.textFlag IN flags)
279 THEN
280 doTextWrite(dtp, from, charsToWrite)
281 ELSE
282 RAISE(iochan, ORD(notAvailable),
283 'IOChan.TextWrite: attempt to write data to a channel which is not configured as write and text')
284 END
285 END
286 END
287 END TextWrite ;
288
289
290 (* Direct raw operations - these do not effect translation between
291 the internal and external representation of data
292 *)
293
294 PROCEDURE RawRead (cid: ChanId;
295 to: SYSTEM.ADDRESS;
296 maxLocs: CARDINAL;
297 VAR locsRead: CARDINAL) ;
298 (* Reads at most maxLocs items from cid, and assigns corresponding
299 values to successive components of an ARRAY OF LOC variable for
300 which the address of the first component is to. The number of
301 characters read is assigned to locsRead. The stored read result
302 is set to the value allRight, or endOfInput.
303 *)
304 VAR
305 did: IOLink.DeviceId ;
306 dtp: IOLink.DeviceTablePtr ;
307 BEGIN
308 CheckValid(cid) ;
309 did := RTio.GetDeviceId(cid) ;
310 dtp := IOLink.DeviceTablePtrValue(cid, did) ;
311 IF dtp=NIL
312 THEN
313 RAISE(iochan, ORD(hardDeviceError),
314 'IOChan.RawRead: device table ptr is NIL')
315 ELSE
316 WITH dtp^ DO
317 IF (cid=StdChans.NullChan()) OR (result=IOConsts.endOfInput)
318 THEN
319 locsRead := 0 ;
320 result := IOConsts.endOfInput
321 ELSIF (ChanConsts.readFlag IN flags) AND (ChanConsts.rawFlag IN flags)
322 THEN
323 doRawRead(dtp, to, maxLocs, locsRead)
324 ELSE
325 RAISE(iochan, ORD(notAvailable),
326 'IOChan.RawRead: attempt to read data from a channel which is not configured as read and raw')
327 END
328 END
329 END
330 END RawRead ;
331
332
333 PROCEDURE RawWrite (cid: ChanId; from: SYSTEM.ADDRESS; locsToWrite: CARDINAL) ;
334 (* Writes a number of items given by the value of charsToWrite,
335 from successive components of an ARRAY OF LOC variable for
336 which the address of the first component is from, to the channel cid.
337 *)
338 VAR
339 did: IOLink.DeviceId ;
340 dtp: IOLink.DeviceTablePtr ;
341 BEGIN
342 CheckValid(cid) ;
343 did := RTio.GetDeviceId(cid) ;
344 dtp := IOLink.DeviceTablePtrValue(cid, did) ;
345 IF dtp=NIL
346 THEN
347 RAISE(iochan, ORD(hardDeviceError),
348 'IOChan.RawWrite: device table ptr is NIL')
349 ELSE
350 WITH dtp^ DO
351 IF (cid=StdChans.NullChan()) OR (result=IOConsts.endOfInput)
352 THEN
353 result := IOConsts.endOfInput
354 ELSIF (ChanConsts.writeFlag IN flags) AND (ChanConsts.rawFlag IN flags)
355 THEN
356 doRawWrite(dtp, from, locsToWrite)
357 ELSE
358 RAISE(iochan, ORD(notAvailable),
359 'IOChan.RawWrite: attempt to write data to a channel which is not configured as write and raw')
360 END
361 END
362 END
363 END RawWrite ;
364
365
366 (* Common operations *)
367
368 PROCEDURE GetName (cid: ChanId; VAR s: ARRAY OF CHAR) ;
369 (* Copies to s a name associated with the channel cid, possibly truncated
370 (depending on the capacity of s).
371 *)
372 VAR
373 did: IOLink.DeviceId ;
374 dtp: IOLink.DeviceTablePtr ;
375 BEGIN
376 CheckValid(cid) ;
377 did := RTio.GetDeviceId(cid) ;
378 dtp := IOLink.DeviceTablePtrValue(cid, did) ;
379 IF dtp=NIL
380 THEN
381 RAISE(iochan, ORD(hardDeviceError),
382 'IOChan.GetName: device table ptr is NIL')
383 ELSE
384 dtp^.doGetName(dtp, s)
385 END
386 END GetName ;
387
388
389 PROCEDURE Reset (cid: ChanId) ;
390 (* Resets the channel cid to a state defined by the device module. *)
391 VAR
392 did: IOLink.DeviceId ;
393 dtp: IOLink.DeviceTablePtr ;
394 BEGIN
395 CheckValid(cid) ;
396 did := RTio.GetDeviceId(cid) ;
397 dtp := IOLink.DeviceTablePtrValue(cid, did) ;
398 IF dtp=NIL
399 THEN
400 RAISE(iochan, ORD(hardDeviceError),
401 'IOChan.Reset: device table ptr is NIL')
402 ELSE
403 dtp^.doReset(dtp)
404 END
405 END Reset ;
406
407
408 PROCEDURE Flush (cid: ChanId) ;
409 (* Flushes any data buffered by the device module out to the channel cid. *)
410 VAR
411 did: IOLink.DeviceId ;
412 dtp: IOLink.DeviceTablePtr ;
413 BEGIN
414 CheckValid(cid) ;
415 did := RTio.GetDeviceId(cid) ;
416 dtp := IOLink.DeviceTablePtrValue(cid, did) ;
417 IF dtp=NIL
418 THEN
419 RAISE(iochan, ORD(hardDeviceError),
420 'IOChan.Flush: device table ptr is NIL')
421 ELSE
422 dtp^.doFlush(dtp)
423 END
424 END Flush ;
425
426
427 (* Access to read results *)
428
429 PROCEDURE SetReadResult (cid: ChanId; res: IOConsts.ReadResults) ;
430 (* Sets the read result value for the channel cid to the value res. *)
431 VAR
432 did: IOLink.DeviceId ;
433 dtp: IOLink.DeviceTablePtr ;
434 BEGIN
435 CheckValid(cid) ;
436 did := RTio.GetDeviceId(cid) ;
437 dtp := IOLink.DeviceTablePtrValue(cid, did) ;
438 IF dtp=NIL
439 THEN
440 RAISE(iochan, ORD(hardDeviceError),
441 'IOChan.SetReadResult: device table ptr is NIL')
442 ELSE
443 dtp^.result := res
444 END
445 END SetReadResult ;
446
447
448 PROCEDURE ReadResult (cid: ChanId) : IOConsts.ReadResults ;
449 (* Returns the stored read result value for the channel cid.
450 (This is initially the value notKnown).
451 *)
452 VAR
453 did: IOLink.DeviceId ;
454 dtp: IOLink.DeviceTablePtr ;
455 BEGIN
456 CheckValid(cid) ;
457 did := RTio.GetDeviceId(cid) ;
458 dtp := IOLink.DeviceTablePtrValue(cid, did) ;
459 IF dtp=NIL
460 THEN
461 RAISE(iochan, ORD(hardDeviceError),
462 'IOChan.SetReadResult: device table ptr is NIL') ;
463 RETURN IOConsts.notKnown
464 ELSE
465 RETURN( dtp^.result )
466 END
467 END ReadResult ;
468
469
470 (* Users can discover which flags actually apply to a channel *)
471
472 PROCEDURE CurrentFlags (cid: ChanId) : ChanConsts.FlagSet ;
473 (* Returns the set of flags that currently apply to the channel cid. *)
474 VAR
475 did : IOLink.DeviceId ;
476 dtp : IOLink.DeviceTablePtr ;
477 empty: ChanConsts.FlagSet ;
478 BEGIN
479 CheckValid(cid) ;
480 did := RTio.GetDeviceId(cid) ;
481 dtp := IOLink.DeviceTablePtrValue(cid, did) ;
482 IF dtp=NIL
483 THEN
484 RAISE(iochan, ORD(hardDeviceError),
485 'IOChan.SetReadResult: device table ptr is NIL') ;
486 empty := ChanConsts.FlagSet {} ;
487 RETURN empty
488 ELSE
489 RETURN( dtp^.flags )
490 END
491 END CurrentFlags ;
492
493
494 (* The following exceptions are defined for this module and its clients *)
495
496 PROCEDURE IsChanException () : BOOLEAN ;
497 (* Returns TRUE if the current coroutine is in the exceptional
498 execution state because of the raising of an exception from
499 ChanExceptions; otherwise returns FALSE.
500 *)
501 BEGIN
502 RETURN( IsExceptionalExecution() AND IsCurrentSource(iochan) )
503 END IsChanException ;
504
505
506 PROCEDURE ChanException () : ChanExceptions ;
507 (* If the current coroutine is in the exceptional execution state
508 because of the raising of an exception from ChanExceptions,
509 returns the corresponding enumeration value, and otherwise
510 raises an exception.
511 *)
512 BEGIN
513 IF IsChanException()
514 THEN
515 RETURN( VAL(ChanExceptions, EXCEPTIONS.CurrentNumber(iochan)) )
516 ELSE
517 M2RTS.NoException (SYSTEM.ADR(__FILE__), __LINE__,
518 __COLUMN__, SYSTEM.ADR(__FUNCTION__),
519 SYSTEM.ADR ("not in the exceptional execution state"))
520 END
521 END ChanException ;
522
523
524 (* When a device procedure detects a device error, it raises the
525 exception softDeviceError or hardDeviceError. If these exceptions
526 are handled, the following facilities may be used to discover
527 an implementation-defined error number for the channel.
528 *)
529
530 PROCEDURE DeviceError (cid: ChanId) : DeviceErrNum ;
531 (* If a device error exception has been raised for the channel cid,
532 returns the error number stored by the device module.
533 *)
534 VAR
535 did: IOLink.DeviceId ;
536 dtp: IOLink.DeviceTablePtr ;
537 BEGIN
538 CheckValid(cid) ;
539 did := RTio.GetDeviceId(cid) ;
540 dtp := IOLink.DeviceTablePtrValue(cid, did) ;
541 IF dtp=NIL
542 THEN
543 RAISE(iochan, ORD(hardDeviceError),
544 'IOChan.DeviceError: device table ptr is NIL') ;
545 RETURN DeviceError (invalid)
546 ELSE
547 RETURN( dtp^.errNum )
548 END
549 END DeviceError ;
550
551
552 BEGIN
553 AllocateSource(iochan) ;
554 invalid := ChanId(RTio.InitChanId())
555 END IOChan.