A.8 Sequential and Direct Files
This Reference Manual output has not been verified, and may contain omissions or errors. Report any problems on the tracking issue
Static Semantics
1/2Two kinds of access to external files are defined in this subclause: sequential access and direct access. The corresponding file types and the associated operations are provided by the generic packages Sequential_IO and Direct_IO. A file object to be used for sequential access is called a sequential file, and one to be used for direct access is called a direct file. Access to stream files is described in A.12.1.
For sequential access, the file is viewed as a sequence of values that are transferred in the order of their appearance (as produced by the program or by the external environment). When the file is opened with mode In_File or Out_File, transfer starts respectively from or to the beginning of the file. When the file is opened with mode Append_File, transfer to the file starts after the last element of the file.
For direct access, the file is viewed as a set of elements occupying consecutive positions in linear order; a value can be transferred to or from an element of the file at any selected position. The position of an element is specified by its index, which is a number, greater than zero, of the implementation-defined integer type Count. The first element, if any, has index one; the index of the last element, if any, is called the current size; the current size is zero if there are no elements. The current size is a property of the external file.
An open direct file has a current index, which is the index that will be used by the next read or write operation. When a direct file is opened, the current index is set to one. The current index of a direct file is a property of a file object, not of an external file.
Wording Changes from Ada 95
A.8.1 The Generic Package Sequential_IO
Static Semantics
1The generic library package Sequential_IO has the following declaration:
with Ada.IO_Exceptions;
generic
type Element_Type(<>) is private;
package Ada.Sequential_IO
with Global => in out synchronized is
3type File_Type is limited private;
4type File_Mode is (In_File, Out_File, Append_File);
5-- File management
6procedure Create(File : in out File_Type;
Mode : in File_Mode := Out_File;
Name : in String := "";
Form : in String := "");
7procedure Open (File : in out File_Type;
Mode : in File_Mode;
Name : in String;
Form : in String := "");
8procedure Close (File : in out File_Type);
procedure Delete(File : in out File_Type);
procedure Reset (File : in out File_Type; Mode : in File_Mode);
procedure Reset (File : in out File_Type);
9function Mode (File : in File_Type) return File_Mode;
function Name (File : in File_Type) return String;
function Form (File : in File_Type) return String;
10function Is_Open(File : in File_Type) return Boolean;
10.1/5procedure Flush (File : in File_Type)
with Global => overriding in out File;
11-- Input and output operations
12/5procedure Read (File : in File_Type; Item : out Element_Type)
with Global => overriding in out File;
procedure Write (File : in File_Type; Item : in Element_Type)
with Global => overriding in out File;
13function End_Of_File(File : in File_Type) return Boolean;
14-- Exceptions
15Status_Error : exception renames IO_Exceptions.Status_Error;
Mode_Error : exception renames IO_Exceptions.Mode_Error;
Name_Error : exception renames IO_Exceptions.Name_Error;
Use_Error : exception renames IO_Exceptions.Use_Error;
Device_Error : exception renames IO_Exceptions.Device_Error;
End_Error : exception renames IO_Exceptions.End_Error;
Data_Error : exception renames IO_Exceptions.Data_Error;
15.1/5package Wide_File_Names is
15.2/5-- File management
15.3/5procedure Create(File : in out File_Type;
Mode : in File_Mode := Out_File;
Name : in Wide_String := "";
Form : in Wide_String := "");
15.4/5procedure Open (File : in out File_Type;
Mode : in File_Mode;
Name : in Wide_String;
Form : in Wide_String := "");
15.5/5function Name (File : in File_Type) return Wide_String;
15.6/5function Form (File : in File_Type) return Wide_String;
15.7/5end Wide_File_Names;
15.8/5package Wide_Wide_File_Names is
15.9/5-- File management
15.10/5procedure Create(File : in out File_Type;
Mode : in File_Mode := Out_File;
Name : in Wide_Wide_String := "";
Form : in Wide_Wide_String := "");
15.11/5procedure Open (File : in out File_Type;
Mode : in File_Mode;
Name : in Wide_Wide_String;
Form : in Wide_Wide_String := "");
15.12/5function Name (File : in File_Type) return Wide_Wide_String;
15.13/5function Form (File : in File_Type) return Wide_Wide_String;
15.14/5end Wide_Wide_File_Names;
16private
... -- not specified by the language
end Ada.Sequential_IO;
17/2The type File_Type needs finalization (see 7.6) in every instantiation of Sequential_IO.
Incompatibilities With Ada 83
Incompatibilities With Ada 95
Incompatibilities With Ada 2012
A.8.2 File Management
Static Semantics
1/5The procedures and functions described in this subclause provide for the control of external files; their declarations are repeated in each of the packages for sequential, direct, text, and stream input-output. For text input-output, the procedures Create, Open, and Reset have additional effects described in A.10.2.
procedure Create(File : in out File_Type;
Mode : in File_Mode := default_mode;
Name : in String := "";
Form : in String := "");
Establishes a new external file, with the given name and form, and associates this external file with the given file. The given file is left open. The current mode of the given file is set to the given access mode. The default access mode is the mode Out_File for sequential, stream, and text input-output; it is the mode Inout_File for direct input-output. For direct access, the size of the created file is implementation defined.
A null string for Name specifies an external file that is not accessible after the completion of the main program (a temporary file). A null string for Form specifies the use of the default options of the implementation for the external file.
The exception Status_Error is propagated if the given file is already open. The exception Name_Error is propagated if the string given as Name does not allow the identification of an external file. The exception Use_Error is propagated if, for the specified mode, the external environment does not support creation of an external file with the given name (in the absence of Name_Error) and form.
procedure Open(File : in out File_Type;
Mode : in File_Mode;
Name : in String;
Form : in String := "");
Associates the given file with an existing external file having the given name and form, and sets the current mode of the given file to the given mode. The given file is left open.
The exception Status_Error is propagated if the given file is already open. The exception Name_Error is propagated if the string given as Name does not allow the identification of an external file; in particular, this exception is propagated if no external file with the given name exists. The exception Use_Error is propagated if, for the specified mode, the external environment does not support opening for an external file with the given name (in the absence of Name_Error) and form.
procedure Close(File : in out File_Type);
Severs the association between the given file and its associated external file. The given file is left closed. In addition, for sequential files, if the file being closed has mode Out_File or Append_File, then the last element written since the most recent open or reset is the last element that can be read from the file. If no elements have been written and the file mode is Out_File, then the closed file is empty. If no elements have been written and the file mode is Append_File, then the closed file is unchanged.
The exception Status_Error is propagated if the given file is not open.
procedure Delete(File : in out File_Type);
Deletes the external file associated with the given file. The given file is closed, and the external file ceases to exist.
The exception Status_Error is propagated if the given file is not open. The exception Use_Error is propagated if deletion of the external file is not supported by the external environment.
procedure Reset(File : in out File_Type; Mode : in File_Mode);
procedure Reset(File : in out File_Type);
Resets the given file so that reading from its elements can be restarted from the beginning of the external file (for modes In_File and Inout_File), and so that writing to its elements can be restarted at the beginning of the external file (for modes Out_File and Inout_File) or after the last element of the external file (for mode Append_File). In particular, for direct access this means that the current index is set to one. If a Mode parameter is supplied, the current mode of the given file is set to the given mode. In addition, for sequential files, if the given file has mode Out_File or Append_File when Reset is called, the last element written since the most recent open or reset is the last element that can be read from the external file. If no elements have been written and the file mode is Out_File, the reset file is empty. If no elements have been written and the file mode is Append_File, then the reset file is unchanged.
The exception Status_Error is propagated if the file is not open. The exception Use_Error is propagated if the external environment does not support resetting for the external file and, also, if the external environment does not support resetting to the specified mode for the external file.
function Mode(File : in File_Type) return File_Mode;
Returns the current mode of the given file.
The exception Status_Error is propagated if the file is not open.
function Name(File : in File_Type) return String;
Returns a string which uniquely identifies the external file currently associated with the given file (and may thus be used in an Open operation).
The exception Status_Error is propagated if the given file is not open. The exception Use_Error is propagated if the associated external file is a temporary file that cannot be opened by any name.
function Form(File : in File_Type) return String;
Returns the form string for the external file currently associated with the given file. If an external environment allows alternative specifications of the form (for example, abbreviations using default options), the string returned by the function should correspond to a full specification (that is, it should indicate explicitly all options selected, including default options).
The exception Status_Error is propagated if the given file is not open.
function Is_Open(File : in File_Type) return Boolean;
Returns True if the file is open (that is, if it is associated with an external file); otherwise, returns False.
procedure Flush(File : in File_Type);
The Flush procedure synchronizes the external file with the internal file (by flushing any internal buffers) without closing the file. For a direct file, the current index is unchanged; for a stream file (see A.12.1), the current position is unchanged.
The exception Status_Error is propagated if the file is not open. The exception Mode_Error is propagated if the mode of the file is In_File.
The nested package Wide_File_Names provides operations equivalent to the operations of the same name of the outer package except that Wide_String is used instead of String for the name and form of the external file.
The nested package Wide_Wide_File_Names provides operations equivalent to the operations of the same name of the outer package except that Wide_Wide_String is used instead of String for the name and form of the external file.
Implementation Permissions
29An implementation may propagate Name_Error or Use_Error if an attempt is made to use an I/O feature that cannot be supported by the implementation due to limitations in the external environment. Any such restriction should be documented.
Wording Changes from Ada 95
Wording Changes from Ada 2012
A.8.3 Sequential Input-Output Operations
Static Semantics
1The operations available for sequential input and output are described in this subclause. The exception Status_Error is propagated if any of these operations is attempted for a file that is not open.
procedure Read(File : in File_Type; Item : out Element_Type);
Operates on a file of mode In_File. Reads an element from the given file, and returns the value of this element in the Item parameter.
The exception Mode_Error is propagated if the mode is not In_File. The exception End_Error is propagated if no more elements can be read from the given file. The exception Data_Error can be propagated if the element read cannot be interpreted as a value of the subtype Element_Type (see A.13, “Exceptions in Input-Output”).
procedure Write(File : in File_Type; Item : in Element_Type);
Operates on a file of mode Out_File or Append_File. Writes the value of Item to the given file.
The exception Mode_Error is propagated if the mode is not Out_File or Append_File. The exception Use_Error is propagated if the capacity of the external file is exceeded.
function End_Of_File(File : in File_Type) return Boolean;
Operates on a file of mode In_File. Returns True if no more elements can be read from the given file; otherwise, returns False.
The exception Mode_Error is propagated if the mode is not In_File.
A.8.4 The Generic Package Direct_IO
Static Semantics
1The generic library package Direct_IO has the following declaration:
with Ada.IO_Exceptions;
generic
type Element_Type is private;
package Ada.Direct_IO
with Global => in out synchronized is
3type File_Type is limited private;
4type File_Mode is (In_File, Inout_File, Out_File);
type Count is range 0 .. implementation-defined;
subtype Positive_Count is Count range 1 .. Count'Last;
5-- File management
6procedure Create(File : in out File_Type;
Mode : in File_Mode := Inout_File;
Name : in String := "";
Form : in String := "");
7procedure Open (File : in out File_Type;
Mode : in File_Mode;
Name : in String;
Form : in String := "");
8procedure Close (File : in out File_Type);
procedure Delete(File : in out File_Type);
procedure Reset (File : in out File_Type; Mode : in File_Mode);
procedure Reset (File : in out File_Type);
9function Mode (File : in File_Type) return File_Mode;
function Name (File : in File_Type) return String;
function Form (File : in File_Type) return String;
10function Is_Open(File : in File_Type) return Boolean;
10.1/5procedure Flush (File : in File_Type)
with Global => overriding in out File;
11-- Input and output operations
12/5procedure Read (File : in File_Type; Item : out Element_Type;
From : in Positive_Count)
with Global => overriding in out File;
procedure Read (File : in File_Type; Item : out Element_Type)
with Global => overriding in out File;
13/5procedure Write(File : in File_Type; Item : in Element_Type;
To : in Positive_Count)
with Global => overriding in out File;
procedure Write(File : in File_Type; Item : in Element_Type)
with Global => overriding in out File;
14/5procedure Set_Index(File : in File_Type; To : in Positive_Count)
with Global => overriding in out File;
15function Index(File : in File_Type) return Positive_Count;
function Size (File : in File_Type) return Count;
16function End_Of_File(File : in File_Type) return Boolean;
17-- Exceptions
18Status_Error : exception renames IO_Exceptions.Status_Error;
Mode_Error : exception renames IO_Exceptions.Mode_Error;
Name_Error : exception renames IO_Exceptions.Name_Error;
Use_Error : exception renames IO_Exceptions.Use_Error;
Device_Error : exception renames IO_Exceptions.Device_Error;
End_Error : exception renames IO_Exceptions.End_Error;
Data_Error : exception renames IO_Exceptions.Data_Error;
18.1/5package Wide_File_Names is
18.2/5-- File management
18.3/5procedure Create(File : in out File_Type;
Mode : in File_Mode := Inout_File;
Name : in Wide_String := "";
Form : in Wide_String := "");
18.4/5procedure Open (File : in out File_Type;
Mode : in File_Mode;
Name : in Wide_String;
Form : in Wide_String := "");
18.5/5function Name (File : in File_Type) return Wide_String;
18.6/5function Form (File : in File_Type) return Wide_String;
18.7/5end Wide_File_Names;
18.8/5package Wide_Wide_File_Names is
18.9/5-- File management
18.10/5procedure Create(File : in out File_Type;
Mode : in File_Mode := Inout_File;
Name : in Wide_Wide_String := "";
Form : in Wide_Wide_String := "");
18.11/5procedure Open (File : in out File_Type;
Mode : in File_Mode;
Name : in Wide_Wide_String;
Form : in Wide_Wide_String := "");
18.12/5function Name (File : in File_Type) return Wide_Wide_String;
18.13/5function Form (File : in File_Type) return Wide_Wide_String;
18.14/5end Wide_Wide_File_Names;
19private
... -- not specified by the language
end Ada.Direct_IO;
unknown_discriminant_part
(unlike Sequential_IO) so that the implementation can make use of the ability to declare uninitialized variables of the type. The type File_Type needs finalization (see 7.6) in every instantiation of Direct_IO.
Incompatibilities With Ada 95
Incompatibilities With Ada 2012
A.8.5 Direct Input-Output Operations
Static Semantics
1The operations available for direct input and output are described in this subclause. The exception Status_Error is propagated if any of these operations is attempted for a file that is not open.
procedure Read(File : in File_Type; Item : out Element_Type;
From : in Positive_Count);
procedure Read(File : in File_Type; Item : out Element_Type);
Operates on a file of mode In_File or Inout_File. In the case of the first form, sets the current index of the given file to the index value given by the parameter From. Then (for both forms) returns, in the parameter Item, the value of the element whose position in the given file is specified by the current index of the file; finally, increases the current index by one.
The exception Mode_Error is propagated if the mode of the given file is Out_File. The exception End_Error is propagated if the index to be used exceeds the size of the external file. The exception Data_Error can be propagated if the element read cannot be interpreted as a value of the subtype Element_Type (see A.13).
procedure Write(File : in File_Type; Item : in Element_Type;
To : in Positive_Count);
procedure Write(File : in File_Type; Item : in Element_Type);
Operates on a file of mode Inout_File or Out_File. In the case of the first form, sets the index of the given file to the index value given by the parameter To. Then (for both forms) gives the value of the parameter Item to the element whose position in the given file is specified by the current index of the file; finally, increases the current index by one.
The exception Mode_Error is propagated if the mode of the given file is In_File. The exception Use_Error is propagated if the capacity of the external file is exceeded.
procedure Set_Index(File : in File_Type; To : in Positive_Count);
Operates on a file of any mode. Sets the current index of the given file to the given index value (which may exceed the current size of the file).
function Index(File : in File_Type) return Positive_Count;
Operates on a file of any mode. Returns the current index of the given file.
function Size(File : in File_Type) return Count;
Operates on a file of any mode. Returns the current size of the external file that is associated with the given file.
function End_Of_File(File : in File_Type) return Boolean;
Operates on a file of mode In_File or Inout_File. Returns True if the current index exceeds the size of the external file; otherwise, returns False.
The exception Mode_Error is propagated if the mode of the given file is Out_File.