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-- 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/>.                                          --
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
35with Interfaces.C_Streams;
36
37with System.File_Control_Block;
38
39package 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
250private
251   pragma Inline (Check_Read_Status);
252   pragma Inline (Check_Write_Status);
253   pragma Inline (Mode);
254
255end System.File_IO;
256