]>
Commit | Line | Data |
---|---|---|
cacbc350 RK |
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 | -- -- | |
4b490c1e | 9 | -- Copyright (C) 1992-2020, Free Software Foundation, Inc. -- |
cacbc350 RK |
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- -- | |
748086b7 | 13 | -- ware Foundation; either version 3, or (at your option) any later ver- -- |
cacbc350 RK |
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 -- | |
748086b7 JJ |
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/>. -- | |
cacbc350 RK |
26 | -- -- |
27 | -- GNAT was originally developed by the GNAT team at New York University. -- | |
71ff80dc | 28 | -- Extensive contributions were provided by Ada Core Technologies Inc. -- |
cacbc350 RK |
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 | |
a6f0cb16 AC |
40 | pragma Preelaborate; |
41 | ||
cacbc350 RK |
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; | |
0ae9f22f | 51 | Dummy_FCB : FCB.AFCB'Class; |
cacbc350 RK |
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 | |
1732c156 | 74 | -- file is to be created (only permitted in create mode, not open mode). |
cacbc350 RK |
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 | |
1732c156 | 82 | -- stored in the AFCB. |
cacbc350 | 83 | -- |
1732c156 | 84 | -- Amethod indicates the access method: |
cacbc350 RK |
85 | -- |
86 | -- D = Direct_IO | |
87 | -- Q = Sequential_IO | |
88 | -- S = Stream_IO | |
89 | -- T = Text_IO | |
90 | -- W = Wide_Text_IO | |
1732c156 | 91 | -- ??? Wide_Wide_Text_IO ??? |
cacbc350 RK |
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 | ||
e2baae4e | 102 | procedure Close (File_Ptr : access FCB.AFCB_Ptr); |
cacbc350 RK |
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 | |
e2baae4e TQ |
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). | |
cacbc350 | 111 | |
e2baae4e | 112 | procedure Delete (File_Ptr : access FCB.AFCB_Ptr); |
cacbc350 RK |
113 | -- The indicated file is unlinked |
114 | ||
e2baae4e | 115 | procedure Reset (File_Ptr : access FCB.AFCB_Ptr; Mode : FCB.File_Mode); |
0ae9f22f | 116 | -- The file is reset, and the mode changed as indicated |
cacbc350 | 117 | |
e2baae4e | 118 | procedure Reset (File_Ptr : access FCB.AFCB_Ptr); |
cacbc350 RK |
119 | -- The files is reset, and the mode is unchanged |
120 | ||
0ae9f22f | 121 | function Mode (File : FCB.AFCB_Ptr) return FCB.File_Mode; |
cacbc350 RK |
122 | -- Returns the mode as supplied by create, open or reset |
123 | ||
0ae9f22f | 124 | function Name (File : FCB.AFCB_Ptr) return String; |
cacbc350 RK |
125 | -- Returns the file name as supplied by Open or Create. Raises Use_Error |
126 | -- if used with temporary files or standard files. | |
127 | ||
0ae9f22f | 128 | function Form (File : FCB.AFCB_Ptr) return String; |
65a07a30 RD |
129 | -- Returns the form as supplied by create, open or reset The string is |
130 | -- normalized to all lower case letters. | |
cacbc350 | 131 | |
0ae9f22f | 132 | function Is_Open (File : FCB.AFCB_Ptr) return Boolean; |
cacbc350 RK |
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 | |
aa635439 | 144 | -- is done implicitly by Open. Chain_File is used for the special cases of |
cacbc350 RK |
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, | |
65a07a30 RD |
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). | |
cacbc350 RK |
151 | |
152 | procedure Check_File_Open (File : FCB.AFCB_Ptr); | |
65a07a30 RD |
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. | |
cacbc350 RK |
156 | |
157 | procedure Check_Read_Status (File : FCB.AFCB_Ptr); | |
65a07a30 RD |
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. | |
cacbc350 RK |
162 | |
163 | procedure Check_Write_Status (File : FCB.AFCB_Ptr); | |
65a07a30 RD |
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. | |
cacbc350 RK |
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); | |
65a07a30 RD |
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) | |
cacbc350 RK |
177 | |
178 | function Form_Boolean | |
179 | (Form : String; | |
180 | Keyword : String; | |
65a07a30 RD |
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. | |
cacbc350 RK |
187 | |
188 | function Form_Integer | |
189 | (Form : String; | |
190 | Keyword : String; | |
65a07a30 RD |
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. | |
cacbc350 RK |
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; | |
0ae9f22f | 221 | Siz : Interfaces.C_Streams.size_t; |
cacbc350 | 222 | Count : out Interfaces.C_Streams.size_t); |
65a07a30 RD |
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 | |
cacbc350 RK |
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); | |
65a07a30 RD |
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. | |
cacbc350 RK |
231 | |
232 | procedure Write_Buf | |
233 | (File : FCB.AFCB_Ptr; | |
234 | Buf : Address; | |
235 | Siz : Interfaces.C_Streams.size_t); | |
65a07a30 RD |
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. | |
cacbc350 RK |
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); | |
cacbc350 RK |
253 | pragma Inline (Mode); |
254 | ||
255 | end System.File_IO; |