gcc/m2/gm2-libs-log/FileSystem.def

   1 (* FileSystem.def provides a PIM [234] FileSystem module.
   2
   3 Copyright (C) 2004-2024 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 FileSystem ;
  28
  29 (*  Use this module sparingly, FIO or the ISO file modules have a
  30     much cleaner interface.  *)
  31
  32 FROM SYSTEM IMPORT WORD, BYTE, ADDRESS ;
  33 IMPORT FIO ;
  34 FROM DynamicStrings IMPORT String ;
  35
  36 EXPORT QUALIFIED File, Response, Flag, FlagSet,
  37
  38                  Create, Close, Lookup, Rename, Delete,
  39                  SetRead, SetWrite, SetModify, SetOpen,
  40                  Doio, SetPos, GetPos, Length, Reset,
  41
  42                  ReadWord, ReadChar, ReadByte, ReadNBytes,
  43                  WriteWord, WriteChar, WriteByte, WriteNBytes ;
  44
  45 TYPE
  46    File = RECORD
  47              res     : Response ;
  48              flags   : FlagSet ;
  49              eof     : BOOLEAN ;
  50              lastWord: WORD ;
  51              lastByte: BYTE ;
  52              fio     : FIO.File ;
  53              highpos,
  54              lowpos  : CARDINAL ;
  55              name    : String ;
  56           END ;
  57
  58    Flag = (
  59            read,        (* read access mode *)
  60            write,       (* write access mode *)
  61            modify,
  62            truncate,    (* truncate file when closed *)
  63            again,       (* reread the last character *)
  64            temporary,   (* file is temporary *)
  65            opened       (* file has been opened *)
  66           );
  67
  68    FlagSet = SET OF Flag;
  69
  70    Response = (done, notdone, notsupported, callerror,
  71                unknownfile, paramerror, toomanyfiles,
  72                userdeverror) ;
  73
  74    Command = (create, close, lookup, rename, delete,
  75               setread, setwrite, setmodify, setopen,
  76               doio, setpos, getpos, length) ;
  77
  78
  79 (*
  80    Create - creates a temporary file. To make the file perminant
  81             the file must be renamed.
  82 *)
  83
  84 PROCEDURE Create (VAR f: File) ;
  85
  86
  87 (*
  88    Close - closes an open file.
  89 *)
  90
  91 PROCEDURE Close (f: File) ;
  92
  93
  94 (*
  95    Lookup - looks for a file, filename. If the file is found
  96             then, f, is opened. If it is not found and, newFile,
  97             is TRUE then a new file is created and attached to, f.
  98             If, newFile, is FALSE and no file was found then f.res
  99             is set to notdone.
 100 *)
 101
 102 PROCEDURE Lookup (VAR f: File; filename: ARRAY OF CHAR; newFile: BOOLEAN) ;
 103
 104
 105 (*
 106    Rename - rename a file and change a temporary file to a permanent
 107             file. f.res is set appropriately.
 108 *)
 109
 110 PROCEDURE Rename (VAR f: File; newname: ARRAY OF CHAR) ;
 111
 112
 113 (*
 114    Delete - deletes a file, name, and sets the f.res field.
 115             f.res is set appropriately.
 116 *)
 117
 118 PROCEDURE Delete (name: ARRAY OF CHAR; VAR f: File) ;
 119
 120
 121 (*
 122    ReadWord - reads a WORD, w, from file, f.
 123               f.res is set appropriately.
 124 *)
 125
 126 PROCEDURE ReadWord (VAR f: File; VAR w: WORD) ;
 127
 128
 129 (*
 130    WriteWord - writes one word to a file, f.
 131                f.res is set appropriately.
 132 *)
 133
 134 PROCEDURE WriteWord (VAR f: File; w: WORD) ;
 135
 136
 137 (*
 138    ReadChar - reads one character from a file, f.
 139 *)
 140
 141 PROCEDURE ReadChar (VAR f: File; VAR ch: CHAR) ;
 142
 143
 144 (*
 145    WriteChar - writes a character, ch, to a file, f.
 146                f.res is set appropriately.
 147 *)
 148
 149 PROCEDURE WriteChar (VAR f: File; ch: CHAR) ;
 150
 151
 152 (*
 153    ReadByte - reads a BYTE, b, from file, f.
 154               f.res is set appropriately.
 155 *)
 156
 157 PROCEDURE ReadByte (VAR f: File; VAR b: BYTE) ;
 158
 159
 160 (*
 161    WriteByte - writes one BYTE, b, to a file, f.
 162                f.res is set appropriately.
 163 *)
 164
 165 PROCEDURE WriteByte (VAR f: File; b: BYTE) ;
 166
 167
 168 (*
 169    ReadNBytes - reads a sequence of bytes from a file, f.
 170 *)
 171
 172 PROCEDURE ReadNBytes (VAR f: File; a: ADDRESS; amount: CARDINAL;
 173                       VAR actuallyRead: CARDINAL) ;
 174
 175
 176 (*
 177    WriteNBytes - writes a sequence of bytes to file, f.
 178 *)
 179
 180 PROCEDURE WriteNBytes (VAR f: File; a: ADDRESS; amount: CARDINAL;
 181                        VAR actuallyWritten: CARDINAL) ;
 182
 183
 184 (*
 185    Again - returns the last character read to the internal buffer
 186            so that it can be read again.
 187 *)
 188
 189 PROCEDURE Again (VAR f: File) ;
 190
 191
 192 (*
 193    SetRead - puts the file, f, into the read state.
 194              The file position is unchanged.
 195 *)
 196
 197 PROCEDURE SetRead (VAR f: File) ;
 198
 199
 200 (*
 201    SetWrite - puts the file, f, into the write state.
 202               The file position is unchanged.
 203 *)
 204
 205 PROCEDURE SetWrite (VAR f: File) ;
 206
 207
 208 (*
 209    SetModify - puts the file, f, into the modify state.
 210                The file position is unchanged but the file can be
 211                read and written.
 212 *)
 213
 214 PROCEDURE SetModify (VAR f: File) ;
 215
 216
 217 (*
 218    SetOpen - places a file, f, into the open state. The file may
 219              have been in the read/write/modify state before and
 220              in which case the previous buffer contents are flushed
 221              and the file state is reset to open. The position is
 222              unaltered.
 223 *)
 224
 225 PROCEDURE SetOpen (VAR f: File) ;
 226
 227
 228 (*
 229    Reset - places a file, f, into the open state and reset the
 230            position to the start of the file.
 231 *)
 232
 233 PROCEDURE Reset (VAR f: File) ;
 234
 235
 236 (*
 237    SetPos - lseek to a position within a file.
 238 *)
 239
 240 PROCEDURE SetPos (VAR f: File; high, low: CARDINAL) ;
 241
 242
 243 (*
 244    GetPos - return the position within a file.
 245 *)
 246
 247 PROCEDURE GetPos (VAR f: File; VAR high, low: CARDINAL) ;
 248
 249
 250 (*
 251    Length - returns the length of file, in, high, and, low.
 252 *)
 253
 254 PROCEDURE Length (VAR f: File; VAR high, low: CARDINAL) ;
 255
 256
 257 (*
 258    Doio - effectively flushes a file in write mode, rereads the
 259           current buffer from disk if in read mode and writes
 260           and rereads the buffer if in modify mode.
 261 *)
 262
 263 PROCEDURE Doio (VAR f: File) ;
 264
 265
 266 (*
 267    FileNameChar - checks to see whether the character, ch, is
 268                   legal in a filename. nul is returned if the
 269                   character was illegal.
 270 *)
 271
 272 PROCEDURE FileNameChar (ch: CHAR) ;
 273
 274
 275 END FileSystem.