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 --
9 -- Copyright (C) 1998-2001 Ada Core Technologies, Inc. --
11 -- GNAT is free software; you can redistribute it and/or modify it under --
12 -- terms of the GNU General Public License as published by the Free Soft- --
13 -- ware Foundation; either version 2, or (at your option) any later ver- --
14 -- sion. GNAT is distributed in the hope that it will be useful, but WITH- --
15 -- OUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY --
16 -- or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License --
17 -- for more details. You should have received a copy of the GNU General --
18 -- Public License distributed with GNAT; see file COPYING. If not, write --
19 -- to the Free Software Foundation, 59 Temple Place - Suite 330, Boston, --
20 -- MA 02111-1307, USA. --
22 -- As a special exception, if other files instantiate generics from this --
23 -- unit, or you link this unit with other files to produce an executable, --
24 -- this unit does not by itself cause the resulting executable to be --
25 -- covered by the GNU General Public License. This exception does not --
26 -- however invalidate any other reasons why the executable file might be --
27 -- covered by the GNU Public License. --
29 -- GNAT is maintained by Ada Core Technologies Inc (http://www.gnat.com). --
31 ------------------------------------------------------------------------------
33 -- Directory operations
35 -- This package provides routines for manipulating directories. A directory
36 -- can be treated as a file, using open and close routines, and a scanning
37 -- routine is provided for iterating through the entries in a directory.
39 -- See also child package GNAT.Directory_Operations.Iteration
41 with Ada
.Strings
.Maps
;
43 package GNAT
.Directory_Operations
is
45 subtype Dir_Name_Str
is String;
46 -- A subtype used in this package to represent string values that are
47 -- directory names. A directory name is a prefix for files that appear
48 -- with in the directory. This means that for UNIX systems, the string
49 -- includes a final '/', and for DOS-like systems, it includes a final
50 -- '\' character. It can also include drive letters if the operating
51 -- system provides for this. The final '/' or '\' in a Dir_Name_Str is
52 -- optional when passed as a procedure or function in parameter.
54 type Dir_Type
is limited private;
55 -- A value used to reference a directory. Conceptually this value includes
56 -- the identity of the directory, and a sequential position within it.
58 Null_Dir
: constant Dir_Type
;
59 -- Represent the value for an uninitialized or closed directory
61 Directory_Error
: exception;
62 -- Exception raised if the directory cannot be opened, read, closed,
63 -- created or if it is not possible to change the current execution
64 -- environment directory.
66 Dir_Separator
: constant Character;
67 -- Running system default directory separator
69 --------------------------------
70 -- Basic Directory operations --
71 --------------------------------
73 procedure Change_Dir
(Dir_Name
: Dir_Name_Str
);
74 -- Changes the working directory of the current execution environment
75 -- to the directory named by Dir_Name. Raises Directory_Error if Dir_Name
78 procedure Make_Dir
(Dir_Name
: Dir_Name_Str
);
79 -- Create a new directory named Dir_Name. Raises Directory_Error if
80 -- Dir_Name cannot be created.
82 procedure Remove_Dir
(Dir_Name
: Dir_Name_Str
);
83 -- Remove the directory named Dir_Name. Raises Directory_Error if Dir_Name
86 function Get_Current_Dir
return Dir_Name_Str
;
87 -- Returns the current working directory for the execution environment.
89 procedure Get_Current_Dir
(Dir
: out Dir_Name_Str
; Last
: out Natural);
90 -- Returns the current working directory for the execution environment
91 -- The name is returned in Dir_Name. Last is the index in Dir_Name such
92 -- that Dir_Name (Last) is the last character written. If Dir_Name is
93 -- too small for the directory name, the name will be truncated before
94 -- being copied to Dir_Name.
96 -------------------------
97 -- Pathname Operations --
98 -------------------------
100 subtype Path_Name
is String;
101 -- All routines using Path_Name handle both styles (UNIX and DOS) of
102 -- directory separators (either slash or back slash).
104 function Dir_Name
(Path
: Path_Name
) return Dir_Name_Str
;
105 -- Returns directory name for Path. This is similar to the UNIX dirname
106 -- command. Everything after the last directory separator is removed. If
107 -- there is no directory separator the current working directory is
112 Suffix
: String := "")
114 -- Any directory prefix is removed. If Suffix is non-empty and is a
115 -- suffix of Path, it is removed. This is equivalent to the UNIX basename
116 -- command. The following rule is always true:
118 -- 'Path' and 'Dir_Name (Path) & Directory_Separator & Base_Name (Path)'
119 -- represent the same file.
121 -- This function is not case-sensitive on systems that have a non
122 -- case-sensitive file system like Windows, OS/2 and VMS.
124 function File_Extension
(Path
: Path_Name
) return String;
125 -- Return the file extension. This is the string after the last dot
126 -- character in File_Name (Path). It returns the empty string if no
127 -- extension is found. The returned value does contains the file
128 -- extension separator (dot character).
130 function File_Name
(Path
: Path_Name
) return String;
131 -- Returns the file name and the file extension if present. It removes all
132 -- path information. This is equivalent to Base_Name with default Extension
135 type Path_Style
is (UNIX
, DOS
, System_Default
);
137 function Format_Pathname
139 Style
: Path_Style
:= System_Default
)
141 -- Removes all double directory separator and converts all '\' to '/' if
142 -- Style is UNIX and converts all '/' to '\' if Style is set to DOS. This
143 -- function will help to provide a consistent naming scheme running for
144 -- different environments. If style is set to System_Default the routine
145 -- will use the default directory separator on the running environment.
147 function Expand_Path
(Path
: Path_Name
) return Path_Name
;
148 -- Returns Path with environment variables (string preceded by a dollar
149 -- sign) replaced by the current environment variable value. For example,
150 -- $HOME/mydir will be replaced by /home/joe/mydir if $HOME environment
151 -- variable is set to /home/joe. The variable can be surrounded by the
152 -- characters '{' and '}' (curly bracket) if needed as in ${HOME}/mydir.
153 -- If an environment variable does not exists the variable will be replaced
154 -- by the empty string. Two dollar signs are replaced by a single dollar
155 -- sign. Note that a variable must start with a letter. If there is no
156 -- closing curly bracket for an opening one there is no translation done,
157 -- so for example ${VAR/toto is returned as ${VAR/toto.
163 procedure Open
(Dir
: out Dir_Type
; Dir_Name
: Dir_Name_Str
);
164 -- Opens the directory named by Dir_Name and returns a Dir_Type value
165 -- that refers to this directory, and is positioned at the first entry.
166 -- Raises Directory_Error if Dir_Name cannot be accessed. In that case
167 -- Dir will be set to Null_Dir.
169 procedure Close
(Dir
: in out Dir_Type
);
170 -- Closes the directory stream refered to by Dir. After calling Close
171 -- Is_Open will return False. Dir will be set to Null_Dir.
172 -- Raises Directory_Error if Dir has not be opened (Dir = Null_Dir).
174 function Is_Open
(Dir
: Dir_Type
) return Boolean;
175 -- Returns True if Dir is open, or False otherwise.
178 (Dir
: in out Dir_Type
;
181 -- Reads the next entry from the directory and sets Str to the name
182 -- of that entry. Last is the index in Str such that Str (Last) is the
183 -- last character written. Last is 0 when there are no more files in the
184 -- directory. If Str is too small for the file name, the file name will
185 -- be truncated before being copied to Str. The list of files returned
186 -- includes directories in systems providing a hierarchical directory
187 -- structure, including . (the current directory) and .. (the parent
188 -- directory) in systems providing these entries. The directory is
189 -- returned in target-OS form. Raises Directory_Error if Dir has not
190 -- be opened (Dir = Null_Dir).
192 function Read_Is_Thread_Safe
return Boolean;
193 -- Indicates if procedure Read is thread safe. On systems where the
194 -- target system supports this functionality, Read is thread safe,
195 -- and this function returns True (e.g. this will be the case on any
196 -- UNIX or UNIX-like system providing a correct implementation of the
197 -- function readdir_r). If the system cannot provide a thread safe
198 -- implementation of Read, then this function returns False.
203 type Dir_Type
is access Dir_Type_Value
;
205 Null_Dir
: constant Dir_Type
:= null;
207 pragma Import
(C
, Dir_Separator
, "__gnat_dir_separator");
209 Dir_Seps
: constant Ada
.Strings
.Maps
.Character_Set
:=
210 Ada
.Strings
.Maps
.To_Set
("/\");
211 -- UNIX and DOS style directory separators.
213 end GNAT.Directory_Operations;