1 ------------------------------------------------------------------------------
3 -- GNAT COMPILER COMPONENTS --
5 -- G N A T . D I R E C T O R Y _ O P E R A T I O N S --
11 -- Copyright (C) 1998-2001 Ada Core Technologies, Inc. --
13 -- GNAT is free software; you can redistribute it and/or modify it under --
14 -- terms of the GNU General Public License as published by the Free Soft- --
15 -- ware Foundation; either version 2, or (at your option) any later ver- --
16 -- sion. GNAT is distributed in the hope that it will be useful, but WITH- --
17 -- OUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY --
18 -- or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License --
19 -- for more details. You should have received a copy of the GNU General --
20 -- Public License distributed with GNAT; see file COPYING. If not, write --
21 -- to the Free Software Foundation, 59 Temple Place - Suite 330, Boston, --
22 -- MA 02111-1307, USA. --
24 -- As a special exception, if other files instantiate generics from this --
25 -- unit, or you link this unit with other files to produce an executable, --
26 -- this unit does not by itself cause the resulting executable to be --
27 -- covered by the GNU General Public License. This exception does not --
28 -- however invalidate any other reasons why the executable file might be --
29 -- covered by the GNU Public License. --
31 -- GNAT is maintained by Ada Core Technologies Inc (http://www.gnat.com). --
33 ------------------------------------------------------------------------------
35 -- Directory operations
37 -- This package provides routines for manipulating directories. A directory
38 -- can be treated as a file, using open and close routines, and a scanning
39 -- routine is provided for iterating through the entries in a directory.
41 package GNAT
.Directory_Operations
is
43 subtype Dir_Name_Str
is String;
44 -- A subtype used in this package to represent string values that are
45 -- directory names. A directory name is a prefix for files that appear
46 -- with in the directory. This means that for UNIX systems, the string
47 -- includes a final '/', and for DOS-like systems, it includes a final
48 -- '\' character. It can also include drive letters if the operating
49 -- system provides for this. The final '/' or '\' in a Dir_Name_Str is
50 -- optional when passed as a procedure or function in parameter.
52 type Dir_Type
is limited private;
53 -- A value used to reference a directory. Conceptually this value includes
54 -- the identity of the directory, and a sequential position within it.
56 Null_Dir
: constant Dir_Type
;
57 -- Represent the value for an uninitialized or closed directory
59 Directory_Error
: exception;
60 -- Exception raised if the directory cannot be opened, read, closed,
61 -- created or if it is not possible to change the current execution
62 -- environment directory.
64 Dir_Separator
: constant Character;
65 -- Running system default directory separator
67 --------------------------------
68 -- Basic Directory operations --
69 --------------------------------
71 procedure Change_Dir
(Dir_Name
: Dir_Name_Str
);
72 -- Changes the working directory of the current execution environment
73 -- to the directory named by Dir_Name. Raises Directory_Error if Dir_Name
76 procedure Make_Dir
(Dir_Name
: Dir_Name_Str
);
77 -- Create a new directory named Dir_Name. Raises Directory_Error if
78 -- Dir_Name cannot be created.
80 procedure Remove_Dir
(Dir_Name
: Dir_Name_Str
);
81 -- Remove the directory named Dir_Name. Raises Directory_Error if Dir_Name
84 function Get_Current_Dir
return Dir_Name_Str
;
85 -- Returns the current working directory for the execution environment.
87 procedure Get_Current_Dir
(Dir
: out Dir_Name_Str
; Last
: out Natural);
88 -- Returns the current working directory for the execution environment
89 -- The name is returned in Dir_Name. Last is the index in Dir_Name such
90 -- that Dir_Name (Last) is the last character written. If Dir_Name is
91 -- too small for the directory name, the name will be truncated before
92 -- being copied to Dir_Name.
94 -------------------------
95 -- Pathname Operations --
96 -------------------------
98 subtype Path_Name
is String;
99 -- All routines using Path_Name handle both styles (UNIX and DOS) of
100 -- directory separators (either slash or back slash).
102 function Dir_Name
(Path
: Path_Name
) return Dir_Name_Str
;
103 -- Returns directory name for Path. This is similar to the UNIX dirname
104 -- command. Everything after the last directory separator is removed. If
105 -- there is no directory separator the current working directory is
110 Suffix
: String := "")
112 -- Any directory prefix is removed. If Suffix is non-empty and is a
113 -- suffix of Path, it is removed. This is equivalent to the UNIX basename
114 -- command. The following rule is always true:
116 -- 'Path' and 'Dir_Name (Path) & Directory_Separator & Base_Name (Path)'
117 -- represent the same file.
119 -- This function is not case-sensitive on systems that have a non
120 -- case-sensitive file system like Windows, OS/2 and VMS.
122 function File_Extension
(Path
: Path_Name
) return String;
123 -- Return the file extension. This is the string after the last dot
124 -- character in File_Name (Path). It returns the empty string if no
125 -- extension is found. The returned value does contains the file
126 -- extension separator (dot character).
128 function File_Name
(Path
: Path_Name
) return String;
129 -- Returns the file name and the file extension if present. It removes all
130 -- path information. This is equivalent to Base_Name with default Extension
133 type Path_Style
is (UNIX
, DOS
, System_Default
);
135 function Normalize_Pathname
137 Style
: Path_Style
:= System_Default
)
139 -- Removes all double directory separator and converts all '\' to '/' if
140 -- Style is UNIX and converts all '/' to '\' if Style is set to DOS. This
141 -- function will help to provide a consistent naming scheme running for
142 -- different environments. If style is set to System_Default the routine
143 -- will use the default directory separator on the running environment.
145 function Expand_Path
(Path
: Path_Name
) return Path_Name
;
146 -- Returns Path with environment variables (string preceded by a dollar
147 -- sign) replaced by the current environment variable value. For example,
148 -- $HOME/mydir will be replaced by /home/joe/mydir if $HOME environment
149 -- variable is set to /home/joe. The variable can be surrounded by the
150 -- characters '{' and '}' (curly bracket) if needed as in ${HOME}/mydir.
151 -- If an environment variable does not exists the variable will be replaced
152 -- by the empty string. Two dollar signs are replaced by a single dollar
153 -- sign. Note that a variable must start with a letter. If there is no
154 -- closing curly bracket for an opening one there is no translation done,
155 -- so for example ${VAR/toto is returned as ${VAR/toto.
161 procedure Open
(Dir
: out Dir_Type
; Dir_Name
: Dir_Name_Str
);
162 -- Opens the directory named by Dir_Name and returns a Dir_Type value
163 -- that refers to this directory, and is positioned at the first entry.
164 -- Raises Directory_Error if Dir_Name cannot be accessed. In that case
165 -- Dir will be set to Null_Dir.
167 procedure Close
(Dir
: in out Dir_Type
);
168 -- Closes the directory stream refered to by Dir. After calling Close
169 -- Is_Open will return False. Dir will be set to Null_Dir.
170 -- Raises Directory_Error if Dir has not be opened (Dir = Null_Dir).
172 function Is_Open
(Dir
: Dir_Type
) return Boolean;
173 -- Returns True if Dir is open, or False otherwise.
176 (Dir
: in out Dir_Type
;
179 -- Reads the next entry from the directory and sets Str to the name
180 -- of that entry. Last is the index in Str such that Str (Last) is the
181 -- last character written. Last is 0 when there are no more files in the
182 -- directory. If Str is too small for the file name, the file name will
183 -- be truncated before being copied to Str. The list of files returned
184 -- includes directories in systems providing a hierarchical directory
185 -- structure, including . (the current directory) and .. (the parent
186 -- directory) in systems providing these entries. The directory is
187 -- returned in target-OS form. Raises Directory_Error if Dir has not
188 -- be opened (Dir = Null_Dir).
191 with procedure Action
194 Quit
: in out Boolean);
195 procedure Wildcard_Iterator
(Path
: Path_Name
);
196 -- Calls Action for each path matching Path. Path can include wildcards '*'
197 -- and '?' and [...]. The rules are:
199 -- * can be replaced by any sequence of characters
200 -- ? can be replaced by a single character
201 -- [a-z] match one character in the range 'a' through 'z'
202 -- [abc] match either character 'a', 'b' or 'c'
204 -- Item is the filename that has been matched. Index is set to one for the
205 -- first call and is incremented by one at each call. The iterator's
206 -- termination can be controlled by setting Quit to True. It is by default
209 -- For example, if we have the following directory structure:
222 -- A call with expression "/s*/file/*" will call Action for the following
228 with procedure Action
231 Quit
: in out Boolean);
233 (Root_Directory
: Dir_Name_Str
;
234 File_Pattern
: String);
235 -- Recursively searches the directory structure rooted at Root_Directory.
236 -- This provides functionality similar to the UNIX 'find' command.
237 -- Action will be called for every item matching the regular expression
238 -- File_Pattern (see GNAT.Regexp). Item is the full pathname to the file
239 -- starting with Root_Directory that has been matched. Index is set to one
240 -- for the first call and is incremented by one at each call. The iterator
241 -- will pass in the value False on each call to Action. The iterator will
242 -- terminate after passing the last matched path to Action or after
243 -- returning from a call to Action which sets Quit to True.
244 -- Raises GNAT.Regexp.Error_In_Regexp if File_Pattern is ill formed.
246 function Read_Is_Thread_Safe
return Boolean;
247 -- Indicates if procedure Read is thread safe. On systems where the
248 -- target system supports this functionality, Read is thread safe,
249 -- and this function returns True (e.g. this will be the case on any
250 -- UNIX or UNIX-like system providing a correct implementation of the
251 -- function readdir_r). If the system cannot provide a thread safe
252 -- implementation of Read, then this function returns False.
257 type Dir_Type
is access Dir_Type_Value
;
259 Null_Dir
: constant Dir_Type
:= null;
261 pragma Import
(C
, Dir_Separator
, "__gnat_dir_separator");
263 end GNAT
.Directory_Operations
;