File : s-fileio.ads
------------------------------------------------------------------------------
-- --
-- GNAT RUN-TIME COMPONENTS --
-- --
5 -- S Y S T E M . F I L E _ I O --
-- --
-- S p e c --
-- --
-- $Revision: 1.17 $
10 -- --
-- Copyright (C) 1992-2001, Free Software Foundation, Inc. --
-- --
-- GNAT is free software; you can redistribute it and/or modify it under --
-- 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- --
-- sion. GNAT is distributed in the hope that it will be useful, but WITH- --
-- OUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY --
-- or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License --
-- 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 --
-- to the Free Software Foundation, 59 Temple Place - Suite 330, Boston, --
-- MA 02111-1307, USA. --
-- --
-- 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, --
-- this unit does not by itself cause the resulting executable to be --
-- covered by the GNU General Public License. This exception does not --
-- however invalidate any other reasons why the executable file might be --
-- covered by the GNU Public License. --
30 -- --
-- GNAT was originally developed by the GNAT team at New York University. --
-- It is now maintained by Ada Core Technologies Inc (http://www.gnat.com). --
-- --
------------------------------------------------------------------------------
35
-- This package provides support for the routines described in (RM A.8.2)
-- which are common to Text_IO, Direct_IO, Sequential_IO and Stream_IO.
with Interfaces.C_Streams;
40
with System.File_Control_Block;
package System.File_IO is
45 package FCB renames System.File_Control_Block;
package ICS renames Interfaces.C_Streams;
---------------------
-- File Management --
50 ---------------------
procedure Open
(File_Ptr : in out FCB.AFCB_Ptr;
Dummy_FCB : in out FCB.AFCB'Class;
55 Mode : FCB.File_Mode;
Name : String;
Form : String;
Amethod : Character;
Creat : Boolean;
60 Text : Boolean;
C_Stream : ICS.FILEs := ICS.NULL_Stream);
-- This routine is used for both Open and Create calls:
--
-- File_Ptr is the file type, which must be null on entry
65 -- (i.e. the file must be closed before the call).
--
-- Dummy_FCB is a default initialized file control block of appropriate
-- type. Note that the tag of this record indicates the type and length
-- of the control block. This control block is used only for the purpose
70 -- of providing the controlling argument for calling the write version
-- of Allocate_AFCB. It has no other purpose, and its fields are never
-- read or written.
--
-- Mode is the required mode
75 --
-- Name is the file name, with a null string indicating that a temporary
-- file is to be created (only permitted in create mode, not open mode)
--
-- Creat is True for a create call, and false for an open call
80 --
-- Text is set True to open the file in text mode (w+t or r+t) instead
-- of the usual binary mode open (w+b or r+b).
--
-- 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
-- routine in this unit (except Form which retrieves the original value)
--
-- Amethod indicates the access method
--
90 -- D = Direct_IO
-- Q = Sequential_IO
-- S = Stream_IO
-- T = Text_IO
-- W = Wide_Text_IO
95 --
-- C_Stream is left at its default value for the normal case of an
-- Open or Create call as defined in the RM. The only time this is
-- non-null is for the Open call from Ada.xxx_IO.C_Streams.Open.
--
100 -- On return, if the open/create succeeds, then the fields of File are
-- filled in, and this value is copied to the heap. File_Ptr points to
-- this allocated file control block. If the open/create fails, then the
-- fields of File are undefined, and File_Ptr is unchanged.
105 procedure Close (File : in out FCB.AFCB_Ptr);
-- The file is closed, all storage associated with it is released, and
-- File is set to null. Note that this routine calls AFCB_Close to perform
-- any specialized close actions, then closes the file at the system level,
-- then frees the mode and form strings, and finally calls AFCB_Free to
110 -- free the file control block itself, setting File to null.
procedure Delete (File : in out FCB.AFCB_Ptr);
-- The indicated file is unlinked
115 procedure Reset (File : in out FCB.AFCB_Ptr; Mode : in FCB.File_Mode);
-- The file is reset, and the mode changed as indicated.
procedure Reset (File : in out FCB.AFCB_Ptr);
-- The files is reset, and the mode is unchanged
120
function Mode (File : in FCB.AFCB_Ptr) return FCB.File_Mode;
-- Returns the mode as supplied by create, open or reset
function Name (File : in FCB.AFCB_Ptr) return String;
125 -- Returns the file name as supplied by Open or Create. Raises Use_Error
-- if used with temporary files or standard files.
function Form (File : in FCB.AFCB_Ptr) return String;
-- Returns the form as supplied by create, open or reset
130 -- The string is normalized to all lower case letters.
function Is_Open (File : in FCB.AFCB_Ptr) return Boolean;
-- Determines if file is open or not
135 ----------------------
-- Utility Routines --
----------------------
-- Some internal routines not defined in A.8.2. These are routines which
140 -- provide required common functionality shared by separate packages.
procedure Chain_File (File : FCB.AFCB_Ptr);
-- Used to chain the given file into the list of open files. Normally this
-- 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
-- not opened in the normal manner. Note that the caller is responsible
-- for task lock out to protect the global data structures if this is
-- necessary (it is needed for the calls from within this unit itself,
-- but not required for the calls from Text_IO and Wide_Text_IO that
150 -- are made during elaboration of the environment task).
procedure Check_File_Open (File : FCB.AFCB_Ptr);
-- If the current file is not open, then Status_Error is raised.
-- Otherwise control returns normally (with File pointing to the
155 -- control block for the open file.
procedure Check_Read_Status (File : FCB.AFCB_Ptr);
-- If the current file is not open, then Status_Error is raised. If
-- 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
-- returns normally.
procedure Check_Write_Status (File : FCB.AFCB_Ptr);
-- 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
-- is permitted, and if not Mode_Error is raised, otherwise control
-- returns normally.
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
-- currently positioned at the end of file, otherwise False is returned.
-- The position of the stream is not affected.
procedure Flush (File : FCB.AFCB_Ptr);
175 -- Flushes the stream associated with the given file. The file must be
-- open and in write mode (if not, an appropriate exception is raised)
function Form_Boolean
(Form : String;
180 Keyword : String;
Default : Boolean)
return Boolean;
-- Searches form string for an entry of the form Keyword=xx where xx is
-- 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
-- value given as Default. May raise Use_Error if a form string syntax
-- error is detected. Keyword and Form must be in lower case.
function Form_Integer
190 (Form : String;
Keyword : String;
Default : Integer)
return Integer;
-- 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
-- integer value if it is found. If the keyword parameter is not found,
-- returns the value given as Default. Raise Use_Error if a form string
-- syntax error is detected. Keyword and Form must be in lower case.
200 procedure Form_Parameter
(Form : String;
Keyword : String;
Start : out Natural;
Stop : out Natural);
205 -- Searches form string for an entry of the form Keyword=xx and if found
-- Sets Start and Stop to the first and last characters of xx. Keyword
-- and Form must be in lower case. If no entry matches, then Start and
-- Stop are set to zero on return. Use_Error is raised if a malformed
-- string is detected, but there is no guarantee of full syntax checking.
210
procedure Read_Buf
(File : FCB.AFCB_Ptr;
Buf : Address;
Siz : Interfaces.C_Streams.size_t);
215 -- Reads Siz bytes from File.Stream into Buf. The caller has checked
-- that the file is open in read mode. Raises an exception if Siz bytes
-- cannot be read (End_Error if no data was read, Data_Error if a partial
-- buffer was read, Device_Error if an error occurs).
220 procedure Read_Buf
(File : FCB.AFCB_Ptr;
Buf : Address;
Siz : in Interfaces.C_Streams.size_t;
Count : out Interfaces.C_Streams.size_t);
225 -- Reads Siz bytes from File.Stream into Buf. The caller has checked
-- that the file is open in read mode. Device Error is raised if an error
-- occurs. Count is the actual number of bytes read, which may be less
-- than Siz if the end of file is encountered.
230 procedure Append_Set (File : FCB.AFCB_Ptr);
-- If the mode of the file is Append_File, then the file is positioned
-- at the end of file using fseek, otherwise this call has no effect.
procedure Write_Buf
235 (File : FCB.AFCB_Ptr;
Buf : Address;
Siz : Interfaces.C_Streams.size_t);
-- Writes size_t bytes to File.Stream from Buf. The caller has checked
-- that the file is open in write mode. Raises Device_Error if the
240 -- complete buffer cannot be written.
procedure Make_Unbuffered (File : FCB.AFCB_Ptr);
procedure Make_Line_Buffered
245 (File : FCB.AFCB_Ptr;
Line_Siz : Interfaces.C_Streams.size_t);
procedure Make_Buffered
(File : FCB.AFCB_Ptr;
250 Buf_Siz : Interfaces.C_Streams.size_t);
private
pragma Inline (Check_Read_Status);
pragma Inline (Check_Write_Status);
255 pragma Inline (Form);
pragma Inline (Mode);
end System.File_IO;