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-2018, 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 35with Interfaces.C_Streams; 36 37with System.File_Control_Block; 38 39package System.File_IO is 40 pragma Preelaborate; 41 42 package FCB renames System.File_Control_Block; 43 package ICS renames Interfaces.C_Streams; 44 45 --------------------- 46 -- File Management -- 47 --------------------- 48 49 procedure Open 50 (File_Ptr : in out FCB.AFCB_Ptr; 51 Dummy_FCB : FCB.AFCB'Class; 52 Mode : FCB.File_Mode; 53 Name : String; 54 Form : String; 55 Amethod : Character; 56 Creat : Boolean; 57 Text : Boolean; 58 C_Stream : ICS.FILEs := ICS.NULL_Stream); 59 -- This routine is used for both Open and Create calls: 60 -- 61 -- File_Ptr is the file type, which must be null on entry 62 -- (i.e. the file must be closed before the call). 63 -- 64 -- Dummy_FCB is a default initialized file control block of appropriate 65 -- type. Note that the tag of this record indicates the type and length 66 -- of the control block. This control block is used only for the purpose 67 -- of providing the controlling argument for calling the write version 68 -- of Allocate_AFCB. It has no other purpose, and its fields are never 69 -- read or written. 70 -- 71 -- Mode is the required mode 72 -- 73 -- Name is the file name, with a null string indicating that a temporary 74 -- file is to be created (only permitted in create mode, not open mode). 75 -- 76 -- Creat is True for a create call, and false for an open call 77 -- 78 -- Text is set True to open the file in text mode (w+t or r+t) instead 79 -- of the usual binary mode open (w+b or r+b). 80 -- 81 -- Form is the form string given in the open or create call, this is 82 -- stored in the AFCB. 83 -- 84 -- Amethod indicates the access method: 85 -- 86 -- D = Direct_IO 87 -- Q = Sequential_IO 88 -- S = Stream_IO 89 -- T = Text_IO 90 -- W = Wide_Text_IO 91 -- ??? Wide_Wide_Text_IO ??? 92 -- 93 -- C_Stream is left at its default value for the normal case of an 94 -- Open or Create call as defined in the RM. The only time this is 95 -- non-null is for the Open call from Ada.xxx_IO.C_Streams.Open. 96 -- 97 -- On return, if the open/create succeeds, then the fields of File are 98 -- filled in, and this value is copied to the heap. File_Ptr points to 99 -- this allocated file control block. If the open/create fails, then the 100 -- fields of File are undefined, and File_Ptr is unchanged. 101 102 procedure Close (File_Ptr : access FCB.AFCB_Ptr); 103 -- The file is closed, all storage associated with it is released, and 104 -- File is set to null. Note that this routine calls AFCB_Close to perform 105 -- any specialized close actions, then closes the file at the system level, 106 -- then frees the mode and form strings, and finally calls AFCB_Free to 107 -- free the file control block itself, setting File.all to null. Note that 108 -- for this assignment to be done in all cases, including those where 109 -- an exception is raised, we can't use an IN OUT parameter (which would 110 -- not be copied back in case of abnormal return). 111 112 procedure Delete (File_Ptr : access FCB.AFCB_Ptr); 113 -- The indicated file is unlinked 114 115 procedure Reset (File_Ptr : access FCB.AFCB_Ptr; Mode : FCB.File_Mode); 116 -- The file is reset, and the mode changed as indicated 117 118 procedure Reset (File_Ptr : access FCB.AFCB_Ptr); 119 -- The files is reset, and the mode is unchanged 120 121 function Mode (File : FCB.AFCB_Ptr) return FCB.File_Mode; 122 -- Returns the mode as supplied by create, open or reset 123 124 function Name (File : 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 : FCB.AFCB_Ptr) return String; 129 -- Returns the form as supplied by create, open or reset The string is 130 -- normalized to all lower case letters. 131 132 function Is_Open (File : 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 special 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_]Wide_Text_IO 150 -- that 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. Otherwise 154 -- control returns normally (with File pointing to the control block for 155 -- 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 the 159 -- file is open, then the mode is checked to make sure that reading is 160 -- permitted, and if not Mode_Error is raised, otherwise control returns 161 -- 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 the 165 -- file is open, then the mode is checked to ensure that writing is 166 -- permitted, and if not Mode_Error is raised, otherwise control returns 167 -- 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 open 176 -- 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) return Boolean; 182 -- Searches form string for an entry of the form keyword=xx where xx is 183 -- either yes/no or y/n. Returns True if yes or y is found, False if no or 184 -- n is found. If the keyword parameter is not found, returns the value 185 -- given as Default. May raise Use_Error if a form string syntax error is 186 -- detected. Keyword and Form must be in lower case. 187 188 function Form_Integer 189 (Form : String; 190 Keyword : String; 191 Default : Integer) return Integer; 192 -- Searches form string for an entry of the form Keyword=xx where xx is an 193 -- unsigned decimal integer in the range 0 to 999_999. Returns this integer 194 -- value if it is found. If the keyword parameter is not found, returns the 195 -- value given as Default. Raise Use_Error if a form string syntax error is 196 -- detected. Keyword and Form must be in lower case. 197 198 procedure Form_Parameter 199 (Form : String; 200 Keyword : String; 201 Start : out Natural; 202 Stop : out Natural); 203 -- Searches form string for an entry of the form Keyword=xx and if found 204 -- Sets Start and Stop to the first and last characters of xx. Keyword 205 -- and Form must be in lower case. If no entry matches, then Start and 206 -- Stop are set to zero on return. Use_Error is raised if a malformed 207 -- string is detected, but there is no guarantee of full syntax checking. 208 209 procedure Read_Buf 210 (File : FCB.AFCB_Ptr; 211 Buf : Address; 212 Siz : Interfaces.C_Streams.size_t); 213 -- Reads Siz bytes from File.Stream into Buf. The caller has checked 214 -- that the file is open in read mode. Raises an exception if Siz bytes 215 -- cannot be read (End_Error if no data was read, Data_Error if a partial 216 -- buffer was read, Device_Error if an error occurs). 217 218 procedure Read_Buf 219 (File : FCB.AFCB_Ptr; 220 Buf : Address; 221 Siz : Interfaces.C_Streams.size_t; 222 Count : out Interfaces.C_Streams.size_t); 223 -- Reads Siz bytes from File.Stream into Buf. The caller has checked that 224 -- the file is open in read mode. Device Error is raised if an error 225 -- occurs. Count is the actual number of bytes read, which may be less 226 -- than Siz if the end of file is encountered. 227 228 procedure Append_Set (File : FCB.AFCB_Ptr); 229 -- If the mode of the file is Append_File, then the file is positioned at 230 -- the end of file using fseek, otherwise this call has no effect. 231 232 procedure Write_Buf 233 (File : FCB.AFCB_Ptr; 234 Buf : Address; 235 Siz : Interfaces.C_Streams.size_t); 236 -- Writes size_t bytes to File.Stream from Buf. The caller has checked that 237 -- the file is open in write mode. Raises Device_Error if the complete 238 -- buffer cannot be written. 239 240 procedure Make_Unbuffered (File : FCB.AFCB_Ptr); 241 242 procedure Make_Line_Buffered 243 (File : FCB.AFCB_Ptr; 244 Line_Siz : Interfaces.C_Streams.size_t); 245 246 procedure Make_Buffered 247 (File : FCB.AFCB_Ptr; 248 Buf_Siz : Interfaces.C_Streams.size_t); 249 250private 251 pragma Inline (Check_Read_Status); 252 pragma Inline (Check_Write_Status); 253 pragma Inline (Mode); 254 255end System.File_IO; 256