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-- As a special exception under Section 7 of GPL version 3, you are granted --
23-- additional permissions described in the GCC Runtime Library Exception,   --
24-- version 3.1, as published by the Free Software Foundation.               --
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
36with Ada.IO_Exceptions;
37with System.File_Control_Block;
38
39package 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
145private
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
223end Ada.Streams.Stream_IO;
224