1 ------------------------------------------------------------------------------
3 -- GNAT COMPILER COMPONENTS --
5 -- G N A T . O S _ L I B --
9 -- Copyright (C) 1995-2002 Free Software Foundation, 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 -- Extensive contributions were provided by Ada Core Technologies Inc. --
31 ------------------------------------------------------------------------------
33 -- Operating system interface facilities
35 -- This package contains types and procedures for interfacing to the
36 -- underlying OS. It is used by the GNAT compiler and by tools associated
37 -- with the GNAT compiler, and therefore works for the various operating
38 -- systems to which GNAT has been ported. This package will undoubtedly
39 -- grow as new services are needed by various tools.
41 -- This package tends to use fairly low-level Ada in order to not bring
42 -- in large portions of the RTL. For example, functions return access
43 -- to string as part of avoiding functions returning unconstrained types.
45 -- Except where specifically noted, these routines are portable across
46 -- all GNAT implementations on all supported operating systems.
49 with Unchecked_Deallocation
;
51 package GNAT
.OS_Lib
is
52 pragma Elaborate_Body
(OS_Lib
);
54 type String_Access
is access all String;
55 -- General purpose string access type. Some of the functions in this
56 -- package allocate string results on the heap, and return a value of
57 -- this type. Note that the caller is responsible for freeing this
58 -- String to avoid memory leaks.
60 procedure Free
is new Unchecked_Deallocation
61 (Object
=> String, Name
=> String_Access
);
62 -- This procedure is provided for freeing returned values of type
65 type String_List
is array (Positive range <>) of String_Access
;
66 type String_List_Access
is access all String_List
;
67 -- General purpose array and pointer for list of string accesses
69 procedure Free
(Arg
: in out String_List_Access
);
70 -- Frees the given array and all strings that its elements reference,
71 -- and then sets the argument to null. Provided for freeing returned
72 -- values of this type (including Argument_List_Access).
78 -- The OS's notion of time is represented by the private type OS_Time.
79 -- This is the type returned by the File_Time_Stamp functions to obtain
80 -- the time stamp of a specified file. Functions and a procedure (modeled
81 -- after the similar subprograms in package Calendar) are provided for
82 -- extracting information from a value of this type. Although these are
83 -- called GM, the intention is not that they provide GMT times in all
84 -- cases but rather the actual (time-zone independent) time stamp of the
85 -- file (of course in Unix systems, this *is* in GMT form).
87 type OS_Time
is private;
89 subtype Year_Type
is Integer range 1900 .. 2099;
90 subtype Month_Type
is Integer range 1 .. 12;
91 subtype Day_Type
is Integer range 1 .. 31;
92 subtype Hour_Type
is Integer range 0 .. 23;
93 subtype Minute_Type
is Integer range 0 .. 59;
94 subtype Second_Type
is Integer range 0 .. 59;
96 function GM_Year
(Date
: OS_Time
) return Year_Type
;
97 function GM_Month
(Date
: OS_Time
) return Month_Type
;
98 function GM_Day
(Date
: OS_Time
) return Day_Type
;
99 function GM_Hour
(Date
: OS_Time
) return Hour_Type
;
100 function GM_Minute
(Date
: OS_Time
) return Minute_Type
;
101 function GM_Second
(Date
: OS_Time
) return Second_Type
;
105 Year
: out Year_Type
;
106 Month
: out Month_Type
;
108 Hour
: out Hour_Type
;
109 Minute
: out Minute_Type
;
110 Second
: out Second_Type
);
116 -- These routines give access to the open/creat/close/read/write level
117 -- of I/O routines in the typical C library (these functions are not
118 -- part of the ANSI C standard, but are typically available in all
119 -- systems). See also package Interfaces.C_Streams for access to the
120 -- stream level routines.
122 -- Note on file names. If a file name is passed as type String in any
123 -- of the following specifications, then the name is a normal Ada string
124 -- and need not be NUL-terminated. However, a trailing NUL character is
125 -- permitted, and will be ignored (more accurately, the NUL and any
126 -- characters that follow it will be ignored).
128 type File_Descriptor
is private;
129 -- Corresponds to the int file handle values used in the C routines,
131 Standin
: constant File_Descriptor
;
132 Standout
: constant File_Descriptor
;
133 Standerr
: constant File_Descriptor
;
134 -- File descriptors for standard input output files
136 Invalid_FD
: constant File_Descriptor
;
137 -- File descriptor returned when error in opening/creating file;
139 type Mode
is (Binary
, Text
);
140 for Mode
'Size use Integer'Size;
141 for Mode
use (Binary
=> 0, Text
=> 1);
142 -- Used in all the Open and Create calls to specify if the file is to be
143 -- opened in binary mode or text mode. In systems like Unix, this has no
144 -- effect, but in systems capable of text mode translation, the use of
145 -- Text as the mode parameter causes the system to do CR/LF translation
146 -- and also to recognize the DOS end of file character on input. The use
147 -- of Text where appropriate allows programs to take a portable Unix view
148 -- of DOs-format files and process them appropriately.
153 return File_Descriptor
;
154 -- Open file Name for reading, returning file descriptor File descriptor
155 -- returned is Invalid_FD if file cannot be opened.
157 function Open_Read_Write
160 return File_Descriptor
;
161 -- Open file Name for both reading and writing, returning file
162 -- descriptor. File descriptor returned is Invalid_FD if file cannot be
168 return File_Descriptor
;
169 -- Creates new file with given name for writing, returning file descriptor
170 -- for subsequent use in Write calls. File descriptor returned is
171 -- Invalid_FD if file cannot be successfully created
173 function Create_New_File
176 return File_Descriptor
;
177 -- Create new file with given name for writing, returning file descriptor
178 -- for subsequent use in Write calls. This differs from Create_File in
179 -- that it fails if the file already exists. File descriptor returned is
180 -- Invalid_FD if the file exists or cannot be created.
182 Temp_File_Len
: constant Integer := 12;
183 -- Length of name returned by Create_Temp_File call (GNAT-XXXXXX & NUL)
185 subtype Temp_File_Name
is String (1 .. Temp_File_Len
);
186 -- String subtype set by Create_Temp_File
188 procedure Create_Temp_File
189 (FD
: out File_Descriptor
;
190 Name
: out Temp_File_Name
);
191 -- Create and open for writing a temporary file. The name of the
192 -- file and the File Descriptor are returned. The File Descriptor
193 -- returned is Invalid_FD in the case of failure. No mode parameter
194 -- is provided. Since this is a temporary file, there is no point in
195 -- doing text translation on it.
197 procedure Close
(FD
: File_Descriptor
);
198 pragma Import
(C
, Close
, "close");
199 -- Close file referenced by FD
201 procedure Delete_File
(Name
: String; Success
: out Boolean);
202 -- Deletes file. Success is set True or False indicating if the delete is
205 procedure Rename_File
208 Success
: out Boolean);
209 -- Rename a file. Success is set True or False indicating if the rename is
213 (FD
: File_Descriptor
;
217 pragma Import
(C
, Read
, "read");
218 -- Read N bytes to address A from file referenced by FD. Returned value
219 -- is count of bytes actually read, which can be less than N at EOF.
222 (FD
: File_Descriptor
;
226 pragma Import
(C
, Write
, "write");
227 -- Write N bytes from address A to file referenced by FD. The returned
228 -- value is the number of bytes written, which can be less than N if
229 -- a disk full condition was detected.
231 Seek_Cur
: constant := 1;
232 Seek_End
: constant := 2;
233 Seek_Set
: constant := 0;
234 -- Used to indicate origin for Lseek call
237 (FD
: File_Descriptor
;
238 offset
: Long_Integer;
240 pragma Import
(C
, Lseek
, "lseek");
241 -- Sets the current file pointer to the indicated offset value,
242 -- relative to the current position (origin = SEEK_CUR), end of
243 -- file (origin = SEEK_END), or start of file (origin = SEEK_SET).
245 function File_Length
(FD
: File_Descriptor
) return Long_Integer;
246 pragma Import
(C
, File_Length
, "__gnat_file_length");
247 -- Get length of file from file descriptor FD
249 function File_Time_Stamp
(Name
: String) return OS_Time
;
250 -- Given the name of a file or directory, Name, obtains and returns the
251 -- time stamp. This function can be used for an unopend file.
253 function File_Time_Stamp
(FD
: File_Descriptor
) return OS_Time
;
254 -- Get time stamp of file from file descriptor FD
256 function Normalize_Pathname
258 Directory
: String := "")
260 -- Returns a file name as an absolute path name, resolving all relative
261 -- directories, and symbolic links. The parameter Directory is a fully
262 -- resolved path name for a directory, or the empty string (the default).
263 -- Name is the name of a file, which is either relative to the given
264 -- directory name, if Directory is non-null, or to the current working
265 -- directory if Directory is null. The result returned is the normalized
266 -- name of the file. For most cases, if two file names designate the same
267 -- file through different paths, Normalize_Pathname will return the same
268 -- canonical name in both cases. However, there are cases when this is
269 -- not true; for example, this is not true in Unix for two hard links
270 -- designating the same file.
272 -- If Name cannot be resolved or is null on entry (for example if there is
273 -- a circularity in symbolic links: A is a symbolic link for B, while B is
274 -- a symbolic link for A), then Normalize_Pathname returns an empty string.
276 -- In VMS, if Name follows the VMS syntax file specification, it is first
277 -- converted into Unix syntax. If the conversion fails, Normalize_Pathname
278 -- returns an empty string.
280 function Is_Absolute_Path
(Name
: String) return Boolean;
281 -- Returns True if Name is an absolute path name, i.e. it designates
282 -- a directory absolutely, rather than relative to another directory.
284 function Is_Regular_File
(Name
: String) return Boolean;
285 -- Determines if the given string, Name, is the name of an existing
286 -- regular file. Returns True if so, False otherwise.
288 function Is_Directory
(Name
: String) return Boolean;
289 -- Determines if the given string, Name, is the name of a directory.
290 -- Returns True if so, False otherwise.
292 function Is_Writable_File
(Name
: String) return Boolean;
293 -- Determines if the given string, Name, is the name of an existing
294 -- file that is writable. Returns True if so, False otherwise.
296 function Locate_Exec_On_Path
298 return String_Access
;
299 -- Try to locate an executable whose name is given by Exec_Name in the
300 -- directories listed in the environment Path. If the Exec_Name doesn't
301 -- have the executable suffix, it will be appended before the search.
302 -- Otherwise works like Locate_Regular_File below.
304 -- Note that this function allocates some memory for the returned value.
305 -- This memory needs to be deallocated after use.
307 function Locate_Regular_File
310 return String_Access
;
311 -- Try to locate a regular file whose name is given by File_Name in the
312 -- directories listed in Path. If a file is found, its full pathname is
313 -- returned; otherwise, a null pointer is returned. If the File_Name given
314 -- is an absolute pathname, then Locate_Regular_File just checks that the
315 -- file exists and is a regular file. Otherwise, the Path argument is
316 -- parsed according to OS conventions, and for each directory in the Path
317 -- a check is made if File_Name is a relative pathname of a regular file
318 -- from that directory.
320 -- Note that this function allocates some memory for the returned value.
321 -- This memory needs to be deallocated after use.
323 function Get_Debuggable_Suffix
return String_Access
;
324 -- Return the debuggable suffix convention. Usually this is the same as
325 -- the convention for Get_Executable_Suffix. The result is allocated on
326 -- the heap and should be freed when no longer needed to avoid storage
329 function Get_Executable_Suffix
return String_Access
;
330 -- Return the executable suffix convention. The result is allocated on
331 -- the heap and should be freed when no longer needed to avoid storage
334 function Get_Object_Suffix
return String_Access
;
335 -- Return the object suffix convention. The result is allocated on the
336 -- heap and should be freed when no longer needed to avoid storage leaks.
338 -- The following section contains low-level routines using addresses to
339 -- pass file name and executable name. In each routine the name must be
340 -- Nul-Terminated. For complete documentation refer to the equivalent
341 -- routine (but using string) defined above.
343 subtype C_File_Name
is System
.Address
;
344 -- This subtype is used to document that a parameter is the address
345 -- of a null-terminated string containing the name of a file.
350 return File_Descriptor
;
352 function Open_Read_Write
355 return File_Descriptor
;
360 return File_Descriptor
;
362 function Create_New_File
365 return File_Descriptor
;
367 procedure Delete_File
(Name
: C_File_Name
; Success
: out Boolean);
369 procedure Rename_File
370 (Old_Name
: C_File_Name
;
371 New_Name
: C_File_Name
;
372 Success
: out Boolean);
374 function File_Time_Stamp
(Name
: C_File_Name
) return OS_Time
;
376 function Is_Regular_File
(Name
: C_File_Name
) return Boolean;
378 function Is_Directory
(Name
: C_File_Name
) return Boolean;
380 function Is_Writable_File
(Name
: C_File_Name
) return Boolean;
382 function Locate_Regular_File
383 (File_Name
: C_File_Name
;
385 return String_Access
;
391 subtype Argument_List
is String_List
;
392 -- Type used for argument list in call to Spawn. The lower bound
393 -- of the array should be 1, and the length of the array indicates
394 -- the number of arguments.
396 subtype Argument_List_Access
is String_List_Access
;
397 -- Type used to return Argument_List without dragging in secondary stack.
398 -- Note that there is a Free procedure declared for this subtype which
399 -- frees the array and all referenced strings.
401 procedure Normalize_Arguments
(Args
: in out Argument_List
);
402 -- Normalize all arguments in the list. This ensure that the argument list
403 -- is compatible with the running OS and will works fine with Spawn and
404 -- Non_Blocking_Spawn for example. If Normalize_Arguments is called twice
405 -- on the same list it will do nothing the second time. Note that Spawn
406 -- and Non_Blocking_Spawn call Normalize_Arguments automatically, but
407 -- since there is a guarantee that a second call does nothing, this
408 -- internal call with have no effect if Normalize_Arguments is called
409 -- before calling Spawn. The call to Normalize_Arguments assumes that
410 -- the individual referenced arguments in Argument_List are on the heap,
411 -- and may free them and reallocate if they are modified.
414 (Program_Name
: String;
415 Args
: Argument_List
;
416 Success
: out Boolean);
417 -- The first parameter of function Spawn is the name of the executable.
418 -- The second parameter contains the arguments to be passed to the
419 -- program. Success is False if the named program could not be spawned
420 -- or its execution completed unsuccessfully. Note that the caller will
421 -- be blocked until the execution of the spawned program is complete.
422 -- For maximum portability, use a full path name for the Program_Name
423 -- argument. On some systems (notably Unix systems) a simple file
424 -- name may also work (if the executable can be located in the path).
426 -- Note: Arguments in Args that contain spaces and/or quotes such as
427 -- "--GCC=gcc -v" or "--GCC=""gcc -v""" are not portable across all
428 -- operating systems, and would not have the desired effect if they
429 -- were passed directly to the operating system. To avoid this problem,
430 -- Spawn makes an internal call to Normalize_Arguments, which ensures
431 -- that such arguments are modified in a manner that ensures that the
432 -- desired effect is obtained on all operating systems. The caller may
433 -- call Normalize_Arguments explicitly before the call (e.g. to print
434 -- out the exact form of arguments passed to the operating system). In
435 -- this case the guarantee a second call to Normalize_Arguments has no
436 -- effect ensures that the internal call will not affect the result.
437 -- Note that the implicit call to Normalize_Arguments may free and
438 -- reallocate some of the individual arguments.
440 -- This function will always set Success to False under VxWorks and
441 -- other similar operating systems which have no notion of the concept
442 -- of a dynamically executable file.
445 (Program_Name
: String;
446 Args
: Argument_List
)
448 -- Similar to the above procedure, but returns the actual status returned
449 -- by the operating system, or -1 under VxWorks and any other similar
450 -- operating systems which have no notion of separately spawnable programs.
452 type Process_Id
is private;
453 -- A private type used to identify a process activated by the following
454 -- non-blocking call. The only meaningful operation on this type is a
455 -- comparison for equality.
457 Invalid_Pid
: constant Process_Id
;
458 -- A special value used to indicate errors, as described below.
460 function Non_Blocking_Spawn
461 (Program_Name
: String;
462 Args
: Argument_List
)
464 -- This is a non blocking call. The Process_Id of the spawned process
465 -- is returned. Parameters are to be used as in Spawn. If Invalid_Id
466 -- is returned the program could not be spawned.
468 -- This function will always return Invalid_Id under VxWorks, since
469 -- there is no notion of executables under this OS.
471 procedure Wait_Process
(Pid
: out Process_Id
; Success
: out Boolean);
472 -- Wait for the completion of any of the processes created by previous
473 -- calls to Non_Blocking_Spawn. The caller will be suspended until one
474 -- of these processes terminates (normally or abnormally). If any of
475 -- these subprocesses terminates prior to the call to Wait_Process (and
476 -- has not been returned by a previous call to Wait_Process), then the
477 -- call to Wait_Process is immediate. Pid identifies the process that
478 -- has terminated (matching the value returned from Non_Blocking_Spawn).
479 -- Success is set to True if this sub-process terminated successfully.
480 -- If Pid = Invalid_Id, there were no subprocesses left to wait on.
482 -- This function will always set success to False under VxWorks, since
483 -- there is no notion of executables under this OS.
485 function Argument_String_To_List
486 (Arg_String
: String)
487 return Argument_List_Access
;
488 -- Take a string that is a program and it's arguments and parse it into
489 -- an Argument_List. Note that the result is allocated on the heap, and
490 -- must be freed by the programmer (when it is no longer needed) to avoid
497 function Getenv
(Name
: String) return String_Access
;
498 -- Get the value of the environment variable. Returns an access
499 -- to the empty string if the environment variable does not exist
500 -- or has an explicit null value (in some operating systems these
501 -- are distinct cases, in others they are not; this interface
502 -- abstracts away that difference. The argument is allocated on
503 -- the heap (even in the null case), and needs to be freed explicitly
504 -- when no longer needed to avoid memory leaks.
506 procedure Setenv
(Name
: String; Value
: String);
507 -- Set the value of the environment variable Name to Value. This call
508 -- modifies the current environment, but does not modify the parent
509 -- process environment. After a call to Setenv, Getenv (Name) will
510 -- always return a String_Access referencing the same String as Value.
511 -- This is true also for the null string case (the actual effect may
512 -- be to either set an explicit null as the value, or to remove the
513 -- entry, this is operating system dependent). Note that any following
514 -- calls to Spawn will pass an environment to the spawned process that
515 -- includes the changes made by Setenv calls. This procedure is not
516 -- available under VMS.
518 procedure OS_Exit
(Status
: Integer);
519 pragma Import
(C
, OS_Exit
, "__gnat_os_exit");
520 pragma No_Return
(OS_Exit
);
521 -- Exit to OS with given status code (program is terminated)
524 pragma Import
(C
, OS_Abort
, "abort");
525 pragma No_Return
(OS_Abort
);
526 -- Exit to OS signalling an abort (traceback or other appropriate
527 -- diagnostic information should be given if possible, or entry made
528 -- to the debugger if that is possible).
530 function Errno
return Integer;
531 pragma Import
(C
, Errno
, "__get_errno");
532 -- Return the task-safe last error number.
534 procedure Set_Errno
(Errno
: Integer);
535 pragma Import
(C
, Set_Errno
, "__set_errno");
536 -- Set the task-safe error number.
538 Directory_Separator
: constant Character;
539 -- The character that is used to separate parts of a pathname.
541 Path_Separator
: constant Character;
542 -- The character to separate paths in an environment variable value.
545 pragma Import
(C
, Path_Separator
, "__gnat_path_separator");
546 pragma Import
(C
, Directory_Separator
, "__gnat_dir_separator");
548 type OS_Time
is new Integer;
550 type File_Descriptor
is new Integer;
552 Standin
: constant File_Descriptor
:= 0;
553 Standout
: constant File_Descriptor
:= 1;
554 Standerr
: constant File_Descriptor
:= 2;
555 Invalid_FD
: constant File_Descriptor
:= -1;
557 type Process_Id
is new Integer;
558 Invalid_Pid
: constant Process_Id
:= -1;