gcc/m2/gm2-libs/FIO.def

   1 (* FIO.def provides a simple buffered file input/output library.
   2
   3 Copyright (C) 2001-2023 Free Software Foundation, Inc.
   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 (*
 162    ReadAny - reads HIGH (a) + 1 bytes into, a.  All input
 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 (*
 183    WriteAny - writes HIGH (a) + 1 bytes onto, file, f.  All output
 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.