1 ------------------------------------------------------------------------------
3 -- GNAT RUN-TIME COMPONENTS --
5 -- A D A . D I R E C T O R I E S --
9 -- Copyright (C) 2004-2005 Free Software Foundation, Inc. --
11 -- This specification is derived for use with GNAT from AI-00248, which is --
12 -- expected to be a part of a future expected revised Ada Reference Manual. --
13 -- The copyright notice above, and the license provisions that follow apply --
14 -- solely to the contents of the part following the private keyword. --
16 -- GNAT is free software; you can redistribute it and/or modify it under --
17 -- terms of the GNU General Public License as published by the Free Soft- --
18 -- ware Foundation; either version 2, or (at your option) any later ver- --
19 -- sion. GNAT is distributed in the hope that it will be useful, but WITH- --
20 -- OUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY --
21 -- or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License --
22 -- for more details. You should have received a copy of the GNU General --
23 -- Public License distributed with GNAT; see file COPYING. If not, write --
24 -- to the Free Software Foundation, 51 Franklin Street, Fifth Floor, --
25 -- Boston, MA 02110-1301, USA. --
27 -- As a special exception, if other files instantiate generics from this --
28 -- unit, or you link this unit with other files to produce an executable, --
29 -- this unit does not by itself cause the resulting executable to be --
30 -- covered by the GNU General Public License. This exception does not --
31 -- however invalidate any other reasons why the executable file might be --
32 -- covered by the GNU Public License. --
34 -- GNAT was originally developed by the GNAT team at New York University. --
35 -- Extensive contributions were provided by Ada Core Technologies Inc. --
37 ------------------------------------------------------------------------------
39 -- Ada 2005: Implementation of Ada.Directories (AI95-00248). Note that this
40 -- unit is available without -gnat05. That seems reasonable, since you only
41 -- get it if you explicitly ask for it.
43 -- External files may be classified as directories, special files, or ordinary
44 -- files. A directory is an external file that is a container for files on
45 -- the target system. A special file is an external file that cannot be
46 -- created or read by a predefined Ada Input-Output package. External files
47 -- that are not special files or directories are called ordinary files.
49 -- A file name is a string identifying an external file. Similarly, a
50 -- directory name is a string identifying a directory. The interpretation of
51 -- file names and directory names is implementation-defined.
53 -- The full name of an external file is a full specification of the name of
54 -- the file. If the external environment allows alternative specifications of
55 -- the name (for example, abbreviations), the full name should not use such
56 -- alternatives. A full name typically will include the names of all of
57 -- directories that contain the item. The simple name of an external file is
58 -- the name of the item, not including any containing directory names. Unless
59 -- otherwise specified, a file name or directory name parameter to a
60 -- predefined Ada input-output subprogram can be a full name, a simple name,
61 -- or any other form of name supported by the implementation.
63 -- The default directory is the directory that is used if a directory or
64 -- file name is not a full name (that is, when the name does not fully
65 -- identify all of the containing directories).
67 -- A directory entry is a single item in a directory, identifying a single
68 -- external file (including directories and special files).
70 -- For each function that returns a string, the lower bound of the returned
74 with Ada
.Finalization
;
75 with Ada
.IO_Exceptions
;
76 with Ada
.Strings
.Unbounded
;
78 package Ada
.Directories
is
81 -- To be removed later ???
83 -----------------------------------
84 -- Directory and File Operations --
85 -----------------------------------
87 function Current_Directory
return String;
88 -- Returns the full directory name for the current default directory. The
89 -- name returned shall be suitable for a future call to Set_Directory.
90 -- The exception Use_Error is propagated if a default directory is not
91 -- supported by the external environment.
93 procedure Set_Directory
(Directory
: String);
94 -- Sets the current default directory. The exception Name_Error is
95 -- propagated if the string given as Directory does not identify an
96 -- existing directory. The exception Use_Error is propagated if the
97 -- external environment does not support making Directory (in the absence
98 -- of Name_Error) a default directory.
100 procedure Create_Directory
101 (New_Directory
: String;
102 Form
: String := "");
103 -- Creates a directory with name New_Directory. The Form parameter can be
104 -- used to give system-dependent characteristics of the directory; the
105 -- interpretation of the Form parameter is implementation-defined. A null
106 -- string for Form specifies the use of the default options of the
107 -- implementation of the new directory. The exception Name_Error is
108 -- propagated if the string given as New_Directory does not allow the
109 -- identification of a directory. The exception Use_Error is propagated if
110 -- the external environment does not support the creation of a directory
111 -- with the given name (in the absence of Name_Error) and form.
113 procedure Delete_Directory
(Directory
: String);
114 -- Deletes an existing empty directory with name Directory. The exception
115 -- Name_Error is propagated if the string given as Directory does not
116 -- identify an existing directory. The exception Use_Error is propagated
117 -- if the external environment does not support the deletion of the
118 -- directory (or some portion of its contents) with the given name (in the
119 -- absence of Name_Error).
121 procedure Create_Path
122 (New_Directory
: String;
123 Form
: String := "");
124 -- Creates zero or more directories with name New_Directory. Each
125 -- non-existent directory named by New_Directory is created. For example,
126 -- on a typical Unix system, Create_Path ("/usr/me/my"); would create
127 -- directory "me" in directory "usr", then create directory "my" in
128 -- directory "me". The Form can be used to give system-dependent
129 -- characteristics of the directory; the interpretation of the Form
130 -- parameter is implementation-defined. A null string for Form specifies
131 -- the use of the default options of the implementation of the new
132 -- directory. The exception Name_Error is propagated if the string given
133 -- as New_Directory does not allow the identification of any directory.
134 -- The exception Use_Error is propagated if the external environment does
135 -- not support the creation of any directories with the given name (in the
136 -- absence of Name_Error) and form.
138 procedure Delete_Tree
(Directory
: String);
139 -- Deletes an existing directory with name Directory. The directory and
140 -- all of its contents (possibly including other directories) are deleted.
141 -- The exception Name_Error is propagated if the string given as Directory
142 -- does not identify an existing directory. The exception Use_Error is
143 -- propagated if the external environment does not support the deletion of
144 -- the directory or some portion of its contents with the given name (in
145 -- the absence of Name_Error). If Use_Error is propagated, it is
146 -- unspecified if a portion of the contents of the directory are deleted.
148 procedure Delete_File
(Name
: String);
149 -- Deletes an existing ordinary or special file with Name. The exception
150 -- Name_Error is propagated if the string given as Name does not identify
151 -- an existing ordinary or special external file. The exception Use_Error
152 -- is propagated if the external environment does not support the deletion
153 -- of the file with the given name (in the absence of Name_Error).
155 procedure Rename
(Old_Name
, New_Name
: String);
156 -- Renames an existing external file (including directories) with Old_Name
157 -- to New_Name. The exception Name_Error is propagated if the string given
158 -- as Old_Name does not identify an existing external file. The exception
159 -- Use_Error is propagated if the external environment does not support the
160 -- renaming of the file with the given name (in the absence of Name_Error).
161 -- In particular, Use_Error is propagated if a file or directory already
162 -- exists with New_Name.
165 (Source_Name
: String;
166 Target_Name
: String;
167 Form
: String := "");
168 -- Copies the contents of the existing external file with Source_Name
169 -- to Target_Name. The resulting external file is a duplicate of the source
170 -- external file. The Form can be used to give system-dependent
171 -- characteristics of the resulting external file; the interpretation of
172 -- the Form parameter is implementation-defined. Exception Name_Error is
173 -- propagated if the string given as Source_Name does not identify an
174 -- existing external ordinary or special file or if the string given as
175 -- Target_Name does not allow the identification of an external file.
176 -- The exception Use_Error is propagated if the external environment does
177 -- not support the creating of the file with the name given by Target_Name
178 -- and form given by Form, or copying of the file with the name given by
179 -- Source_Name (in the absence of Name_Error).
181 ----------------------------------------
182 -- File and directory name operations --
183 ----------------------------------------
185 function Full_Name
(Name
: String) return String;
186 -- Returns the full name corresponding to the file name specified by Name.
187 -- The exception Name_Error is propagated if the string given as Name does
188 -- not allow the identification of an external file (including directories
189 -- and special files).
191 function Simple_Name
(Name
: String) return String;
192 -- Returns the simple name portion of the file name specified by Name. The
193 -- exception Name_Error is propagated if the string given as Name does not
194 -- allow the identification of an external file (including directories and
197 function Containing_Directory
(Name
: String) return String;
198 -- Returns the name of the containing directory of the external file
199 -- (including directories) identified by Name. If more than one directory
200 -- can contain Name, the directory name returned is implementation-defined.
201 -- The exception Name_Error is propagated if the string given as Name does
202 -- not allow the identification of an external file. The exception
203 -- Use_Error is propagated if the external file does not have a containing
206 function Extension
(Name
: String) return String;
207 -- Returns the extension name corresponding to Name. The extension name is
208 -- a portion of a simple name (not including any separator characters),
209 -- typically used to identify the file class. If the external environment
210 -- does not have extension names, then the null string is returned.
211 -- The exception Name_Error is propagated if the string given as Name does
212 -- not allow the identification of an external file.
214 function Base_Name
(Name
: String) return String;
215 -- Returns the base name corresponding to Name. The base name is the
216 -- remainder of a simple name after removing any extension and extension
217 -- separators. The exception Name_Error is propagated if the string given
218 -- as Name does not allow the identification of an external file
219 -- (including directories and special files).
222 (Containing_Directory
: String := "";
224 Extension
: String := "") return String;
225 -- Returns the name of the external file with the specified
226 -- Containing_Directory, Name, and Extension. If Extension is the null
227 -- string, then Name is interpreted as a simple name; otherwise Name is
228 -- interpreted as a base name. The exception Name_Error is propagated if
229 -- the string given as Containing_Directory is not null and does not allow
230 -- the identification of a directory, or if the string given as Extension
231 -- is not null and is not a possible extension, or if the string given as
232 -- Name is not a possible simple name (if Extension is null) or base name
233 -- (if Extension is non-null).
235 --------------------------------
236 -- File and directory queries --
237 --------------------------------
239 type File_Kind
is (Directory
, Ordinary_File
, Special_File
);
240 -- The type File_Kind represents the kind of file represented by an
241 -- external file or directory.
243 type File_Size
is range 0 .. Long_Long_Integer'Last;
244 -- The type File_Size represents the size of an external file
246 function Exists
(Name
: String) return Boolean;
247 -- Returns True if external file represented by Name exists, and False
248 -- otherwise. The exception Name_Error is propagated if the string given as
249 -- Name does not allow the identification of an external file (including
250 -- directories and special files).
252 function Kind
(Name
: String) return File_Kind
;
253 -- Returns the kind of external file represented by Name. The exception
254 -- Name_Error is propagated if the string given as Name does not allow the
255 -- identification of an existing external file.
257 function Size
(Name
: String) return File_Size
;
258 -- Returns the size of the external file represented by Name. The size of
259 -- an external file is the number of stream elements contained in the file.
260 -- If the external file is discontiguous (not all elements exist), the
261 -- result is implementation-defined. If the external file is not an
262 -- ordinary file, the result is implementation-defined. The exception
263 -- Name_Error is propagated if the string given as Name does not allow the
264 -- identification of an existing external file. The exception
265 -- Constraint_Error is propagated if the file size is not a value of type
268 function Modification_Time
(Name
: String) return Ada
.Calendar
.Time
;
269 -- Returns the time that the external file represented by Name was most
270 -- recently modified. If the external file is not an ordinary file, the
271 -- result is implementation-defined. The exception Name_Error is propagated
272 -- if the string given as Name does not allow the identification of an
273 -- existing external file. The exception Use_Error is propagated if the
274 -- external environment does not support the reading the modification time
275 -- of the file with the name given by Name (in the absence of Name_Error).
277 -------------------------
278 -- Directory Searching --
279 -------------------------
281 type Directory_Entry_Type
is limited private;
282 -- The type Directory_Entry_Type represents a single item in a directory.
283 -- These items can only be created by the Get_Next_Entry procedure in this
284 -- package. Information about the item can be obtained from the functions
285 -- declared in this package. A default initialized object of this type is
286 -- invalid; objects returned from Get_Next_Entry are valid.
288 type Filter_Type
is array (File_Kind
) of Boolean;
289 -- The type Filter_Type specifies which directory entries are provided from
290 -- a search operation. If the Directory component is True, directory
291 -- entries representing directories are provided. If the Ordinary_File
292 -- component is True, directory entries representing ordinary files are
293 -- provided. If the Special_File component is True, directory entries
294 -- representing special files are provided.
296 type Search_Type
is limited private;
297 -- The type Search_Type contains the state of a directory search. A
298 -- default-initialized Search_Type object has no entries available
299 -- (More_Entries returns False).
301 procedure Start_Search
302 (Search
: in out Search_Type
;
305 Filter
: Filter_Type
:= (others => True));
306 -- Starts a search in the directory entry in the directory named by
307 -- Directory for entries matching Pattern. Pattern represents a file name
308 -- matching pattern. If Pattern is null, all items in the directory are
309 -- matched; otherwise, the interpretation of Pattern is implementation-
310 -- defined. Only items which match Filter will be returned. After a
311 -- successful call on Start_Search, the object Search may have entries
312 -- available, but it may have no entries available if no files or
313 -- directories match Pattern and Filter. The exception Name_Error is
314 -- propagated if the string given by Directory does not identify an
315 -- existing directory, or if Pattern does not allow the identification of
316 -- any possible external file or directory. The exception Use_Error is
317 -- propagated if the external environment does not support the searching
318 -- of the directory with the given name (in the absence of Name_Error).
320 procedure End_Search
(Search
: in out Search_Type
);
321 -- Ends the search represented by Search. After a successful call on
322 -- End_Search, the object Search will have no entries available. Note
323 -- that is is not necessary to call End_Search if the call to Start_Search
324 -- was unsuccessful and raised an exception (but it is harmless to make
325 -- the call in this case)>
327 function More_Entries
(Search
: Search_Type
) return Boolean;
328 -- Returns True if more entries are available to be returned by a call
329 -- to Get_Next_Entry for the specified search object, and False otherwise.
331 procedure Get_Next_Entry
332 (Search
: in out Search_Type
;
333 Directory_Entry
: out Directory_Entry_Type
);
334 -- Returns the next Directory_Entry for the search described by Search that
335 -- matches the pattern and filter. If no further matches are available,
336 -- Status_Error is raised. It is implementation-defined as to whether the
337 -- results returned by this routine are altered if the contents of the
338 -- directory are altered while the Search object is valid (for example, by
339 -- another program). The exception Use_Error is propagated if the external
340 -- environment does not support continued searching of the directory
341 -- represented by Search.
343 -------------------------------------
344 -- Operations on Directory Entries --
345 -------------------------------------
347 function Simple_Name
(Directory_Entry
: Directory_Entry_Type
) return String;
348 -- Returns the simple external name of the external file (including
349 -- directories) represented by Directory_Entry. The format of the name
350 -- returned is implementation-defined. The exception Status_Error is
351 -- propagated if Directory_Entry is invalid.
353 function Full_Name
(Directory_Entry
: Directory_Entry_Type
) return String;
354 -- Returns the full external name of the external file (including
355 -- directories) represented by Directory_Entry. The format of the name
356 -- returned is implementation-defined. The exception Status_Error is
357 -- propagated if Directory_Entry is invalid.
359 function Kind
(Directory_Entry
: Directory_Entry_Type
) return File_Kind
;
360 -- Returns the kind of external file represented by Directory_Entry. The
361 -- exception Status_Error is propagated if Directory_Entry is invalid.
363 function Size
(Directory_Entry
: Directory_Entry_Type
) return File_Size
;
364 -- Returns the size of the external file represented by Directory_Entry.
365 -- The size of an external file is the number of stream elements contained
366 -- in the file. If the external file is discontiguous (not all elements
367 -- exist), the result is implementation-defined. If the external file
368 -- represented by Directory_Entry is not an ordinary file, the result is
369 -- implementation-defined. The exception Status_Error is propagated if
370 -- Directory_Entry is invalid. The exception Constraint_Error is propagated
371 -- if the file size is not a value of type File_Size.
373 function Modification_Time
374 (Directory_Entry
: Directory_Entry_Type
) return Ada
.Calendar
.Time
;
375 -- Returns the time that the external file represented by Directory_Entry
376 -- was most recently modified. If the external file represented by
377 -- Directory_Entry is not an ordinary file, the result is
378 -- implementation-defined. The exception Status_Error is propagated if
379 -- Directory_Entry is invalid. The exception Use_Error is propagated if
380 -- the external environment does not support the reading the modification
381 -- time of the file represented by Directory_Entry.
387 Status_Error
: exception renames Ada
.IO_Exceptions
.Status_Error
;
388 Name_Error
: exception renames Ada
.IO_Exceptions
.Name_Error
;
389 Use_Error
: exception renames Ada
.IO_Exceptions
.Use_Error
;
390 Device_Error
: exception renames Ada
.IO_Exceptions
.Device_Error
;
393 type Directory_Entry_Type
is record
394 Is_Valid
: Boolean := False;
395 Simple
: Ada
.Strings
.Unbounded
.Unbounded_String
;
396 Full
: Ada
.Strings
.Unbounded
.Unbounded_String
;
397 Kind
: File_Kind
:= Ordinary_File
;
400 -- The type Search_Data is defined in the body, so that the spec does not
401 -- depend on packages of the GNAT hierarchy.
404 type Search_Ptr
is access Search_Data
;
406 -- Search_Type need to be a controlled type, because it includes component
407 -- of type Dir_Type (in GNAT.Directory_Operations) that need to be closed
408 -- (if opened) during finalization. The component need to be an access
409 -- value, because Search_Data is not fully defined in the spec.
411 type Search_Type
is new Ada
.Finalization
.Controlled
with record
415 procedure Finalize
(Search
: in out Search_Type
);
416 -- Close the directory, if opened, and deallocate Value
418 procedure End_Search
(Search
: in out Search_Type
) renames Finalize
;