A.8.2 File Management
Static Semantics
{
AI12-0449-1}
The 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 := "");
{
AI95-00283-01}
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.
Ramification: {
AI12-0005-1}
For a direct file, the initial value of current index is 1 (see
A.8).
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.
Ramification: {
AI12-0005-1}
For a direct file, the initial value of current index is 1 (see
A.8).
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);
{
AI95-00085-01}
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;
{
AI95-00248-01}
Returns a string which uniquely identifies the external file currently
associated with the given file (and may thus be used in an Open operation).
Discussion: {
AI95-00248-01}
Retrieving the full path can be accomplished by passing the result of
Name to Directories.Full_Name (see
A.16).
It is important to drop the requirement on Name, as the only way to accomplish
this requirement given that the current directory can be changed with
package Directories is to store the full path when the file is opened.
That's expensive, and it's better for users that need the full path to
explicitly request it.
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;
{
AI05-0264-1}
Returns True if the file is open (that is, if it is associated with an
external file); otherwise, returns False.
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.
{
AI12-0021-1}
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.
Implementation Note: {
AI12-0021-1}
The expectation is that if one opens a file with this subpackage and
then requests the name with Name from this subpackage, the result will
include the same Wide_Characters that were used to open the file (rather
than some encoded form). Since file names are completely implementation-defined,
we cannot say this normatively. We have no expectations when retrieving
the name of a file opened with this package using the String Name. Similar
considerations apply to the nested package Wide_Wide_File_Names (see
below).
{
AI12-0021-1}
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
An 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
{
AI95-00085-01}
Clarified that Reset affects and depends on the external file.
{
AI95-00248-01}
Removed the requirement for Name to return a full path; this is now accomplished
by Directories.Full_Name(Name(File)) (see
A.16).
This is not documented as an inconsistency, because there is no requirement
for implementations to change — the Ada 95 behavior is still allowed,
it just is no longer required.
{
AI95-00283-01}
Added text to specify the default mode for a stream file.
Wording Changes from Ada 2012
{
AI12-0130-1}
Procedure Flush is now defined here, so it can be used for all of the
I/O packages.
{
AI12-0021-1}
The nested Wide_File_Names and Wide_Wide_File_Names packages are now
described here.
Ada 2005 and 2012 Editions sponsored in part by Ada-Europe
