A.16 The Package Directories
The package Directories provides operations for manipulating
files and directories, and their names.
Static Semantics
The library package
Directories has the following declaration:
with Ada.IO_Exceptions;
with Ada.Calendar;
package Ada.Directories
with Global =>
in out synchronized is
-- Directory and file operations:
function Current_Directory
return String;
procedure Set_Directory (Directory : in String);
procedure Create_Directory (New_Directory :
in String;
Form :
in String := "");
procedure Delete_Directory (Directory :
in String);
procedure Create_Path (New_Directory :
in String;
Form :
in String := "");
procedure Delete_Tree (Directory :
in String);
procedure Delete_File (Name :
in String);
procedure Rename (Old_Name, New_Name :
in String);
procedure Copy_File (Source_Name,
Target_Name :
in String;
Form :
in String := "");
-- File and directory name operations:
function Full_Name (Name :
in String)
return String
with Nonblocking;
function Simple_Name (Name :
in String)
return String
with Nonblocking;
function Containing_Directory (Name :
in String)
return String
with Nonblocking;
function Extension (Name :
in String)
return String
with Nonblocking;
function Base_Name (Name :
in String)
return String
with Nonblocking;
function Compose (Containing_Directory :
in String := "";
Name :
in String;
Extension :
in String := "")
return String
with Nonblocking;
type Name_Case_Kind
is
(Unknown, Case_Sensitive, Case_Insensitive, Case_Preserving);
function Name_Case_Equivalence (Name :
in String)
return Name_Case_Kind;
-- File and directory queries:
type File_Kind
is (Directory, Ordinary_File, Special_File);
type File_Size
is range 0 ..
implementation-defined;
function Exists (Name :
in String)
return Boolean;
function Kind (Name :
in String)
return File_Kind;
function Size (Name :
in String)
return File_Size;
function Modification_Time (Name :
in String)
return Ada.Calendar.Time;
-- Directory searching:
type Directory_Entry_Type
is limited private;
type Filter_Type
is array (File_Kind)
of Boolean;
type Search_Type
is limited private;
procedure Start_Search (Search :
in out Search_Type;
Directory :
in String;
Pattern :
in String;
Filter :
in Filter_Type := (
others => True));
procedure End_Search (Search :
in out Search_Type);
function More_Entries (Search :
in Search_Type)
return Boolean;
procedure Get_Next_Entry (Search :
in out Search_Type;
Directory_Entry :
out Directory_Entry_Type);
procedure Search (
Directory : in String;
Pattern : in String;
Filter : in Filter_Type := (others => True);
Process : not null access procedure (
Directory_Entry : in Directory_Entry_Type))
with Allows_Exit;
-- Operations on Directory Entries:
function Simple_Name (Directory_Entry :
in Directory_Entry_Type)
return String;
function Full_Name (Directory_Entry :
in Directory_Entry_Type)
return String;
function Kind (Directory_Entry :
in Directory_Entry_Type)
return File_Kind;
function Size (Directory_Entry :
in Directory_Entry_Type)
return File_Size;
function Modification_Time (Directory_Entry :
in Directory_Entry_Type)
return Ada.Calendar.Time;
Status_Error :
exception renames Ada.IO_Exceptions.Status_Error;
Name_Error :
exception renames Ada.IO_Exceptions.Name_Error;
Use_Error :
exception renames Ada.IO_Exceptions.Use_Error;
Device_Error :
exception renames Ada.IO_Exceptions.Device_Error;
private
... -- not specified by the language
end Ada.Directories;
External files may be classified as directories,
special files, or ordinary files. A
directory is an external file
that is a container for files on the target system. A
special file
is an external file that cannot be created or read by a predefined Ada
input-output package. External files that are not special files or directories
are called
ordinary files.
A
file name is a string identifying an external
file. Similarly, a
directory name is a string identifying a directory.
The interpretation of file names and directory names is implementation
defined.
The
full name of an external file is a full
specification of the name of the file. If the external environment allows
alternative specifications of the name (for example, abbreviations),
the full name should not use such alternatives. A full name typically
will include the names of all of the directories that contain the item.
The
simple name of an external file is the name of the item, not
including any containing directory names. Unless otherwise specified,
a file name or directory name parameter in a call to a predefined Ada
input-output subprogram can be a full name, a simple name, or any other
form of name supported by the implementation.
A
root directory is a directory that has
no containing directory.
The
default directory is the directory that
is used if a directory or file name is not a full name (that is, when
the name does not fully identify all of the containing directories).
A
directory entry is a single item in a directory,
identifying a single external file (including directories and special
files).
For each function that returns a string, the lower
bound of the returned value is 1.
The following file
and directory operations are provided:
function Current_Directory return String;
Returns the full
directory name for the current default directory. The name returned shall
be suitable for a future call to Set_Directory. The exception Use_Error
is propagated if a default directory is not supported by the external
environment.
procedure Set_Directory (Directory : in String);
Sets the current
default directory. The exception Name_Error is propagated if the string
given as Directory does not identify an existing directory. The exception
Use_Error is propagated if the external environment does not support
making Directory (in the absence of Name_Error) a default directory.
procedure Create_Directory (New_Directory : in String;
Form : in String := "");
Creates a directory
with name New_Directory. The Form parameter can be used to give system-dependent
characteristics of the directory; the interpretation of the Form parameter
is implementation defined. A null string for Form specifies the use of
the default options of the implementation of the new directory. The exception
Name_Error is propagated if the string given as New_Directory does not
allow the identification of a directory. The exception Use_Error is propagated
if the external environment does not support the creation of a directory
with the given name (in the absence of Name_Error) and form.
procedure Delete_Directory (Directory : in String);
Deletes an existing
empty directory with name Directory. The exception Name_Error is propagated
if the string given as Directory does not identify an existing directory.
The exception Use_Error is propagated if the directory is not empty or
the external environment does not support the deletion of the directory
with the given name (in the absence of Name_Error).
procedure Create_Path (New_Directory : in String;
Form : in String := "");
Creates zero or
more directories with name New_Directory. Each nonexistent directory
named by New_Directory is created. For example, on a typical Unix system,
Create_Path ("/usr/me/my"); would create directory "me"
in directory "usr", then create directory "my" in
directory "me". The Form parameter can be used to give system-dependent
characteristics of the directory; the interpretation of the Form parameter
is implementation defined. A null string for Form specifies the use of
the default options of the implementation of the new directory. The exception
Name_Error is propagated if the string given as New_Directory does not
allow the identification of any directory. The exception Use_Error is
propagated if the external environment does not support the creation
of any directories with the given name (in the absence of Name_Error)
and form. If Use_Error is propagated, it is unspecified whether a portion
of the directory path is created.
procedure Delete_Tree (Directory : in String);
Deletes an existing
directory with name Directory. The directory and all of its contents
(possibly including other directories) are deleted. The exception Name_Error
is propagated if the string given as Directory does not identify an existing
directory. The exception Use_Error is propagated if the external environment
does not support the deletion of the directory or some portion of its
contents with the given name (in the absence of Name_Error). If Use_Error
is propagated, it is unspecified whether a portion of the contents of
the directory is deleted.
procedure Delete_File (Name : in String);
Deletes an existing
ordinary or special file with name Name. The exception Name_Error is
propagated if the string given as Name does not identify an existing
ordinary or special external file. The exception Use_Error is propagated
if the external environment does not support the deletion of the file
with the given name (in the absence of Name_Error).
procedure Rename (Old_Name, New_Name : in String);
Renames an existing
external file (including directories) with name Old_Name to New_Name.
The exception Name_Error is propagated if the string given as Old_Name
does not identify an existing external file or if the string given as
New_Name does not allow the identification of an external file. The exception
Use_Error is propagated if the external environment does not support
the renaming of the file with the given name (in the absence of Name_Error).
In particular, Use_Error is propagated if a file or directory already
exists with name New_Name.
procedure Copy_File (Source_Name,
Target_Name : in String;
Form : in String := "");
Copies the contents
of the existing external file with name Source_Name to an external file
with name Target_Name. The resulting external file is a duplicate of
the source external file. The Form parameter can be used to give system-dependent
characteristics of the resulting external file; the interpretation of
the Form parameter is implementation defined. Exception Name_Error is
propagated if the string given as Source_Name does not identify an existing
external ordinary or special file, or if the string given as Target_Name
does not allow the identification of an external file. The exception
Use_Error is propagated if the external environment does not support
creating the file with the name given by Target_Name and form given by
Form, or copying of the file with the name given by Source_Name (in the
absence of Name_Error). If Use_Error is propagated, it is unspecified
whether a portion of the file is copied.
The following file
and directory name operations are provided:
function Full_Name (Name : in String) return String;
Returns the full
name corresponding to the file name specified by Name. The exception
Name_Error is propagated if the string given as Name does not allow the
identification of an external file (including directories and special
files).
function Simple_Name (Name : in String) return String;
Returns the simple
name portion of the file name specified by Name. The simple name of a
root directory is a name of the root itself. The exception Name_Error
is propagated if the string given as Name does not allow the identification
of an external file (including directories and special files).
function Containing_Directory (Name : in String) return String;
Returns the name
of the containing directory of the external file (including directories)
identified by Name. (If more than one directory can contain Name, the
directory name returned is implementation defined.) 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 the external
file does not have a containing directory.
function Extension (Name : in String) return String;
Returns the extension
name corresponding to Name. The extension name is a portion of a simple
name (not including any separator characters), typically used to identify
the file class. If the external environment does not have extension names,
then the null string is returned. The exception Name_Error is propagated
if the string given as Name does not allow the identification of an external
file.
function Base_Name (Name : in String) return String;
Returns the base
name corresponding to Name. The base name is the remainder of a simple
name after removing any extension and extension separators. The exception
Name_Error is propagated if the string given as Name does not allow the
identification of an external file (including directories and special
files).
function Compose (Containing_Directory : in String := "";
Name : in String;
Extension : in String := "") return String;
Returns the name
of the external file with the specified Containing_Directory, Name, and
Extension. If Extension is the null string, then Name is interpreted
as a simple name; otherwise, Name is interpreted as a base name. The
exception Name_Error is propagated if:
the string given as Containing_Directory
is not null and does not allow the identification of a directory;
the string given as Extension is not null
and is not a possible extension;
the string given as Name is not a possible
simple name (if Extension is null) or base name (if Extension is nonnull);
or
the string given as Name is a root directory,
and Containing_Directory or Extension is nonnull.
function Name_Case_Equivalence (Name : in String) return Name_Case_Kind;
Returns the file name equivalence rule for the
directory containing Name. Raises Name_Error if Name is not a full name.
Returns Case_Sensitive if file names that differ only in the case of
letters are considered different names. If file names that differ only
in the case of letters are considered the same name, then Case_Preserving
is returned if names have the case of the file name used when a file
is created; and Case_Insensitive is returned otherwise. Returns Unknown
if the file name equivalence is not known.
The following file
and directory queries and types are provided:
type File_Kind is (Directory, Ordinary_File, Special_File);
The type File_Kind
represents the kind of file represented by an external file or directory.
type File_Size is range 0 .. implementation-defined;
The type File_Size
represents the size of an external file.
function Exists (Name : in String) return Boolean;
Returns True if
an external file represented by Name exists, and False otherwise. The
exception Name_Error is propagated if the string given as Name does not
allow the identification of an external file (including directories and
special files).
function Kind (Name : in String) return File_Kind;
Returns the kind
of external file represented by Name. The exception Name_Error is propagated
if the string given as Name does not allow the identification of an existing
external file.
function Size (Name : in String) return File_Size;
Returns the size
of the external file represented by Name. The size of an external file
is the number of stream elements contained in the file. If the external
file is not an ordinary file, the result is implementation defined. The
exception Name_Error is propagated if the string given as Name does not
allow the identification of an existing external file. The exception
Constraint_Error is propagated if the file size is not a value of type
File_Size.
function Modification_Time (Name : in String) return Ada.Calendar.Time;
Returns the time
that the external file represented by Name was most recently modified.
If the external file is not an ordinary file, the result is implementation
defined. The exception Name_Error is propagated if the string given as
Name does not allow the identification of an existing external file.
The exception Use_Error is propagated if the external environment does
not support reading the modification time of the file with the name given
by Name (in the absence of Name_Error).
The following directory
searching operations and types are provided:
type Directory_Entry_Type is limited private;
The type Directory_Entry_Type
represents a single item in a directory. These items can only be created
by the Get_Next_Entry procedure in this package. Information about the
item can be obtained from the functions declared in this package. A default-initialized
object of this type is invalid; objects returned from Get_Next_Entry
are valid.
type Filter_Type is array (File_Kind) of Boolean;
The type Filter_Type
specifies which directory entries are provided from a search operation.
If the Directory component is True, directory entries representing directories
are provided. If the Ordinary_File component is True, directory entries
representing ordinary files are provided. If the Special_File component
is True, directory entries representing special files are provided.
type Search_Type is limited private;
The type Search_Type
contains the state of a directory search. A default-initialized Search_Type
object has no entries available (function More_Entries returns False).
Type Search_Type needs finalization
(see
7.6).
procedure Start_Search (Search : in out Search_Type;
Directory : in String;
Pattern : in String;
Filter : in Filter_Type := (others => True));
Starts a search
in the directory named by Directory for entries matching Pattern and
Filter. Pattern represents a pattern for matching file names. If Pattern
is the null string, all items in the directory are matched; otherwise,
the interpretation of Pattern is implementation defined. Only items that
match Filter will be returned. After a successful call on Start_Search,
the object Search may have entries available, but it may have no entries
available if no files or directories match Pattern and Filter. The exception
Name_Error is propagated if the string given by Directory does not identify
an existing directory, or if Pattern does not allow the identification
of any possible external file or directory. The exception Use_Error is
propagated if the external environment does not support the searching
of the directory with the given name (in the absence of Name_Error).
When Start_Search propagates Name_Error or Use_Error, the object Search
will have no entries available.
procedure End_Search (Search : in out Search_Type);
Ends the search
represented by Search. After a successful call on End_Search, the object
Search will have no entries available.
function More_Entries (Search : in Search_Type) return Boolean;
Returns True if
more entries are available to be returned by a call to Get_Next_Entry
for the specified search object, and False otherwise.
procedure Get_Next_Entry (Search : in out Search_Type;
Directory_Entry : out Directory_Entry_Type);
Returns the next
Directory_Entry for the search described by Search that matches the pattern
and filter. If no further matches are available, Status_Error is raised.
It is implementation defined as to whether the results returned by this
subprogram are altered if the contents of the directory are altered while
the Search object is valid (for example, by another program). The exception
Use_Error is propagated if the external environment does not support
continued searching of the directory represented by Search.
procedure Search (
Directory : in String;
Pattern : in String;
Filter : in Filter_Type := (others => True);
Process : not null access procedure (
Directory_Entry : in Directory_Entry_Type))
with Allows_Exit;
Searches in the
directory named by Directory for entries matching Pattern and Filter.
The subprogram designated by Process is called with each matching entry
in turn. Pattern represents a pattern for matching file names. If Pattern
is the null string, all items in the directory are matched; otherwise,
the interpretation of Pattern is implementation defined. Only items that
match Filter will be returned. The exception Name_Error is propagated
if the string given by Directory does not identify an existing directory,
or if Pattern does not allow the identification of any possible external
file or directory. The exception Use_Error is propagated if the external
environment does not support the searching of the directory with the
given name (in the absence of Name_Error).
function Simple_Name (Directory_Entry : in Directory_Entry_Type)
return String;
Returns the simple
external name of the external file (including directories) represented
by Directory_Entry. The format of the name returned is implementation
defined. The exception Status_Error is propagated if Directory_Entry
is invalid.
function Full_Name (Directory_Entry : in Directory_Entry_Type)
return String;
Returns the full
external name of the external file (including directories) represented
by Directory_Entry. The format of the name returned is implementation
defined. The exception Status_Error is propagated if Directory_Entry
is invalid.
function Kind (Directory_Entry : in Directory_Entry_Type)
return File_Kind;
Returns the kind
of external file represented by Directory_Entry. The exception Status_Error
is propagated if Directory_Entry is invalid.
function Size (Directory_Entry : in Directory_Entry_Type)
return File_Size;
Returns the size
of the external file represented by Directory_Entry. The size of an external
file is the number of stream elements contained in the file. If the external
file represented by Directory_Entry is not an ordinary file, the result
is implementation defined. The exception Status_Error is propagated if
Directory_Entry is invalid. The exception Constraint_Error is propagated
if the file size is not a value of type File_Size.
function Modification_Time (Directory_Entry : in Directory_Entry_Type)
return Ada.Calendar.Time;
Returns the time
that the external file represented by Directory_Entry was most recently
modified. If the external file represented by Directory_Entry is not
an ordinary file, the result is implementation defined. The exception
Status_Error is propagated if Directory_Entry is invalid. The exception
Use_Error is propagated if the external environment does not support
reading the modification time of the file represented by Directory_Entry.
Implementation Requirements
For Copy_File, if Source_Name identifies an existing
external ordinary file created by a predefined Ada input-output package,
and Target_Name and Form can be used in the Create operation of that
input-output package with mode Out_File without raising an exception,
then Copy_File shall not propagate Use_Error.
Implementation Advice
If other information about a file (such as the owner
or creation date) is available in a directory entry, the implementation
should provide functions in a child package Directories.Information to
retrieve it.
Start_Search and Search should raise Name_Error
if Pattern is malformed, but not if it can represent a file in the directory
but does not actually do so.
Rename should be supported at least when both New_Name
and Old_Name are simple names and New_Name does not identify an existing
external file.
NOTE 1 The operations Containing_Directory,
Full_Name, Simple_Name, Base_Name, Extension, and Compose operate on
file names, not external files. The files identified by these operations
do not necessarily exist. Name_Error is raised only if the file name
is malformed and cannot possibly identify a file. Of these operations,
only the result of Full_Name depends on the current default directory;
the result of the others depends only on their parameters.
NOTE 2 Using access types, values
of Search_Type and Directory_Entry_Type can be saved and queried later.
However, another task or application can modify or delete the file represented
by a Directory_Entry_Type value or the directory represented by a Search_Type
value; such a value can only give the information valid at the time it
is created. Therefore, long-term storage of these values is not recommended.
NOTE 3 If the target system does
not support directories inside of directories, then Kind will never return
Directory and Containing_Directory will always raise Use_Error.
NOTE 4 If the target system does
not support creation or deletion of directories, then Create_Directory,
Create_Path, Delete_Directory, and Delete_Tree will always propagate
Use_Error.
NOTE 5 To move a file or directory
to a different location, use Rename. Most target systems will allow renaming
of files from one directory to another. If the target file or directory
can already exist, it should be deleted first.
Ada 2005 and 2012 Editions sponsored in part by Ada-Europe
