File : a-ststio.ads
1 ------------------------------------------------------------------------------
2 -- --
3 -- GNAT RUN-TIME COMPONENTS --
4 -- --
5 -- A D A . S T R E A M S . S T R E A M _ I O --
6 -- --
7 -- S p e c --
8 -- --
9 -- Copyright (C) 1992-2012, Free Software Foundation, Inc. --
10 -- --
11 -- This specification is derived from the Ada Reference Manual for use with --
12 -- GNAT. The copyright notice above, and the license provisions that follow --
13 -- apply solely to the contents of the part following the private keyword. --
14 -- --
15 -- GNAT is free software; you can redistribute it and/or modify it under --
16 -- terms of the GNU General Public License as published by the Free Soft- --
17 -- ware Foundation; either version 3, or (at your option) any later ver- --
18 -- sion. GNAT is distributed in the hope that it will be useful, but WITH- --
19 -- OUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY --
20 -- or FITNESS FOR A PARTICULAR PURPOSE. --
21 -- --
22 -- --
23 -- --
24 -- --
25 -- --
26 -- You should have received a copy of the GNU General Public License and --
27 -- a copy of the GCC Runtime Library Exception along with this program; --
28 -- see the files COPYING3 and COPYING.RUNTIME respectively. If not, see --
29 -- <http://www.gnu.org/licenses/>. --
30 -- --
31 -- GNAT was originally developed by the GNAT team at New York University. --
32 -- Extensive contributions were provided by Ada Core Technologies Inc. --
33 -- --
34 ------------------------------------------------------------------------------
35
36 with Ada.IO_Exceptions;
37 with System.File_Control_Block;
38
39 package Ada.Streams.Stream_IO is
40 pragma Preelaborate;
41
42 type Stream_Access is access all Root_Stream_Type'Class;
43
44 type File_Type is limited private;
45
46 type File_Mode is (In_File, Out_File, Append_File);
47
48 -- The following representation clause allows the use of unchecked
49 -- conversion for rapid translation between the File_Mode type
50 -- used in this package and System.File_IO.
51
52 for File_Mode use
53 (In_File => 0, -- System.File_IO.File_Mode'Pos (In_File)
54 Out_File => 2, -- System.File_IO.File_Mode'Pos (Out_File)
55 Append_File => 3); -- System.File_IO.File_Mode'Pos (Append_File)
56
57 type Count is new Stream_Element_Offset
58 range 0 .. Stream_Element_Offset'Last;
59
60 subtype Positive_Count is Count range 1 .. Count'Last;
61 -- Index into file, in stream elements
62
63 ---------------------
64 -- File Management --
65 ---------------------
66
67 procedure Create
68 (File : in out File_Type;
69 Mode : File_Mode := Out_File;
70 Name : String := "";
71 Form : String := "");
72
73 procedure Open
74 (File : in out File_Type;
75 Mode : File_Mode;
76 Name : String;
77 Form : String := "");
78
79 procedure Close (File : in out File_Type);
80 procedure Delete (File : in out File_Type);
81 procedure Reset (File : in out File_Type; Mode : File_Mode);
82 procedure Reset (File : in out File_Type);
83
84 function Mode (File : File_Type) return File_Mode;
85 function Name (File : File_Type) return String;
86 function Form (File : File_Type) return String;
87
88 function Is_Open (File : File_Type) return Boolean;
89 function End_Of_File (File : File_Type) return Boolean;
90
91 function Stream (File : File_Type) return Stream_Access;
92
93 -----------------------------
94 -- Input-Output Operations --
95 -----------------------------
96
97 procedure Read
98 (File : File_Type;
99 Item : out Stream_Element_Array;
100 Last : out Stream_Element_Offset;
101 From : Positive_Count);
102
103 procedure Read
104 (File : File_Type;
105 Item : out Stream_Element_Array;
106 Last : out Stream_Element_Offset);
107
108 procedure Write
109 (File : File_Type;
110 Item : Stream_Element_Array;
111 To : Positive_Count);
112
113 procedure Write
114 (File : File_Type;
115 Item : Stream_Element_Array);
116
117 ----------------------------------------
118 -- Operations on Position within File --
119 ----------------------------------------
120
121 procedure Set_Index (File : File_Type; To : Positive_Count);
122
123 function Index (File : File_Type) return Positive_Count;
124 function Size (File : File_Type) return Count;
125
126 procedure Set_Mode (File : in out File_Type; Mode : File_Mode);
127
128 -- Note: The parameter file is IN OUT in the RM, but this is clearly
129 -- an oversight, and was intended to be IN, see AI95-00057.
130
131 procedure Flush (File : File_Type);
132
133 ----------------
134 -- Exceptions --
135 ----------------
136
137 Status_Error : exception renames IO_Exceptions.Status_Error;
138 Mode_Error : exception renames IO_Exceptions.Mode_Error;
139 Name_Error : exception renames IO_Exceptions.Name_Error;
140 Use_Error : exception renames IO_Exceptions.Use_Error;
141 Device_Error : exception renames IO_Exceptions.Device_Error;
142 End_Error : exception renames IO_Exceptions.End_Error;
143 Data_Error : exception renames IO_Exceptions.Data_Error;
144
145 private
146
147 -- The following procedures have a File_Type formal of mode IN OUT because
148 -- they may close the original file. The Close operation may raise an
149 -- exception, but in that case we want any assignment to the formal to
150 -- be effective anyway, so it must be passed by reference (or the caller
151 -- will be left with a dangling pointer).
152
153 pragma Export_Procedure
154 (Internal => Close,
155 External => "",
156 Mechanism => Reference);
157 pragma Export_Procedure
158 (Internal => Delete,
159 External => "",
160 Mechanism => Reference);
161 pragma Export_Procedure
162 (Internal => Reset,
163 External => "",
164 Parameter_Types => (File_Type),
165 Mechanism => Reference);
166 pragma Export_Procedure
167 (Internal => Reset,
168 External => "",
169 Parameter_Types => (File_Type, File_Mode),
170 Mechanism => (File => Reference));
171 pragma Export_Procedure
172 (Internal => Set_Mode,
173 External => "",
174 Mechanism => (File => Reference));
175
176 package FCB renames System.File_Control_Block;
177
178 -----------------------------
179 -- Stream_IO Control Block --
180 -----------------------------
181
182 type Operation is (Op_Read, Op_Write, Op_Other);
183 -- Type used to record last operation (to optimize sequential operations)
184
185 type Stream_AFCB is new FCB.AFCB with record
186 Index : Count := 1;
187 -- Current Index value
188
189 File_Size : Stream_Element_Offset := -1;
190 -- Cached value of File_Size, so that we do not keep recomputing it
191 -- when not necessary (otherwise End_Of_File becomes gruesomely slow).
192 -- A value of minus one means that there is no cached value.
193
194 Last_Op : Operation := Op_Other;
195 -- Last operation performed on file, used to avoid unnecessary
196 -- repositioning between successive read or write operations.
197
198 Update_Mode : Boolean := False;
199 -- Set if the mode is changed from write to read or vice versa.
200 -- Indicates that the file has been reopened in update mode.
201
202 end record;
203
204 type File_Type is access all Stream_AFCB;
205
206 overriding function AFCB_Allocate
207 (Control_Block : Stream_AFCB) return FCB.AFCB_Ptr;
208
209 overriding procedure AFCB_Close (File : not null access Stream_AFCB);
210 overriding procedure AFCB_Free (File : not null access Stream_AFCB);
211
212 overriding procedure Read
213 (File : in out Stream_AFCB;
214 Item : out Ada.Streams.Stream_Element_Array;
215 Last : out Ada.Streams.Stream_Element_Offset);
216 -- Read operation used when Stream_IO file is treated directly as Stream
217
218 overriding procedure Write
219 (File : in out Stream_AFCB;
220 Item : Ada.Streams.Stream_Element_Array);
221 -- Write operation used when Stream_IO file is treated directly as Stream
222
223 end Ada.Streams.Stream_IO;