gcc/ada/s-fileio.ads

   1 ------------------------------------------------------------------------------
   2 --                                                                          --
   3 --                         GNAT RUN-TIME COMPONENTS                         --
   4 --                                                                          --
   5 --                       S Y S T E M . F I L E _ I O                        --
   6 --                                                                          --
   7 --                                 S p e c                                  --
   8 --                                                                          --
   9 --                            $Revision: 1.17 $
  10 --                                                                          --
  11 --          Copyright (C) 1992-2001, Free Software Foundation, Inc.         --
  12 --                                                                          --
  13 -- GNAT is free software;  you can  redistribute it  and/or modify it under --
  14 -- terms of the  GNU General Public License as published  by the Free Soft- --
  15 -- ware  Foundation;  either version 2,  or (at your option) any later ver- --
  16 -- sion.  GNAT is distributed in the hope that it will be useful, but WITH- --
  17 -- OUT ANY WARRANTY;  without even the  implied warranty of MERCHANTABILITY --
  18 -- or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License --
  19 -- for  more details.  You should have  received  a copy of the GNU General --
  20 -- Public License  distributed with GNAT;  see file COPYING.  If not, write --
  21 -- to  the Free Software Foundation,  59 Temple Place - Suite 330,  Boston, --
  22 -- MA 02111-1307, USA.                                                      --
  23 --                                                                          --
  24 -- As a special exception,  if other files  instantiate  generics from this --
  25 -- unit, or you link  this unit with other files  to produce an executable, --
  26 -- this  unit  does not  by itself cause  the resulting  executable  to  be --
  27 -- covered  by the  GNU  General  Public  License.  This exception does not --
  28 -- however invalidate  any other reasons why  the executable file  might be --
  29 -- covered by the  GNU Public License.                                      --
  30 --                                                                          --
  31 -- GNAT was originally developed  by the GNAT team at  New York University. --
  32 -- It is now maintained by Ada Core Technologies Inc (http://www.gnat.com). --
  33 --                                                                          --
  34 ------------------------------------------------------------------------------
  35
  36 --  This package provides support for the routines described in (RM A.8.2)
  37 --  which are common to Text_IO, Direct_IO, Sequential_IO and Stream_IO.
  38
  39 with Interfaces.C_Streams;
  40
  41 with System.File_Control_Block;
  42
  43 package System.File_IO is
  44
  45    package FCB renames System.File_Control_Block;
  46    package ICS renames Interfaces.C_Streams;
  47
  48    ---------------------
  49    -- File Management --
  50    ---------------------
  51
  52    procedure Open
  53      (File_Ptr  : in out FCB.AFCB_Ptr;
  54       Dummy_FCB : in out FCB.AFCB'Class;
  55       Mode      : FCB.File_Mode;
  56       Name      : String;
  57       Form      : String;
  58       Amethod   : Character;
  59       Creat     : Boolean;
  60       Text      : Boolean;
  61       C_Stream  : ICS.FILEs := ICS.NULL_Stream);
  62    --  This routine is used for both Open and Create calls:
  63    --
  64    --    File_Ptr is the file type, which must be null on entry
  65    --    (i.e. the file must be closed before the call).
  66    --
  67    --    Dummy_FCB is a default initialized file control block of appropriate
  68    --    type. Note that the tag of this record indicates the type and length
  69    --    of the control block. This control block is used only for the purpose
  70    --    of providing the controlling argument for calling the write version
  71    --    of Allocate_AFCB. It has no other purpose, and its fields are never
  72    --    read or written.
  73    --
  74    --    Mode is the required mode
  75    --
  76    --    Name is the file name, with a null string indicating that a temporary
  77    --    file is to be created (only permitted in create mode, not open mode)
  78    --
  79    --    Creat is True for a create call, and false for an open call
  80    --
  81    --    Text is set True to open the file in text mode (w+t or r+t) instead
  82    --    of the usual binary mode open (w+b or r+b).
  83    --
  84    --    Form is the form string given in the open or create call, this is
  85    --    stored in the AFCB, but otherwise is not used by this or any other
  86    --    routine in this unit (except Form which retrieves the original value)
  87    --
  88    --    Amethod indicates the access method
  89    --
  90    --      D = Direct_IO
  91    --      Q = Sequential_IO
  92    --      S = Stream_IO
  93    --      T = Text_IO
  94    --      W = Wide_Text_IO
  95    --
  96    --    C_Stream is left at its default value for the normal case of an
  97    --    Open or Create call as defined in the RM. The only time this is
  98    --    non-null is for the Open call from Ada.xxx_IO.C_Streams.Open.
  99    --
 100    --  On return, if the open/create succeeds, then the fields of File are
 101    --  filled in, and this value is copied to the heap. File_Ptr points to
 102    --  this allocated file control block. If the open/create fails, then the
 103    --  fields of File are undefined, and File_Ptr is unchanged.
 104
 105    procedure Close (File : in out FCB.AFCB_Ptr);
 106    --  The file is closed, all storage associated with it is released, and
 107    --  File is set to null. Note that this routine calls AFCB_Close to perform
 108    --  any specialized close actions, then closes the file at the system level,
 109    --  then frees the mode and form strings, and finally calls AFCB_Free to
 110    --  free the file control block itself, setting File to null.
 111
 112    procedure Delete (File : in out FCB.AFCB_Ptr);
 113    --  The indicated file is unlinked
 114
 115    procedure Reset (File : in out FCB.AFCB_Ptr; Mode : in FCB.File_Mode);
 116    --  The file is reset, and the mode changed as indicated.
 117
 118    procedure Reset (File : in out FCB.AFCB_Ptr);
 119    --  The files is reset, and the mode is unchanged
 120
 121    function Mode (File : in FCB.AFCB_Ptr) return FCB.File_Mode;
 122    --  Returns the mode as supplied by create, open or reset
 123
 124    function Name (File : in FCB.AFCB_Ptr) return String;
 125    --  Returns the file name as supplied by Open or Create. Raises Use_Error
 126    --  if used with temporary files or standard files.
 127
 128    function Form (File : in FCB.AFCB_Ptr) return String;
 129    --  Returns the form as supplied by create, open or reset
 130    --  The string is normalized to all lower case letters.
 131
 132    function Is_Open (File : in FCB.AFCB_Ptr) return Boolean;
 133    --  Determines if file is open or not
 134
 135    ----------------------
 136    -- Utility Routines --
 137    ----------------------
 138
 139    --  Some internal routines not defined in A.8.2. These are routines which
 140    --  provide required common functionality shared by separate packages.
 141
 142    procedure Chain_File (File : FCB.AFCB_Ptr);
 143    --  Used to chain the given file into the list of open files. Normally this
 144    --  is done implicitly by Open. Chain_File is used for the spcial cases of
 145    --  the system files defined by Text_IO (stdin, stdout, stderr) which are
 146    --  not opened in the normal manner. Note that the caller is responsible
 147    --  for task lock out to protect the global data structures if this is
 148    --  necessary (it is needed for the calls from within this unit itself,
 149    --  but not required for the calls from Text_IO and Wide_Text_IO that
 150    --  are made during elaboration of the environment task).
 151
 152    procedure Check_File_Open (File : FCB.AFCB_Ptr);
 153    --  If the current file is not open, then Status_Error is raised.
 154    --  Otherwise control returns normally (with File pointing to the
 155    --  control block for the open file.
 156
 157    procedure Check_Read_Status (File : FCB.AFCB_Ptr);
 158    --  If the current file is not open, then Status_Error is raised. If
 159    --  the file is open, then the mode is checked to ensure that reading
 160    --  is permitted, and if not Mode_Error is raised, otherwise control
 161    --  returns normally.
 162
 163    procedure Check_Write_Status (File : FCB.AFCB_Ptr);
 164    --  If the current file is not open, then Status_Error is raised. If
 165    --  the file is open, then the mode is checked to ensure that writing
 166    --  is permitted, and if not Mode_Error is raised, otherwise control
 167    --  returns normally.
 168
 169    function End_Of_File (File : FCB.AFCB_Ptr) return Boolean;
 170    --  File must be opened in read mode. True is returned if the stream is
 171    --  currently positioned at the end of file, otherwise False is returned.
 172    --  The position of the stream is not affected.
 173
 174    procedure Flush (File : FCB.AFCB_Ptr);
 175    --  Flushes the stream associated with the given file. The file must be
 176    --  open and in write mode (if not, an appropriate exception is raised)
 177
 178    function Form_Boolean
 179      (Form    : String;
 180       Keyword : String;
 181       Default : Boolean)
 182       return    Boolean;
 183    --  Searches form string for an entry of the form Keyword=xx where xx is
 184    --  either Yes/No or y/n. Returns True if Yes or Y is found, False if No
 185    --  or N is found. If the keyword parameter is not found, returns the
 186    --  value given as Default. May raise Use_Error if a form string syntax
 187    --  error is detected. Keyword and Form must be in lower case.
 188
 189    function Form_Integer
 190      (Form    : String;
 191       Keyword : String;
 192       Default : Integer)
 193       return    Integer;
 194    --  Searches form string for an entry of the form Keyword=xx where xx is
 195    --  an unsigned decimal integer in the range 0 to 999_999. Returns this
 196    --  integer value if it is found. If the keyword parameter is not found,
 197    --  returns the value given as Default. Raise Use_Error if a form string
 198    --  syntax error is detected. Keyword and Form must be in lower case.
 199
 200    procedure Form_Parameter
 201      (Form    : String;
 202       Keyword : String;
 203       Start   : out Natural;
 204       Stop    : out Natural);
 205    --  Searches form string for an entry of the form Keyword=xx and if found
 206    --  Sets Start and Stop to the first and last characters of xx. Keyword
 207    --  and Form must be in lower case. If no entry matches, then Start and
 208    --  Stop are set to zero on return. Use_Error is raised if a malformed
 209    --  string is detected, but there is no guarantee of full syntax checking.
 210
 211    procedure Read_Buf
 212      (File : FCB.AFCB_Ptr;
 213       Buf  : Address;
 214       Siz  : Interfaces.C_Streams.size_t);
 215    --  Reads Siz bytes from File.Stream into Buf. The caller has checked
 216    --  that the file is open in read mode. Raises an exception if Siz bytes
 217    --  cannot be read (End_Error if no data was read, Data_Error if a partial
 218    --  buffer was read, Device_Error if an error occurs).
 219
 220    procedure Read_Buf
 221      (File  : FCB.AFCB_Ptr;
 222       Buf   : Address;
 223       Siz   : in Interfaces.C_Streams.size_t;
 224       Count : out Interfaces.C_Streams.size_t);
 225    --  Reads Siz bytes from File.Stream into Buf. The caller has checked
 226    --  that the file is open in read mode. Device Error is raised if an error
 227    --  occurs. Count is the actual number of bytes read, which may be less
 228    --  than Siz if the end of file is encountered.
 229
 230    procedure Append_Set (File : FCB.AFCB_Ptr);
 231    --  If the mode of the file is Append_File, then the file is positioned
 232    --  at the end of file using fseek, otherwise this call has no effect.
 233
 234    procedure Write_Buf
 235      (File : FCB.AFCB_Ptr;
 236       Buf  : Address;
 237       Siz  : Interfaces.C_Streams.size_t);
 238    --  Writes size_t bytes to File.Stream from Buf. The caller has checked
 239    --  that the file is open in write mode. Raises Device_Error if the
 240    --  complete buffer cannot be written.
 241
 242    procedure Make_Unbuffered (File : FCB.AFCB_Ptr);
 243
 244    procedure Make_Line_Buffered
 245      (File     : FCB.AFCB_Ptr;
 246       Line_Siz : Interfaces.C_Streams.size_t);
 247
 248    procedure Make_Buffered
 249      (File     : FCB.AFCB_Ptr;
 250       Buf_Siz  : Interfaces.C_Streams.size_t);
 251
 252 private
 253    pragma Inline (Check_Read_Status);
 254    pragma Inline (Check_Write_Status);
 255    pragma Inline (Form);
 256    pragma Inline (Mode);
 257
 258 end System.File_IO;