A.16 The Package Directories
1/2
{
AI95-00248-01}
The package Directories provides operations for
manipulating files and directories, and their names. 1.a/2
Discussion: The
notes for this clause contain the expected interpretations of some of
the operations on various target systems. “Unix” refers to
the UNIX® operating system, and in most cases also covers Unix-like
systems such as Linux and POSIX. “Windows®” refers to
the Microsoft® Windows® 2000 operating system and usually also
covers most other versions that use the Win32 API.
Static Semantics
2/2
{
AI95-00248-01}
The library package Directories has the following
declaration: 3/2
with Ada.IO_Exceptions;
with Ada.Calendar;
package Ada.Directories is
4/2
-- Directory and file operations:
5/2
function Current_Directory return String;
6/2
procedure Set_Directory (Directory : in String);
7/2
procedure Create_Directory (New_Directory : in String;
Form : in String := "");
8/2
procedure Delete_Directory (Directory : in String);
9/2
procedure Create_Path (New_Directory : in String;
Form : in String := "");
10/2
procedure Delete_Tree (Directory : in String);
11/2
procedure Delete_File (Name : in String);
12/2
procedure Rename (Old_Name, New_Name : in String);
13/2
procedure Copy_File (Source_Name,
Target_Name : in String;
Form : in String := "");
14/2
-- File and directory name operations:
15/2
function Full_Name (Name : in String) return String;
16/2
function Simple_Name (Name : in String) return String;
17/2
function Containing_Directory (Name : in String) return String;
18/2
function Extension (Name : in String) return String;
19/2
function Base_Name (Name : in String) return String;
20/2
function Compose (Containing_Directory : in String := "";
Name : in String;
Extension : in String := "") return String;
20.1/3
{
AI05-0049-1}
type Name_Case_Kind is
(Unknown, Case_Sensitive, Case_Insensitive, Case_Preserving);20.2/3
{
AI05-0049-1}
function Name_Case_Equivalence (Name : in String) return Name_Case_Kind;21/2
-- File and directory queries:
22/2
type File_Kind is (Directory, Ordinary_File, Special_File);
23/2
type File_Size is range 0 .. implementation-defined;
24/2
function Exists (Name : in String) return Boolean;
25/2
function Kind (Name : in String) return File_Kind;
26/2
function Size (Name : in String) return File_Size;
27/2
function Modification_Time (Name : in String) return Ada.Calendar.Time;
28/2
-- Directory searching:
29/2
type Directory_Entry_Type is limited private;
30/2
type Filter_Type is array (File_Kind) of Boolean;
31/2
type Search_Type is limited private;
32/2
procedure Start_Search (Search : in out Search_Type;
Directory : in String;
Pattern : in String;
Filter : in Filter_Type := (others => True));
33/2
procedure End_Search (Search : in out Search_Type);
34/2
function More_Entries (Search : in Search_Type) return Boolean;
35/2
procedure Get_Next_Entry (Search : in out Search_Type;
Directory_Entry : out Directory_Entry_Type);
36/2
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));
37/2
-- Operations on Directory Entries:
38/2
function Simple_Name (Directory_Entry : in Directory_Entry_Type)
return String;
39/2
function Full_Name (Directory_Entry : in Directory_Entry_Type)
return String;
40/2
function Kind (Directory_Entry : in Directory_Entry_Type)
return File_Kind;
41/2
function Size (Directory_Entry : in Directory_Entry_Type)
return File_Size;
42/2
function Modification_Time (Directory_Entry : in Directory_Entry_Type)
return Ada.Calendar.Time;
43/2
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;
44/3
{
AI05-0092-1}
private
... -- not Not specified by the language.
end Ada.Directories;45/2
{
AI95-00248-01}
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. 45.a/2
Ramification: A
directory is an external file, although it may not have a name on some
targets. A directory is not a special file, as it can be created and
read by Directories.
45.b/2
Discussion: Devices
and soft links are examples of special files on Windows® and Unix.
45.c/2
Even if an implementation
provides a package to create and read soft links, such links are still
special files.
46/2
{
AI95-00248-01}
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.
46.a/2
Implementation defined:
The interpretation of file names and
directory names.
47/2
{
AI95-00248-01}
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. 47.a/2
Discussion: The
full name on Unix is a complete path to the root. For Windows®, the
full name includes a complete path, as well as a disk name ("C:")
or network share name. For both systems, the simple name is the part
of the name following the last '/' (or '\' for Windows®). For example,
in the name "/usr/randy/ada-directories.ads", "ada-directories.ads"
is the simple name.
47.b/2
Ramification: It
is possible for a file or directory name to be neither a full name nor
a simple name. For instance, the Unix name "../parent/myfile"
is neither a full name nor a simple name.
48/2
{
AI95-00248-01}
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).
48.a/2
Discussion: The
default directory is the one maintained by the familiar “cd”
command on Unix and Windows®. Note that Windows® maintains separate
default directories for each disk drive; implementations should use the
natural implementation.
49/2
{
AI95-00248-01}
A directory entry is a single item in a
directory, identifying a single external file (including directories
and special files). 50/2
{
AI95-00248-01}
For each function that returns a string, the lower
bound of the returned value is 1.51/2
{
AI95-00248-01}
The following file and directory operations are
provided:52/2
function Current_Directory return String;
53/2
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.
54/2
procedure Set_Directory (Directory : in String);
55/2
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.
56/2
procedure Create_Directory (New_Directory : in String;
Form : in String := "");
57/2
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.
58/2
procedure Delete_Directory (Directory : in String);
59/3
{
AI05-0231-1}
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 (or
some portion of its contents) with
the given name (in the absence of Name_Error).60/2
procedure Create_Path (New_Directory : in String;
Form : in String := "");
61/2
Creates
zero or more directories with name New_Directory. Each non-existent 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.
62/2
procedure Delete_Tree (Directory : in String);
63/2
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.
64/2
procedure Delete_File (Name : in String);
65/2
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).
66/2
procedure Rename (Old_Name, New_Name : in String);
67/3
{
AI05-0231-1}
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.67.a/2
Implementation Note:
This operation is expected to work within a a single directory, and
implementers are encouraged to support it across directories on a single
device. Copying files from one device to another is discouraged (that's
what Copy_File is for). However, there is no requirement to detect file
copying by the target system. If the target system has an API that gives
that for “free”, it can be used. For Windows®, for instance,
MoveFile can be used to implement Rename.
68/3
{
AI05-0092-1}
procedure Copy_File (Source_Name,
Target_Name : in String;
Form : in String := "");69/2
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).
69.a/2
Ramification: Name_Error
is always raised if Source_Name identifies a directory. It is up to the
implementation whether special files can be copied, or if Use_Error will
be raised.
70/2
{
AI95-00248-01}
The following file and directory name operations
are provided:71/2
function Full_Name (Name : in String) return String;
72/2
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).
72.a/2
Discussion: Full
name means that no abbreviations are used in the returned name, and that
it is a full specification of the name. Thus, for Unix and Windows®,
the result should be a full path that does not contain any "."
or ".." directories. Typically, the default directory is used
to fill in any missing information.
73/2
function Simple_Name (Name : in String) return String;
74/2
Returns
the simple name portion of 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).
75/2
function Containing_Directory (Name : in String) return String;
76/2
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.
76.a/2
Discussion: This
is purely a string manipulation function. If Name is not given as a full
name, the containing directory probably won't be one, either. For example,
if Containing_Directory ("..\AARM\RM-A-8") is called on Windows®,
the result should be "..\AARM". If there is no path at all
on the name, the result should be "." (which represents the
current directory). Use Full_Name on the result of Containing_Directory
if the full name is needed.
77/2
function Extension (Name : in String) return String;
78/2
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.
78.a/2
Discussion: For
Unix and Windows®, the extension is the portion of the simple name
following the rightmost period. For example, in the simple name "RM-A-8.html",
the extension is "html".
79/2
function Base_Name (Name : in String) return String;
80/2
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).
80.a/2
Discussion: For
Unix and Windows®, the base name is the portion of the simple name
preceding the rightmost period (except for the special directory names
"." and "..", whose Base_Name is "." and
".."). For example, in the simple name "RM-A-8.html",
the base name is "RM-A-8".
81/2
function Compose (Containing_Directory : in String := "";
Name : in String;
Extension : in String := "") return String;
82/3
{
AI05-0264-1}
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, or if the string given as Extension
is not null and is not a possible extension, or if the string given as
Name is not a possible simple name (if Extension is null) or base name
(if Extension is non-null).82.a/2
Ramification: The
above definition implies that if the Extension is null, for Unix and
Windows® no '.' is added to Name.
82.b/2
Discussion: If
Name is null, Name_Error should be raised, as nothing is not a possible
simple name or base name.
82.c/2
Generally, Compose(Containing_Directory(F),
Base_Name(F),Extension(F)) = F. However, this is not true on Unix or
Windows® for file names that end with a '.'; Compose(Base_Name("Fooey."),Extension("Fooey."))
= "Fooey". This is not a problem for Windows®, as the names
have the same meaning with or without the '.', but these are different
names for Unix. Thus, care needs to be taken on Unix; if Extension is
null, Base_Name should be avoided. (That's not usually a problem with
file names generated by a program.)
82.1/3
{
AI05-0049-1}
function Name_Case_Equivalence (Name : in String) return Name_Case_Kind;82.2/3
{
AI05-0049-1}
{
AI05-0248-1}
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. 82.c.1/3
Implementation Note:
Unix, Linux, and their relatives are Case_Sensitive systems. Microsoft®
Windows® is a Case_Preserving system (unless the rarely used POSIX
mode is used). Ancient systems like CP/M and early MS-DOS were Case_Insensitive
systems (file names were always in UPPER CASE). Unknown is provided in
case it is impossible to tell (such as could be the case for network
files).
83/2
{
AI95-00248-01}
The following file and directory queries and types
are provided:84/2
type File_Kind is (Directory, Ordinary_File, Special_File);
85/2
The
type File_Kind represents the kind of file represented by an external
file or directory.
86/2
type File_Size is range 0 .. implementation-defined;
87/2
The
type File_Size represents the size of an external file.
87.a/2
Implementation defined:
The maximum value for a file size in
Directories.
88/2
function Exists (Name : in String) return Boolean;
89/2
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).
90/2
function Kind (Name : in String) return File_Kind;
91/2
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.
92/2
function Size (Name : in String) return File_Size;
93/2
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.
93.a/2
Implementation defined:
The result for Directories.Size for
a directory or special file
93.b/2
Discussion:
We allow raising Constraint_Error, so that an implementation for
a system with 64-bit file sizes does not need to support full numerics
on 64-bit integers just to implement this package. Of course, if 64-bit
integers are available on such a system, they should be used when defining
type File_Size.
94/2
function Modification_Time (Name : in String) return Ada.Calendar.Time;
95/2
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).
95.a/2
Implementation defined:
The result for Directories.Modification_Time
for a directory or special file.
96/2
{
AI95-00248-01}
The following directory searching operations and
types are provided:97/2
type Directory_Entry_Type is limited private;
98/2
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.
99/2
type Filter_Type is array (File_Kind) of Boolean;
100/2
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.
101/2
type Search_Type is limited private;
102/2
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).
103/2
procedure Start_Search (Search : in out Search_Type;
Directory : in String;
Pattern : in String;
Filter : in Filter_Type := (others => True));
104/3
{
AI05-0092-1}
{
AI05-0262-1}
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. 104.a/2
Implementation defined:
The interpretation of a non-null search
pattern in Directories.
105/2
procedure End_Search (Search : in out Search_Type);
106/2
Ends
the search represented by Search. After a successful call on End_Search,
the object Search will have no entries available.
106.a/2
Ramification: The
only way that a call to End_Search could be unsuccessful if Device_Error
(see A.13) is raised because of an underlying
failure (or bug).
107/2
function More_Entries (Search : in Search_Type) return Boolean;
108/2
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.
109/2
procedure Get_Next_Entry (Search : in out Search_Type;
Directory_Entry : out Directory_Entry_Type);
110/3
{
AI05-0262-1}
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 routine 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. 110.a/2
Implementation defined:
The results of a Directories search
if the contents of the directory are altered while a search is in progress.
111/2
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));
112/3
{
AI05-0092-1}
{
AI05-0262-1}
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). 112.a/2
Discussion: “In
turn” means that the calls to the subprogram designated by Process
are not made in parallel; they can be made in any order but must be in
sequence.
113/2
function Simple_Name (Directory_Entry : in Directory_Entry_Type)
return String;
114/2
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.
115/2
function Full_Name (Directory_Entry : in Directory_Entry_Type)
return String;
116/2
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.
117/2
function Kind (Directory_Entry : in Directory_Entry_Type)
return File_Kind;
118/2
Returns
the kind of external file represented by Directory_Entry. The exception
Status_Error is propagated if Directory_Entry is invalid.
119/2
function Size (Directory_Entry : in Directory_Entry_Type)
return File_Size;
120/2
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.
121/2
function Modification_Time (Directory_Entry : in Directory_Entry_Type)
return Ada.Calendar.Time;
122/2
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
123/2
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.
123.a/2
Discussion: This
means that Copy_File will copy any file that the Ada programmer could
copy (by writing some possibly complicated Ada code).
Implementation Advice
124/2
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.
124.a/2
Implementation Advice:
Package Directories.Information should
be provided to retrieve other information about a file.
124.b/2
Implementation
Note: For Windows®, Directories.Information should contain at
least the following routines:
124.c/2
package Ada.Directories.Information is
-- System-specific directory information.
-- Version for the Microsoft® Windows® operating system.
124.d/2
function Creation_Time (Name : in String) return Ada.Calendar.Time;
124.e/2
function Last_Access_Time (Name : in String) return Ada.Calendar.Time;
124.f/2
function Is_Read_Only (Name : in String) return Boolean;
124.g/2
function Needs_Archiving (Name : in String) return Boolean;
-- This generally means that the file needs to be backed up.
-- The flag is only cleared by backup programs.
124.h/2
function Is_Compressed (Name : in String) return Boolean;
124.i/2
function Is_Encrypted (Name : in String) return Boolean;
124.j/2
function Is_Hidden (Name : in String) return Boolean;
124.k/2
function Is_System (Name : in String) return Boolean;
124.l/2
function Is_Offline (Name : in String) return Boolean;
124.m/2
function Is_Temporary (Name : in String) return Boolean;
124.n/2
function Is_Sparse (Name : in String) return Boolean;
124.o/2
function Is_Not_Indexed (Name : in String) return Boolean;
124.p/2
function Creation_Time (Directory_Entry : in Directory_Entry_Type)
return Ada.Calendar.Time;
124.q/2
function Last_Access_Time (Directory_Entry : in Directory_Entry_Type)
return Ada.Calendar.Time;
124.r/2
function Is_Read_Only (Directory_Entry : in Directory_Entry_Type) return Boolean;
124.s/2
function Needs_Archiving (Directory_Entry : in Directory_Entry_Type) return Boolean;
-- This generally means that the file needs to be backed up.
-- The flag is only cleared by backup programs.
124.t/2
function Is_Compressed (Directory_Entry : in Directory_Entry_Type) return Boolean;
124.u/2
function Is_Encrypted (Directory_Entry : in Directory_Entry_Type) return Boolean;
124.v/2
function Is_Hidden (Directory_Entry : in Directory_Entry_Type) return Boolean;
124.w/2
function Is_System (Directory_Entry : in Directory_Entry_Type) return Boolean;
124.x/2
function Is_Offline (Directory_Entry : in Directory_Entry_Type) return Boolean;
124.y/2
function Is_Temporary (Directory_Entry : in Directory_Entry_Type) return Boolean;
124.z/2
function Is_Sparse (Directory_Entry : in Directory_Entry_Type) return Boolean;
124.aa/2
function Is_Not_Indexed (Directory_Entry : in Directory_Entry_Type) return Boolean;
124.bb/2
-- Additional implementation-defined subprograms allowed here.
end Ada.Directories.Information;
124.cc/2
For
Unix-like systems (Unix, POSIX, Linux, etc.), Directories.Information
should contain at least the following routines:
124.dd/2
package Ada.Directories.Information is
-- System-specific directory information.
-- Unix and similar systems version.
124.ee/2
function Last_Access_Time (Name : in String) return Ada.Calendar.Time;
124.ff/2
function Last_Status_Change_Time (Name : in String) return Ada.Calendar.Time;
124.gg/2
type Permission is
(Others_Execute, Others_Write, Others_Read,
Group_Execute, Group_Write, Group_Read,
Owner_Execute, Owner_Write, Owner_Read,
Set_Group_ID, Set_User_ID);
124.hh/2
type Permission_Set_Type is array (Permission) of Boolean;
124.ii/2
function Permission_Set (Name : in String) return Permission_Set_Type;
124.jj/2
function Owner (Name : in String) return String;
-- Returns the image of the User_Id. If a definition of User_Id
-- is available, an implementation-defined version of Owner
-- returning User_Id should also be defined.
124.kk/3
{
AI05-0005-1}
function Group (Name : in String) return String;
-- Returns the image of the Group_Id User_Id. If a definition of Group_Id
-- is available, an implementation-defined version of Group
-- returning Group_Id should also be defined.124.ll/2
function Is_Block_Special_File (Name : in String) return Boolean;
124.mm/2
function Is_Character_Special_File (Name : in String) return Boolean;
124.nn/2
function Is_FIFO (Name : in String) return Boolean;
124.oo/2
function Is_Symbolic_Link (Name : in String) return Boolean;
124.pp/2
function Is_Socket (Name : in String) return Boolean;
124.qq/2
function Last_Access_Time (Directory_Entry : in Directory_Entry_Type)
return Ada.Calendar.Time;
124.rr/2
function Last_Status_Change_Time (Directory_Entry : in Directory_Entry_Type)
return Ada.Calendar.Time;
124.ss/2
function Permission_Set (Directory_Entry : in Directory_Entry_Type)
return Permission_Set_Type;
124.tt/2
function Owner (Directory_Entry : in Directory_Entry_Type) return String;
-- See Owner above.
124.uu/2
function Group (Directory_Entry : in Directory_Entry_Type) return String;
-- See Group above.
124.vv/2
function Is_Block_Special_File (Directory_Entry : in Directory_Entry_Type)
return Boolean;
124.ww/2
function Is_Character_Special_File (Directory_Entry : in Directory_Entry_Type)
return Boolean;
124.xx/2
function Is_FIFO (Directory_Entry : in Directory_Entry_Type) return Boolean;
124.yy/2
function Is_Symbolic_Link (Directory_Entry : in Directory_Entry_Type)
return Boolean;
124.zz/2
function Is_Socket (Directory_Entry : in Directory_Entry_Type) return Boolean;
124.aaa/2
-- Additional implementation-defined subprograms allowed here.
end Ada.Directories.Information;
124.bbb/2
We give these definitions
to give guidance so that every implementation for a given target is not
unnecessarily different. Implementers are encouraged to make packages
for other targets as similar to these as possible.
125/3
{
AI05-0231-1}
Start_Search and Search should raise Name_Error Use_Error if Pattern is malformed, but not if it could represent a file in the
directory but does not actually do so.125.a/3
Implementation Advice: Directories.Start_Search
and Directories.Search should raise Name_Error Use_Error for malformed patterns.
126/2
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.
126.a/2
Implementation Advice:
Directories.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.
126.b/2
Discussion: “Supported”
includes raising an exception if either name is malformed, the file to
rename doesn't exist, insufficient permission for the operation exists,
or similar problems. But this advice requires implementations to document
what they do, and tells implementers that simply raising Use_Error isn't
acceptable.
127/2
41 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 need to 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.
128/2
42 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.
129/2
43 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.
130/2
44 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.
131/2
45 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 might already exist, it should be deleted first.
131.a/2
Discussion:
While Rename is only guaranteed to work for name changes within a
single directory, its unlikely that implementers would purposely prevent
functionality present in the underlying system from working. To move
a file totally portably, it's necessary to handle failure of the Rename
and fall back to Copy_File and Delete:
131.b
begin
Rename (Source, Target);
exception
when Use_Error =>
Copy_File (Source, Target);
Delete (Source);
end;
Extensions to Ada 95
131.c/2
Inconsistencies With Ada 2005
131.d/3
{
AI05-0231-1}
Correction: Clarified
when and which exceptions are raised for Start_Search, Search, Delete_Directory,
and Rename. If an implementation followed the original incorrect wording,
it might raise Use_Error instead of Name_Error for Start_Search and Search,
Name_Error instead of Use_Error for Rename, and might have deleted a
non-empty directory instead of raising Use_Error for Delete_Directory.
The first two cases are very unlikely to matter in practice, and it unlikely
that an implementation would have followed the latter implementation
strategy, as it would be more work and would make Delete_Directory identical
to Delete_Tree (which is obvious nonsense). Incompatibilities With Ada 2005
131.e/3
{
AI05-0049-1}
A new enumeration type Name_Case_Kind
and a new function Name_Case_Equivalence is newly added to Directories.
If Directories is referenced in a use_clause,
and an entity E with a defining_identifier
of one of the new entities is defined in a package that is also referenced
in a use_clause,
the entity E may no longer be use-visible, resulting in errors.
This should be rare and is easily fixed if it does occur.
Ada 2005 and 2012 Editions sponsored in part by Ada-Europe
