File : 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-2012, 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 -- --
19 -- --
20 -- --
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 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
250 private
251 pragma Inline (Check_Read_Status);
252 pragma Inline (Check_Write_Status);
253 pragma Inline (Mode);
254
255 end System.File_IO;