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-2021, 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 with Default_Initial_Condition;
45   pragma Preelaborable_Initialization (File_Type);
46
47   type File_Mode is (In_File, Out_File, Append_File);
48
49   --  The following representation clause allows the use of unchecked
50   --  conversion for rapid translation between the File_Mode type
51   --  used in this package and System.File_IO.
52
53   for File_Mode use
54     (In_File     => 0,  -- System.File_IO.File_Mode'Pos (In_File)
55      Out_File    => 2,  -- System.File_IO.File_Mode'Pos (Out_File)
56      Append_File => 3); -- System.File_IO.File_Mode'Pos (Append_File)
57
58   type Count is new Stream_Element_Offset
59     range 0 .. Stream_Element_Offset'Last;
60
61   subtype Positive_Count is Count range 1 .. Count'Last;
62   --  Index into file, in stream elements
63
64   ---------------------
65   -- File Management --
66   ---------------------
67
68   procedure Create
69     (File : in out File_Type;
70      Mode : File_Mode := Out_File;
71      Name : String := "";
72      Form : String := "");
73
74   procedure Open
75     (File : in out File_Type;
76      Mode : File_Mode;
77      Name : String;
78      Form : String := "");
79
80   procedure Close  (File : in out File_Type);
81   procedure Delete (File : in out File_Type);
82   procedure Reset  (File : in out File_Type; Mode : File_Mode);
83   procedure Reset  (File : in out File_Type);
84
85   function Mode (File : File_Type) return File_Mode;
86   function Name (File : File_Type) return String;
87   function Form (File : File_Type) return String;
88
89   function Is_Open     (File : File_Type) return Boolean;
90   function End_Of_File (File : File_Type) return Boolean;
91
92   function Stream (File : File_Type) return Stream_Access;
93
94   -----------------------------
95   -- Input-Output Operations --
96   -----------------------------
97
98   procedure Read
99     (File : File_Type;
100      Item : out Stream_Element_Array;
101      Last : out Stream_Element_Offset;
102      From : Positive_Count);
103
104   procedure Read
105     (File : File_Type;
106      Item : out Stream_Element_Array;
107      Last : out Stream_Element_Offset);
108
109   procedure Write
110     (File : File_Type;
111      Item : Stream_Element_Array;
112      To   : Positive_Count);
113
114   procedure Write
115     (File : File_Type;
116      Item : Stream_Element_Array);
117
118   ----------------------------------------
119   -- Operations on Position within File --
120   ----------------------------------------
121
122   procedure Set_Index (File : File_Type; To : Positive_Count);
123
124   function Index (File : File_Type) return Positive_Count;
125   function Size  (File : File_Type) return Count;
126
127   procedure Set_Mode (File : in out File_Type; Mode : File_Mode);
128
129   --  Note: The parameter file is IN OUT in the RM, but this is clearly
130   --  an oversight, and was intended to be IN, see AI95-00057.
131
132   procedure Flush (File : File_Type);
133
134   ----------------
135   -- Exceptions --
136   ----------------
137
138   Status_Error : exception renames IO_Exceptions.Status_Error;
139   Mode_Error   : exception renames IO_Exceptions.Mode_Error;
140   Name_Error   : exception renames IO_Exceptions.Name_Error;
141   Use_Error    : exception renames IO_Exceptions.Use_Error;
142   Device_Error : exception renames IO_Exceptions.Device_Error;
143   End_Error    : exception renames IO_Exceptions.End_Error;
144   Data_Error   : exception renames IO_Exceptions.Data_Error;
145
146private
147
148   --  The following procedures have a File_Type formal of mode IN OUT because
149   --  they may close the original file. The Close operation may raise an
150   --  exception, but in that case we want any assignment to the formal to
151   --  be effective anyway, so it must be passed by reference (or the caller
152   --  will be left with a dangling pointer).
153
154   pragma Export_Procedure
155     (Internal  => Close,
156      External  => "",
157      Mechanism => Reference);
158   pragma Export_Procedure
159     (Internal  => Delete,
160      External  => "",
161      Mechanism => Reference);
162   pragma Export_Procedure
163     (Internal        => Reset,
164      External        => "",
165      Parameter_Types => (File_Type),
166      Mechanism       => Reference);
167   pragma Export_Procedure
168     (Internal        => Reset,
169      External        => "",
170      Parameter_Types => (File_Type, File_Mode),
171      Mechanism       => (File => Reference));
172   pragma Export_Procedure
173     (Internal  => Set_Mode,
174      External  => "",
175      Mechanism => (File => Reference));
176
177   package FCB renames System.File_Control_Block;
178
179   -----------------------------
180   -- Stream_IO Control Block --
181   -----------------------------
182
183   type Operation is (Op_Read, Op_Write, Op_Other);
184   --  Type used to record last operation (to optimize sequential operations)
185
186   type Stream_AFCB is new FCB.AFCB with record
187      Index : Count := 1;
188      --  Current Index value
189
190      File_Size : Stream_Element_Offset := -1;
191      --  Cached value of File_Size, so that we do not keep recomputing it
192      --  when not necessary (otherwise End_Of_File becomes gruesomely slow).
193      --  A value of minus one means that there is no cached value.
194
195      Last_Op : Operation := Op_Other;
196      --  Last operation performed on file, used to avoid unnecessary
197      --  repositioning between successive read or write operations.
198
199      Update_Mode : Boolean := False;
200      --  Set if the mode is changed from write to read or vice versa.
201      --  Indicates that the file has been reopened in update mode.
202
203   end record;
204
205   type File_Type is access all Stream_AFCB;
206
207   overriding function AFCB_Allocate
208     (Control_Block : Stream_AFCB) return FCB.AFCB_Ptr;
209
210   overriding procedure AFCB_Close (File : not null access Stream_AFCB);
211   overriding procedure AFCB_Free  (File : not null access Stream_AFCB);
212
213   overriding procedure Read
214     (File : in out Stream_AFCB;
215      Item : out Ada.Streams.Stream_Element_Array;
216      Last : out Ada.Streams.Stream_Element_Offset);
217   --  Read operation used when Stream_IO file is treated directly as Stream
218
219   overriding procedure Write
220     (File : in out Stream_AFCB;
221      Item : Ada.Streams.Stream_Element_Array);
222   --  Write operation used when Stream_IO file is treated directly as Stream
223
224end Ada.Streams.Stream_IO;
225