A.16 The Package Directories

danger

This Reference Manual output has not been verified, and may contain omissions or errors. Report any problems on the tracking issue

1/2

The package Directories provides operations for manipulating files and directories, and their names.

1.a/3

discussion

The notes for this subclause 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

The library package Directories has the following declaration:

3/5

with Ada.IO_Exceptions;
with Ada.Calendar;
package Ada.Directories 
   with Global => in out synchronized is
4/2-- Directory and file operations:
5/2function Current_Directory return String;
6/2procedure Set_Directory (Directory : in String);
7/2procedure Create_Directory (New_Directory : in String;
                               Form          : in String := "");
8/2procedure Delete_Directory (Directory : in String);
9/2procedure Create_Path (New_Directory : in String;
                          Form          : in String := "");
10/2procedure Delete_Tree (Directory : in String);
11/2procedure Delete_File (Name : in String);
12/2procedure Rename (Old_Name, New_Name : in String);
13/2procedure Copy_File (Source_Name,
                        Target_Name : in String;
                        Form        : in String := "");
14/2-- File and directory name operations:
15/5
function Full_Name (Name : in String) return String
      with Nonblocking;
16/5
function Simple_Name (Name : in String) return String
      with Nonblocking;
17/5
function Containing_Directory (Name : in String) return String
      with Nonblocking;
18/5
function Extension (Name : in String) return String
      with Nonblocking;
19/5
function Base_Name (Name : in String) return String
      with Nonblocking;
20/5
function Compose (Containing_Directory : in String := "";
                     Name                 : in String;
                     Extension            : in String := "") return String
      with Nonblocking;
20.1/3
type Name_Case_Kind is
      (Unknown, Case_Sensitive, Case_Insensitive, Case_Preserving);
20.2/3
function Name_Case_Equivalence (Name : in String) return Name_Case_Kind;
21/2-- File and directory queries:
22/2type File_Kind is (Directory, Ordinary_File, Special_File);
23/2type File_Size is range 0 .. implementation-defined;
24/2function Exists (Name : in String) return Boolean;
25/2function Kind (Name : in String) return File_Kind;
26/2function Size (Name : in String) return File_Size;
27/2function Modification_Time (Name : in String) return Ada.Calendar.Time;
28/2-- Directory searching:
29/2type Directory_Entry_Type is limited private;
30/2type Filter_Type is array (File_Kind) of Boolean;
31/2type Search_Type is limited private;
32/2procedure Start_Search (Search    : in out Search_Type;
                           Directory : in String;
                           Pattern   : in String;
                           Filter    : in Filter_Type := (others => True));
33/2procedure End_Search (Search : in out Search_Type);
34/2function More_Entries (Search : in Search_Type) return Boolean;
35/2procedure Get_Next_Entry (Search : in out Search_Type;
                             Directory_Entry : out Directory_Entry_Type);
36/5
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;
37/2-- Operations on Directory Entries:
38/2function Simple_Name (Directory_Entry : in Directory_Entry_Type)
       return String;
39/2function Full_Name (Directory_Entry : in Directory_Entry_Type)
       return String;
40/2function Kind (Directory_Entry : in Directory_Entry_Type)
       return File_Kind;
41/2function Size (Directory_Entry : in Directory_Entry_Type)
       return File_Size;
42/2function Modification_Time (Directory_Entry : in Directory_Entry_Type)
       return Ada.Calendar.Time;
43/2Status_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
private
    ... -- not specified by the language
end Ada.Directories;

45/2

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

note

Even if an implementation provides a package to create and read soft links, such links are still special files.

46/2

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

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.

47.1/5

A root directory is a directory that has no containing directory.

47.c/5

implementation note

For Unix and Unix-like systems, "/" is the root. For Windows®, "C:\" and "\\Computer\Share" are roots.

48/2

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

A directory entry is a single item in a directory, identifying a single external file (including directories and special files).

50/2

For each function that returns a string, the lower bound of the returned value is 1.

51/2

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

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).

60/2

procedure Create_Path (New_Directory : in String;
                       Form          : in String := "");

61/3

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.

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

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 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

procedure Copy_File (Source_Name,
                     Target_Name : in String;
                     Form        : in String := "");

69/3

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.

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

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/5

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).

74.a/5

discussion

The result of Simple_Name corresponds to the result of the “basename” command on Linux and Unix. If the filename ends with a '/', and is not a root, then “basename” returns the part in front of all of the trailing '/'s. It returns a root intact. The null string is never returned. Similar rules should be used for Windows filenames.

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.

76.b/5

ramification

Containing_Directory raises Use_Error when passed a string representing a root directory.

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/5

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:

82.1/5

• the string given as Containing_Directory is not null and does not allow the identification of a directory;
  
82.2/5
• the string given as Extension is not null and is not a possible extension;
  
82.3/5
• the string given as Name is not a possible simple name (if Extension is null) or base name (if Extension is nonnull); or
  
82.4/5
• the string given as Name is a root directory, and Containing_Directory or Extension is nonnull.
  

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

note

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.5/3

function Name_Case_Equivalence (Name : in String) return Name_Case_Kind;

82.6/3

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

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

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

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 nonnull 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

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.

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/5

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;

112/3

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/5

package Ada.Directories.Information 
   with Global => in out synchronized is
    -- System-specific directory information.
    -- Version for the Microsoft® Windows® operating system.
124.d/2function Creation_Time (Name : in String) return Ada.Calendar.Time;
124.e/2function Last_Access_Time (Name : in String) return Ada.Calendar.Time;
124.f/2function Is_Read_Only (Name : in String) return Boolean;
124.g/2function 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/2function Is_Compressed (Name : in String) return Boolean;
124.i/2function Is_Encrypted (Name : in String) return Boolean;
124.j/2function Is_Hidden (Name : in String) return Boolean;
124.k/2function Is_System (Name : in String) return Boolean;
124.l/2function Is_Offline (Name : in String) return Boolean;
124.m/2function Is_Temporary (Name : in String) return Boolean;
124.n/2function Is_Sparse (Name : in String) return Boolean;
124.o/2function Is_Not_Indexed (Name : in String) return Boolean;
124.p/2function Creation_Time (Directory_Entry : in Directory_Entry_Type)
         return Ada.Calendar.Time;
124.q/2function Last_Access_Time (Directory_Entry : in Directory_Entry_Type)
         return Ada.Calendar.Time;
124.r/2function Is_Read_Only (Directory_Entry : in Directory_Entry_Type) return Boolean;
124.s/2function 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/2function Is_Compressed (Directory_Entry : in Directory_Entry_Type) return Boolean;
124.u/2function Is_Encrypted (Directory_Entry : in Directory_Entry_Type) return Boolean;
124.v/2function Is_Hidden (Directory_Entry : in Directory_Entry_Type) return Boolean;
124.w/2function Is_System (Directory_Entry : in Directory_Entry_Type) return Boolean;
124.x/2function Is_Offline (Directory_Entry : in Directory_Entry_Type) return Boolean;
124.y/2function Is_Temporary (Directory_Entry : in Directory_Entry_Type) return Boolean;
124.z/2function Is_Sparse (Directory_Entry : in Directory_Entry_Type) return Boolean;
124.aa/2function 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

note

For Unix-like systems (Unix, POSIX, Linux, etc.), Directories.Information should contain at least the following routines:

124.dd/5

package Ada.Directories.Information 
   with Global => in out synchronized is
    -- System-specific directory information.
    -- Unix and similar systems version.
124.ee/2function Last_Access_Time (Name : in String) return Ada.Calendar.Time;
124.ff/2function Last_Status_Change_Time (Name : in String) return Ada.Calendar.Time;
124.gg/2type 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/2type Permission_Set_Type is array (Permission) of Boolean;
124.ii/2function Permission_Set (Name : in String) return Permission_Set_Type;
124.jj/2function 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
function Group (Name : in String) return String;
        -- Returns the image of the Group_Id. If a definition of Group_Id
        -- is available, an implementation-defined version of Group
        -- returning Group_Id should also be defined.
124.ll/2function Is_Block_Special_File (Name : in String) return Boolean;
124.mm/2function Is_Character_Special_File (Name : in String) return Boolean;
124.nn/2function Is_FIFO (Name : in String) return Boolean;
124.oo/2function Is_Symbolic_Link (Name : in String) return Boolean;
124.pp/2function Is_Socket (Name : in String) return Boolean;
124.qq/2function Last_Access_Time (Directory_Entry : in Directory_Entry_Type)
       return Ada.Calendar.Time;
124.rr/2function Last_Status_Change_Time (Directory_Entry : in Directory_Entry_Type)
       return Ada.Calendar.Time;
124.ss/2function Permission_Set (Directory_Entry : in Directory_Entry_Type)
       return Permission_Set_Type;
124.tt/2function Owner (Directory_Entry : in Directory_Entry_Type) return String;
       -- See Owner above.
124.uu/2function Group (Directory_Entry : in Directory_Entry_Type) return String;
       -- See Group above.
124.vv/2function Is_Block_Special_File (Directory_Entry : in Directory_Entry_Type)
       return Boolean;
124.ww/2function Is_Character_Special_File (Directory_Entry : in Directory_Entry_Type)
       return Boolean;
124.xx/2function Is_FIFO (Directory_Entry : in Directory_Entry_Type) return Boolean;
124.yy/2function Is_Symbolic_Link (Directory_Entry : in Directory_Entry_Type)
       return Boolean;
124.zz/2function 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

note

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/5

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.

125.a/3

implementation advice

Directories.Start_Search and Directories.Search should raise Name_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/5

note

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.

128/2

note

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.

129/2

note

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.

130/2

note

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.

131/5

note

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.

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

note

Package Ada.Directories is new.

Inconsistencies With Ada 2005

131.d/3

note

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 nonempty 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

note

A new enumeration type Name_Case_Kind and a new function Name_Case_Equivalence is 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.

Wording Changes from Ada 2005

131.f/3

correction

We now explicitly say that the behavior of Create_Path and Copy_File is unspecified when Use_Error is raised. Nothing has changed here, as the behavior was (implicitly) unspecified in the 2007 Amendment.

Wording Changes from Ada 2012

131.g/5

correction

Clarified the meaning of Simple_Name in the case that the parameter is a root directory. This was not previously described.

A.16.1 The Package Directories.Hierarchical_File_Names

1/3

The library package Directories.Hierarchical_File_Names is an optional package providing operations for file name construction and decomposition for targets with hierarchical file naming.

Static Semantics

2/3

If provided, the library package Directories.Hierarchical_File_Names has the following declaration:

3/5

package Ada.Directories.Hierarchical_File_Names
   with Nonblocking, Global => in out synchronized is
4/3function Is_Simple_Name (Name : in String) return Boolean;
5/3function Is_Root_Directory_Name (Name : in String) return Boolean;
6/3function Is_Parent_Directory_Name (Name : in String) return Boolean;
7/3function Is_Current_Directory_Name (Name : in String) return Boolean;
8/3function Is_Full_Name (Name : in String) return Boolean;
9/3function Is_Relative_Name (Name : in String) return Boolean;
10/3function Simple_Name (Name : in String) return String
      renames Ada.Directories.Simple_Name;
11/3function Containing_Directory (Name : in String) return String
      renames Ada.Directories.Containing_Directory;
12/3function Initial_Directory (Name : in String) return String;
13/3function Relative_Name (Name : in String) return String;
14/3function Compose (Directory      : in String := "";
                     Relative_Name  : in String;
                     Extension      : in String := "") return String;
15/3end Ada.Directories.Hierarchical_File_Names;

16/3

In addition to the operations provided in package Directories.Hierarchical_File_Names, the operations in package Directories can be used with hierarchical file names. In particular, functions Full_Name, Base_Name, and Extension provide additional capabilities for hierarchical file names.

17/3

function Is_Simple_Name (Name : in String) return Boolean;

18/3

Returns True if Name is a simple name, and returns False otherwise.

18.a/5

ramification

Root directories are considered simple names, so this function will return True if Name represents a root. Use Is_Root_Directory if it is necessary to distinguish roots and other simple names.

19/3

function Is_Root_Directory_Name (Name : in String) return Boolean;

20/3

Returns True if Name is syntactically a root (a directory that cannot be decomposed further), and returns False otherwise.

20.a/5

implementation note

21/3

function Is_Parent_Directory_Name (Name : in String) return Boolean;

22/3

Returns True if Name can be used to indicate symbolically the parent directory of any directory, and returns False otherwise.

22.a/3

implementation note

Is_Parent_Directory_Name returns True if and only if Name is ".." for both Unix and Windows®.

23/3

function Is_Current_Directory_Name (Name : in String) return Boolean;

24/3

Returns True if Name can be used to indicate symbolically the directory itself for any directory, and returns False otherwise.

24.a/3

implementation note

Is_Current_Directory_Name returns True if and only if Name is "." for both Unix and Windows®.

25/3

function Is_Full_Name (Name : in String) return Boolean;

26/3

Returns True if the leftmost directory part of Name is a root, and returns False otherwise.

27/3

function Is_Relative_Name (Name : in String) return Boolean;

28/3

Returns True if Name allows the identification of an external file (including directories and special files) but is not a full name, and returns False otherwise.

28.a/5

ramification

Relative names include simple names other than root directories as a special case. This function returns False if the syntax of the name is incorrect.

29/3

function Initial_Directory (Name : in String) return String;

30/3

Returns the leftmost directory part in Name. [That is, it returns a root directory name (for a full name), or one of a parent directory name, a current directory name, or a simple name (for a relative 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).

31/3

function Relative_Name (Name : in String) return String;

32/3

Returns the entire file name except the Initial_Directory portion. 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), or if Name has a single part (this includes if any of Is_Simple_Name, Is_Root_Directory_Name, Is_Parent_Directory_Name, or Is_Current_Directory_Name are True).

32.a/3

ramification

The result might be a simple name.

33/3

function Compose (Directory      : in String := "";
                  Relative_Name  : in String;
                  Extension      : in String := "") return String;

34/3

Returns the name of the external file with the specified Directory, Relative_Name, and Extension. The exception Name_Error is propagated if the string given as Directory is not the null string and does not allow the identification of a directory, or if Is_Relative_Name (Relative_Name) is False, or if the string given as Extension is not the null string and is not a possible extension, or if Extension is not the null string and Simple_Name (Relative_Name) is not a base name.

35/3

The result of Compose is a full name if Is_Full_Name (Directory) is True; result is a relative name otherwise.

35.a/3

ramification

Name_Error is raised by Compose if Directory is not the null string, and both Is_Full_Name and Is_Relative_Name return False.

35.b/3

discussion

A common security problem is to include a parent directory name in the middle of a file name; this is often used to navigate outside of an intended root directory. We considered attempting to prevent that case by having Compose detect it and raise an exception. But the extra rules necessary were more confusing than helpful.

35.c/5

note

We can say more about the details of these operations by adopting the notation of a subscript to specify how many path fragments a particular result has. Then, we can abbreviate "Full Name" as "Full" and "Relative Name" as "Rel". In this notation, Unix file name "a/b" is a Rel(2), "../c/d" is a Rel(3), and "/a/b" is a Full(2). Rel(1) is equivalent to a simple name that is not a root; thus we don't have to describe that separately.

35.d/3

note

In this notation,

35.e/3

For N>1,
Containing_Directory(Rel(N)) = Leftmost Rel(N-1),
Containing_Directory(Full(N)) = Leftmost Full(N-1),
Else if N = 1, raise Use_Error .
  

35.f/3

note

Similarly,

35.g/3

For N>1,
Relative_Name(Rel(N)) = Rightmost Rel(N-1),
Relative_Name(Full(N)) = Rightmost Full(N-1),
Else if N = 1, raise Name_Error.
  

35.h/3

note

Finally, for Compose (ignoring the extension here):

35.i/3

Compose (Directory => Full(N), Relative_Name => Rel(M)) => Full(N+M)
Compose (Directory => Rel(N), Relative_Name => Rel(M)) => Rel(N+M)
Name_Error if Relative_Name is a Full(M).
  

35.j/3

note

We didn't try to write wording to reflect these details of these functions.

Implementation Advice

36/3

Directories.Hierarchical_File_Names should be provided for systems with hierarchical file naming, and should not be provided on other systems.

36.a/3

implementation advice

Directories.Hierarchical_File_Names should be provided for systems with hierarchical file naming, and should not be provided on other systems.

36.b/3

implementation note

This package should be provided when targeting Microsoft® Windows®, Unix, Linux, and most Unix-like systems.

37/5

note

NOTE 1 These operations operate on file names, not external files. The files identified by these operations do not necessarily exist. Name_Error is raised only as specified or if the file name is malformed and cannot possibly identify a file. The result of these operations depends only on their parameters.

38/3

note

NOTE 2 Containing_Directory raises Use_Error if Name does not have a containing directory, including when any of Is_Simple_Name, Is_Root_Directory_Name, Is_Parent_Directory_Name, or Is_Current_Directory_Name are True.

38.a/3

ramification

In particular, the default directory is not used to find the containing directory either when Is_Parent_Directory_Name or Is_Current_Directory_Name is True. As noted above, these functions operate purely on the syntax of the file names and do not attempt to interpret them. If interpretation is needed, Directories.Full_Name can be to expand any shorthands used before calling Containing_Directory.

Extensions to Ada 2005

38.b/3

note

Package Ada.Directories.Hierarchical_File_Names is new.

A.16.2 The Packages Wide_Directories and Wide_Wide_Directories

1/5

The packages Wide_Directories and Wide_Wide_Directories provide operations for manipulating files and directories, and their names.

Static Semantics

2/5

The specification of package Wide_Directories is the same as for Directories (including its optional child packages Information and Hierarchical_File_Names), except that each occurrence of String is replaced by Wide_String.

3/5

The specification of package Wide_Wide_Directories is the same as for Directories (including its optional child packages Information and Hierarchical_File_Names), except that each occurrence of String is replaced by Wide_Wide_String.

Extensions to Ada 2012

3.a/5

note

These six packages are new.