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 -- See also child package GNAT.Directory_Operations.Iteration
43 with Ada
.Strings
.Maps
;
45 package GNAT
.Directory_Operations
is
47 subtype Dir_Name_Str
is String;
48 -- A subtype used in this package to represent string values that are
49 -- directory names. A directory name is a prefix for files that appear
50 -- with in the directory. This means that for UNIX systems, the string
51 -- includes a final '/', and for DOS-like systems, it includes a final
52 -- '\' character. It can also include drive letters if the operating
53 -- system provides for this. The final '/' or '\' in a Dir_Name_Str is
54 -- optional when passed as a procedure or function in parameter.
56 type Dir_Type
is limited private;
57 -- A value used to reference a directory. Conceptually this value includes
58 -- the identity of the directory, and a sequential position within it.
60 Null_Dir
: constant Dir_Type
;
61 -- Represent the value for an uninitialized or closed directory
63 Directory_Error
: exception;
64 -- Exception raised if the directory cannot be opened, read, closed,
65 -- created or if it is not possible to change the current execution
66 -- environment directory.
68 Dir_Separator
: constant Character;
69 -- Running system default directory separator
71 --------------------------------
72 -- Basic Directory operations --
73 --------------------------------
75 procedure Change_Dir
(Dir_Name
: Dir_Name_Str
);
76 -- Changes the working directory of the current execution environment
77 -- to the directory named by Dir_Name. Raises Directory_Error if Dir_Name
80 procedure Make_Dir
(Dir_Name
: Dir_Name_Str
);
81 -- Create a new directory named Dir_Name. Raises Directory_Error if
82 -- Dir_Name cannot be created.
84 procedure Remove_Dir
(Dir_Name
: Dir_Name_Str
);
85 -- Remove the directory named Dir_Name. Raises Directory_Error if Dir_Name
88 function Get_Current_Dir
return Dir_Name_Str
;
89 -- Returns the current working directory for the execution environment.
91 procedure Get_Current_Dir
(Dir
: out Dir_Name_Str
; Last
: out Natural);
92 -- Returns the current working directory for the execution environment
93 -- The name is returned in Dir_Name. Last is the index in Dir_Name such
94 -- that Dir_Name (Last) is the last character written. If Dir_Name is
95 -- too small for the directory name, the name will be truncated before
96 -- being copied to Dir_Name.
98 -------------------------
99 -- Pathname Operations --
100 -------------------------
102 subtype Path_Name
is String;
103 -- All routines using Path_Name handle both styles (UNIX and DOS) of
104 -- directory separators (either slash or back slash).
106 function Dir_Name
(Path
: Path_Name
) return Dir_Name_Str
;
107 -- Returns directory name for Path. This is similar to the UNIX dirname
108 -- command. Everything after the last directory separator is removed. If
109 -- there is no directory separator the current working directory is
114 Suffix
: String := "")
116 -- Any directory prefix is removed. If Suffix is non-empty and is a
117 -- suffix of Path, it is removed. This is equivalent to the UNIX basename
118 -- command. The following rule is always true:
120 -- 'Path' and 'Dir_Name (Path) & Directory_Separator & Base_Name (Path)'
121 -- represent the same file.
123 -- This function is not case-sensitive on systems that have a non
124 -- case-sensitive file system like Windows, OS/2 and VMS.
126 function File_Extension
(Path
: Path_Name
) return String;
127 -- Return the file extension. This is the string after the last dot
128 -- character in File_Name (Path). It returns the empty string if no
129 -- extension is found. The returned value does contains the file
130 -- extension separator (dot character).
132 function File_Name
(Path
: Path_Name
) return String;
133 -- Returns the file name and the file extension if present. It removes all
134 -- path information. This is equivalent to Base_Name with default Extension
137 type Path_Style
is (UNIX
, DOS
, System_Default
);
139 function Normalize_Pathname
141 Style
: Path_Style
:= System_Default
)
143 -- Removes all double directory separator and converts all '\' to '/' if
144 -- Style is UNIX and converts all '/' to '\' if Style is set to DOS. This
145 -- function will help to provide a consistent naming scheme running for
146 -- different environments. If style is set to System_Default the routine
147 -- will use the default directory separator on the running environment.
149 function Expand_Path
(Path
: Path_Name
) return Path_Name
;
150 -- Returns Path with environment variables (string preceded by a dollar
151 -- sign) replaced by the current environment variable value. For example,
152 -- $HOME/mydir will be replaced by /home/joe/mydir if $HOME environment
153 -- variable is set to /home/joe. The variable can be surrounded by the
154 -- characters '{' and '}' (curly bracket) if needed as in ${HOME}/mydir.
155 -- If an environment variable does not exists the variable will be replaced
156 -- by the empty string. Two dollar signs are replaced by a single dollar
157 -- sign. Note that a variable must start with a letter. If there is no
158 -- closing curly bracket for an opening one there is no translation done,
159 -- so for example ${VAR/toto is returned as ${VAR/toto.
165 procedure Open
(Dir
: out Dir_Type
; Dir_Name
: Dir_Name_Str
);
166 -- Opens the directory named by Dir_Name and returns a Dir_Type value
167 -- that refers to this directory, and is positioned at the first entry.
168 -- Raises Directory_Error if Dir_Name cannot be accessed. In that case
169 -- Dir will be set to Null_Dir.
171 procedure Close
(Dir
: in out Dir_Type
);
172 -- Closes the directory stream refered to by Dir. After calling Close
173 -- Is_Open will return False. Dir will be set to Null_Dir.
174 -- Raises Directory_Error if Dir has not be opened (Dir = Null_Dir).
176 function Is_Open
(Dir
: Dir_Type
) return Boolean;
177 -- Returns True if Dir is open, or False otherwise.
180 (Dir
: in out Dir_Type
;
183 -- Reads the next entry from the directory and sets Str to the name
184 -- of that entry. Last is the index in Str such that Str (Last) is the
185 -- last character written. Last is 0 when there are no more files in the
186 -- directory. If Str is too small for the file name, the file name will
187 -- be truncated before being copied to Str. The list of files returned
188 -- includes directories in systems providing a hierarchical directory
189 -- structure, including . (the current directory) and .. (the parent
190 -- directory) in systems providing these entries. The directory is
191 -- returned in target-OS form. Raises Directory_Error if Dir has not
192 -- be opened (Dir = Null_Dir).
194 function Read_Is_Thread_Safe
return Boolean;
195 -- Indicates if procedure Read is thread safe. On systems where the
196 -- target system supports this functionality, Read is thread safe,
197 -- and this function returns True (e.g. this will be the case on any
198 -- UNIX or UNIX-like system providing a correct implementation of the
199 -- function readdir_r). If the system cannot provide a thread safe
200 -- implementation of Read, then this function returns False.
205 type Dir_Type
is access Dir_Type_Value
;
207 Null_Dir
: constant Dir_Type
:= null;
209 pragma Import
(C
, Dir_Separator
, "__gnat_dir_separator");
211 Dir_Seps
: constant Ada
.Strings
.Maps
.Character_Set
:=
212 Ada
.Strings
.Maps
.To_Set
("/\");
213 -- UNIX and DOS style directory separators.
215 end GNAT.Directory_Operations;