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