1 ------------------------------------------------------------------------------
3 -- GNAT COMPILER COMPONENTS --
5 -- S Y S T E M . O S _ L I B --
9 -- Copyright (C) 1995-2023, 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 3, 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. --
18 -- As a special exception under Section 7 of GPL version 3, you are granted --
19 -- additional permissions described in the GCC Runtime Library Exception, --
20 -- version 3.1, as published by the Free Software Foundation. --
22 -- You should have received a copy of the GNU General Public License and --
23 -- a copy of the GCC Runtime Library Exception along with this program; --
24 -- see the files COPYING3 and COPYING.RUNTIME respectively. If not, see --
25 -- <http://www.gnu.org/licenses/>. --
27 -- GNAT was originally developed by the GNAT team at New York University. --
28 -- Extensive contributions were provided by Ada Core Technologies Inc. --
30 ------------------------------------------------------------------------------
32 -- Operating system interface facilities
34 -- This package contains types and procedures for interfacing to the
35 -- underlying OS. It is used by the GNAT compiler and by tools associated
36 -- with the GNAT compiler, and therefore works for the various operating
37 -- systems to which GNAT has been ported. This package will undoubtedly grow
38 -- as new services are needed by various tools.
40 -- This package tends to use fairly low-level Ada in order to not bring in
41 -- large portions of the RTL. For example, functions return access to string
42 -- as part of avoiding functions returning unconstrained types.
44 -- Except where specifically noted, these routines are portable across all
45 -- GNAT implementations on all supported operating systems.
47 -- Note: this package is in the System hierarchy so that it can be directly
48 -- be used by other predefined packages. User access to this package is via
49 -- a renaming of this package in GNAT.OS_Lib (file g-os_lib.ads).
53 package System
.OS_Lib
is
56 -----------------------
57 -- String Operations --
58 -----------------------
60 -- These are reexported from package Strings (which was introduced to
61 -- avoid different packages declaring different types unnecessarily).
62 -- See package System.Strings for details.
64 subtype String_Access
is Strings
.String_Access
;
66 function "=" (Left
: String_Access
; Right
: String_Access
) return Boolean
69 procedure Free
(X
: in out String_Access
) renames Strings
.Free
;
71 subtype String_List
is Strings
.String_List
;
73 function "=" (Left
: String_List
; Right
: String_List
) return Boolean
76 function "&" (Left
: String_Access
; Right
: String_Access
)
77 return String_List
renames Strings
."&";
78 function "&" (Left
: String_Access
; Right
: String_List
)
79 return String_List
renames Strings
."&";
80 function "&" (Left
: String_List
; Right
: String_Access
)
81 return String_List
renames Strings
."&";
82 function "&" (Left
: String_List
; Right
: String_List
)
83 return String_List
renames Strings
."&";
85 subtype String_List_Access
is Strings
.String_List_Access
;
88 (Left
: String_List_Access
;
89 Right
: String_List_Access
) return Boolean renames Strings
."=";
91 procedure Free
(Arg
: in out String_List_Access
) renames Strings
.Free
;
97 type OS_Time
is private;
98 -- The OS's notion of time is represented by the private type OS_Time. This
99 -- is the type returned by the File_Time_Stamp functions to obtain the time
100 -- stamp of a specified file. Functions and a procedure (modeled after the
101 -- similar subprograms in package Calendar) are provided for extracting
102 -- information from a value of this type. Although these are called GM, the
103 -- intention in the case of time stamps is not that they provide GMT times
104 -- in all cases but rather the actual (time-zone independent) time stamp of
105 -- the file (of course in Unix systems, this *is* in GMT form).
107 Invalid_Time
: constant OS_Time
;
108 -- A special unique value used to flag an invalid time stamp value
110 function "<" (X
: OS_Time
; Y
: OS_Time
) return Boolean;
111 function ">" (X
: OS_Time
; Y
: OS_Time
) return Boolean;
112 function ">=" (X
: OS_Time
; Y
: OS_Time
) return Boolean;
113 function "<=" (X
: OS_Time
; Y
: OS_Time
) return Boolean;
114 -- Basic comparison operators on OS_Time with obvious meanings. Note that
115 -- these have Intrinsic convention, so for example it is not permissible
116 -- to create accesses to any of these functions.
118 subtype Year_Type
is Integer range 1900 .. 2099;
119 subtype Month_Type
is Integer range 1 .. 12;
120 subtype Day_Type
is Integer range 1 .. 31;
121 subtype Hour_Type
is Integer range 0 .. 23;
122 subtype Minute_Type
is Integer range 0 .. 59;
123 subtype Second_Type
is Integer range 0 .. 59;
124 -- Declarations similar to those in Calendar, breaking down the time
126 function Current_Time
return OS_Time
;
127 -- Return the system clock value as OS_Time
129 function Current_Time_String
return String;
130 -- Returns current local time in the form YYYY-MM-DD HH:MM:SS. The result
131 -- has bounds 1 .. 19.
133 function GM_Year
(Date
: OS_Time
) return Year_Type
;
134 function GM_Month
(Date
: OS_Time
) return Month_Type
;
135 function GM_Day
(Date
: OS_Time
) return Day_Type
;
136 function GM_Hour
(Date
: OS_Time
) return Hour_Type
;
137 function GM_Minute
(Date
: OS_Time
) return Minute_Type
;
138 function GM_Second
(Date
: OS_Time
) return Second_Type
;
139 -- Functions to extract information from OS_Time value in GMT form
143 Year
: out Year_Type
;
144 Month
: out Month_Type
;
146 Hour
: out Hour_Type
;
147 Minute
: out Minute_Type
;
148 Second
: out Second_Type
);
149 -- Analogous to the Split routine in Ada.Calendar, takes an OS_Time and
150 -- provides a representation of it as a set of component parts, to be
151 -- interpreted as a date point in UTC.
158 Minute
: Minute_Type
;
159 Second
: Second_Type
) return OS_Time
;
160 -- Analogous to the Time_Of routine in Ada.Calendar, takes a set of time
161 -- component parts to be interpreted in the local time zone, and returns
162 -- an OS_Time. Returns Invalid_Time if the creation fails.
168 -- Note: Do not use time_t in the compiler and host-based tools; instead
171 subtype time_t
is Long_Long_Integer;
172 -- C time_t can be either long or long long, so we choose the Ada
173 -- equivalent of the latter because eventually that will be the
174 -- type used out of necessity. This may affect some user code on 32-bit
175 -- targets that have not yet migrated to the Posix 2008 standard,
176 -- particularly pre version 5 32-bit Linux. Do not change this
177 -- declaration without coordinating it with conversions in Ada.Calendar.
179 function To_C
(Time
: OS_Time
) return time_t
;
180 -- Convert OS_Time to C time_t type
182 function To_Ada
(Time
: time_t
) return OS_Time
;
183 -- Convert C time_t type to OS_Time
189 -- These routines give access to the open/creat/close/read/write level of
190 -- I/O routines in the typical C library (these functions are not part of
191 -- the ANSI C standard, but are typically available in all systems). See
192 -- also package Interfaces.C_Streams for access to the stream level
195 -- Note on file names. If a file name is passed as type String in any of
196 -- the following specifications, then the name is a normal Ada string and
197 -- need not be NUL-terminated. However, a trailing NUL character is
198 -- permitted, and will be ignored (more accurately, the NUL and any
199 -- characters that follow it will be ignored).
201 type File_Descriptor
is new Integer;
202 -- Corresponds to the int file handle values used in the C routines
204 Standin
: constant File_Descriptor
:= 0;
205 Standout
: constant File_Descriptor
:= 1;
206 Standerr
: constant File_Descriptor
:= 2;
207 -- File descriptors for standard input output files
209 Invalid_FD
: constant File_Descriptor
:= -1;
210 -- File descriptor returned when error in opening/creating file
212 Null_FD
: constant File_Descriptor
:= -2;
213 -- Uninitialized file descriptor
215 procedure Close
(FD
: File_Descriptor
; Status
: out Boolean);
216 -- Close file referenced by FD. Status is False if the underlying service
217 -- failed. Reasons for failure include: disk full, disk quotas exceeded
218 -- and invalid file descriptor (the file may have been closed twice).
220 procedure Close
(FD
: File_Descriptor
);
221 -- Close file referenced by FD. This form is used when the caller wants to
222 -- ignore any possible error (see above for error cases).
226 -- Copy the file. It is an error if the target file already exists. The
227 -- time stamps and other file attributes are preserved in the copy.
230 -- If the target file exists, the file is replaced otherwise the file
231 -- is just copied. The time stamps and other file attributes are
232 -- preserved in the copy.
235 -- If the target file exists, the contents of the source file is
236 -- appended at the end. Otherwise the source file is just copied. The
237 -- time stamps and other file attributes are preserved if the
238 -- destination file does not exist.
242 -- Copy time stamps from source file to target file. All other
243 -- attributes are set to normal default values for file creation.
246 -- All attributes are copied from the source file to the target file.
247 -- This includes the timestamps, and for example also includes
248 -- read/write/execute attributes in Unix systems.
251 -- No attributes are copied. All attributes including the time stamp
252 -- values are set to normal default values for file creation.
254 -- Note: The default is Time_Stamps, which corresponds to the normal
255 -- default on Windows style systems. Full corresponds to the typical
256 -- effect of "cp -p" on Unix systems, and None corresponds to the typical
257 -- effect of "cp" on Unix systems.
259 -- Note: Time_Stamps and Full are not supported on VxWorks 5
264 Success
: out Boolean;
265 Mode
: Copy_Mode
:= Copy
;
266 Preserve
: Attribute
:= Time_Stamps
);
267 -- Copy a file. Name must designate a single file (no wildcards allowed).
268 -- Pathname can be a filename or directory name. In the latter case Name
269 -- is copied into the directory preserving the same file name. Mode
270 -- defines the kind of copy, see above with the default being a normal
271 -- copy in which the target file must not already exist. Success is set to
272 -- True or False indicating if the copy is successful (depending on the
275 procedure Copy_File_Attributes
278 Success
: out Boolean;
279 Copy_Timestamp
: Boolean := True;
280 Copy_Permissions
: Boolean := True);
281 -- Copy some of the file attributes from one file to another. Both files
282 -- must exist, or Success is set to False.
284 procedure Copy_Time_Stamps
287 Success
: out Boolean);
288 -- Copy Source file time stamps (last modification and last access time
289 -- stamps) to Dest file. Source and Dest must be valid filenames,
290 -- furthermore Dest must be writable. Success will be set to True if the
291 -- operation was successful and False otherwise.
293 -- Note: this procedure is not supported on VxWorks 5. On this platform,
294 -- Success is always set to False.
296 type Mode
is (Binary
, Text
);
297 for Mode
'Size use Integer'Size;
298 for Mode
use (Binary
=> 0, Text
=> 1);
299 -- Used in all the Open and Create calls to specify if the file is to be
300 -- opened in binary mode or text mode. In systems like Unix, this has no
301 -- effect, but in systems capable of text mode translation, the use of
302 -- Text as the mode parameter causes the system to do CR/LF translation
303 -- and also to recognize the DOS end of file character on input. The use
304 -- of Text where appropriate allows programs to take a portable Unix view
305 -- of DOS-format files and process them appropriately.
309 Fmode
: Mode
) return File_Descriptor
;
310 -- Creates new file with given name for writing, returning file descriptor
311 -- for subsequent use in Write calls. If the file already exists, it is
312 -- overwritten. File descriptor returned is Invalid_FD if file cannot be
313 -- successfully created.
315 function Create_New_File
317 Fmode
: Mode
) return File_Descriptor
;
318 -- Create new file with given name for writing, returning file descriptor
319 -- for subsequent use in Write calls. This differs from Create_File in
320 -- that it fails if the file already exists. File descriptor returned is
321 -- Invalid_FD if the file exists or cannot be created.
323 function Create_Output_Text_File
(Name
: String) return File_Descriptor
;
324 -- Creates new text file with given name suitable to redirect standard
325 -- output, returning file descriptor. File descriptor returned is
326 -- Invalid_FD if file cannot be successfully created.
328 Temp_File_Len
: constant Integer := 12;
329 -- Length of name returned by Create_Temp_File call (GNAT-XXXXXX & NUL)
331 subtype Temp_File_Name
is String (1 .. Temp_File_Len
);
332 -- String subtype set by Create_Temp_File
334 procedure Create_Temp_File
335 (FD
: out File_Descriptor
;
336 Name
: out Temp_File_Name
);
337 -- Create and open for writing a temporary file in the current working
338 -- directory. The name of the file and the File Descriptor are returned.
339 -- The File Descriptor returned is Invalid_FD in the case of failure. No
340 -- mode parameter is provided. Since this is a temporary file, there is no
341 -- point in doing text translation on it.
343 -- On some operating systems, the maximum number of temp files that can be
344 -- created with this procedure may be limited. When the maximum is reached,
345 -- this procedure returns Invalid_FD. On some operating systems, there may
346 -- be a race condition between processes trying to create temp files at the
347 -- same time in the same directory using this procedure.
349 procedure Create_Temp_File
350 (FD
: out File_Descriptor
;
351 Name
: out String_Access
);
352 -- Create and open for writing a temporary file in the current working
353 -- directory. The name of the file and the File Descriptor are returned.
354 -- It is the responsibility of the caller to deallocate the access value
357 -- The file is opened in binary mode (no text translation).
359 -- This procedure will always succeed if the current working directory is
360 -- writable. If the current working directory is not writable, then
361 -- Invalid_FD is returned for the file descriptor and null for the Name.
362 -- There is no race condition problem between processes trying to create
363 -- temp files at the same time in the same directory.
365 procedure Create_Temp_Output_File
366 (FD
: out File_Descriptor
;
367 Name
: out String_Access
);
368 -- Create and open for writing a temporary file in the current working
369 -- directory suitable to redirect standard output. The name of the file and
370 -- the File Descriptor are returned. It is the responsibility of the caller
371 -- to deallocate the access value returned in Name.
373 -- The file is opened in text mode
375 -- This procedure will always succeed if the current working directory is
376 -- writable. If the current working directory is not writable, then
377 -- Invalid_FD is returned for the file descriptor and null for the Name.
378 -- There is no race condition problem between processes trying to create
379 -- temp files at the same time in the same directory.
381 procedure Delete_File
(Name
: String; Success
: out Boolean);
382 -- Deletes file. Success is set True or False indicating if the delete is
385 function File_Length
(FD
: File_Descriptor
) return Long_Integer;
386 pragma Import
(C
, File_Length
, "__gnat_file_length_long");
388 type Large_File_Size
is range -2**63 .. 2**63 - 1;
389 -- Maximum supported size for a file (8 exabytes = 8 million terabytes,
390 -- should be enough to accommodate all possible needs for quite a while).
392 function File_Length64
(FD
: File_Descriptor
) return Large_File_Size
;
393 pragma Import
(C
, File_Length64
, "__gnat_file_length");
394 -- Get length of file from file descriptor FD
396 function File_Time_Stamp
(Name
: String) return OS_Time
;
397 -- Given the name of a file or directory, Name, obtains and returns the
398 -- time stamp. This function can be used for an unopened file. Returns
399 -- Invalid_Time if Name doesn't correspond to an existing file.
401 function File_Time_Stamp
(FD
: File_Descriptor
) return OS_Time
;
402 -- Get time stamp of file from file descriptor FD Returns Invalid_Time is
403 -- FD doesn't correspond to an existing file.
405 function Get_Debuggable_Suffix
return String_Access
;
406 -- Return the debuggable suffix convention. Usually this is the same as
407 -- the convention for Get_Executable_Suffix. The result is allocated on
408 -- the heap and should be freed after use to avoid storage leaks.
410 function Get_Executable_Suffix
return String_Access
;
411 -- Return the executable suffix convention. The result is allocated on the
412 -- heap and should be freed after use to avoid storage leaks.
414 function Get_Object_Suffix
return String_Access
;
415 -- Return the object suffix convention. The result is allocated on the heap
416 -- and should be freed after use to avoid storage leaks.
418 function Get_Target_Debuggable_Suffix
return String_Access
;
419 -- Return the target debuggable suffix convention. Usually this is the same
420 -- as the convention for Get_Executable_Suffix. The result is allocated on
421 -- the heap and should be freed after use to avoid storage leaks.
423 function Get_Target_Executable_Suffix
return String_Access
;
424 -- Return the target executable suffix convention. The result is allocated
425 -- on the heap and should be freed after use to avoid storage leaks.
427 function Get_Target_Object_Suffix
return String_Access
;
428 -- Return the target object suffix convention. The result is allocated on
429 -- the heap and should be freed after use to avoid storage leaks.
431 function Is_Absolute_Path
(Name
: String) return Boolean;
432 -- Returns True if Name is an absolute path name, i.e. it designates a
433 -- file or directory absolutely rather than relative to another directory.
435 function Is_Directory
(Name
: String) return Boolean;
436 -- Determines if the given string, Name, is the name of a directory.
437 -- Returns True if so, False otherwise. Name may be an absolute path
438 -- name or a relative path name, including a simple file name. If it is
439 -- a relative path name, it is relative to the current working directory.
441 function Is_Executable_File
(Name
: String) return Boolean;
442 -- Determines if the given string, Name, is the name of an existing file
443 -- that is executable. Returns True if so, False otherwise. Note that this
444 -- function simply interrogates the file attributes (e.g. using the C
445 -- function stat), so it does not indicate a situation in which a file may
446 -- not actually be readable due to some other process having exclusive
449 function Is_Owner_Readable_File
(Name
: String) return Boolean;
450 -- Determines if the given string, Name, is the name of an existing file
451 -- that is readable. Returns True if so, False otherwise. Note that this
452 -- function simply interrogates the file attributes (e.g. using the C
453 -- function stat), so it does not indicate a situation in which a file may
454 -- not actually be readable due to some other process having exclusive
457 function Is_Regular_File
(Name
: String) return Boolean;
458 -- Determines if the given string, Name, is the name of an existing
459 -- regular file. Returns True if so, False otherwise. Name may be an
460 -- absolute path name or a relative path name, including a simple file
461 -- name. If it is a relative path name, it is relative to the current
462 -- working directory.
464 function Is_Symbolic_Link
(Name
: String) return Boolean;
465 -- Determines if the given string, Name, is the path of a symbolic link on
466 -- systems that support it. Returns True if so, False if the path is not a
467 -- symbolic link or if the system does not support symbolic links.
469 -- A symbolic link is an indirect pointer to a file; its directory entry
470 -- contains the name of the file to which it is linked. Symbolic links may
471 -- span file systems and may refer to directories.
473 function Is_Owner_Writable_File
(Name
: String) return Boolean;
474 -- Determines if the given string, Name, is the name of an existing file
475 -- that is writable. Returns True if so, False otherwise. Note that this
476 -- function simply interrogates the file attributes (e.g. using the C
477 -- function stat), so it does not indicate a situation in which a file may
478 -- not actually be writable due to some other process having exclusive
481 function Is_Read_Accessible_File
(Name
: String) return Boolean;
482 -- Determines if the given string, Name, is the name of an existing file
483 -- that is readable. Returns True if so, False otherwise.
485 function Is_Write_Accessible_File
(Name
: String) return Boolean;
486 -- Determines if the given string, Name, is the name of an existing file
487 -- that is writable. Returns True if so, False otherwise.
489 function Is_Readable_File
(Name
: String) return Boolean
490 renames Is_Read_Accessible_File
;
491 function Is_Writable_File
(Name
: String) return Boolean
492 renames Is_Write_Accessible_File
;
493 -- These subprograms provided for backward compatibility and should not be
494 -- used. Use Is_Owner_Readable_File/Is_Owner_Writable_File or
495 -- Is_Read_Accessible_File/Is_Write_Accessible_File instead.
497 function Locate_Exec_On_Path
(Exec_Name
: String) return String_Access
;
498 -- Try to locate an executable whose name is given by Exec_Name in the
499 -- directories listed in the environment Path. If the Exec_Name does not
500 -- have the executable suffix, it will be appended before the search.
501 -- Otherwise works like Locate_Regular_File below. If the executable is
502 -- not found, null is returned.
504 -- Note that this function allocates memory for the returned value. This
505 -- memory needs to be deallocated after use.
507 function Locate_Regular_File
509 Path
: String) return String_Access
;
510 -- Try to locate a regular file whose name is given by File_Name in the
511 -- directories listed in Path. If a file is found, its full pathname is
512 -- returned; otherwise, a null pointer is returned. If the File_Name given
513 -- is an absolute pathname, then Locate_Regular_File just checks that the
514 -- file exists and is a regular file. Otherwise, if the File_Name given
515 -- includes directory information, Locate_Regular_File first checks if the
516 -- file exists relative to the current directory. If it does not, or if
517 -- the File_Name given is a simple file name, the Path argument is parsed
518 -- according to OS conventions, and for each directory in the Path a check
519 -- is made if File_Name is a relative pathname of a regular file from that
522 -- Note that this function allocates some memory for the returned value.
523 -- This memory needs to be deallocated after use.
525 Seek_Cur
: constant := 1;
526 Seek_End
: constant := 2;
527 Seek_Set
: constant := 0;
528 -- Used to indicate origin for Lseek call
531 (FD
: File_Descriptor
;
532 offset
: Long_Integer;
534 pragma Import
(C
, Lseek
, "__gnat_lseek");
535 -- Sets the current file pointer to the indicated offset value, relative
536 -- to the current position (origin = SEEK_CUR), end of file (origin =
537 -- SEEK_END), or start of file (origin = SEEK_SET).
539 function Normalize_Pathname
541 Directory
: String := "";
542 Resolve_Links
: Boolean := True;
543 Case_Sensitive
: Boolean := True) return String;
544 -- Returns a file name as an absolute path name, resolving all relative
545 -- directories, and symbolic links. If Name is a relative path, it is
546 -- interpreted relative to Directory, or to the current directory if
547 -- Directory is the empty string (the default). The result returned is
548 -- the normalized name of the file, containing no "." or ".." components,
549 -- and no duplicated directory separators. For most cases, if two file
550 -- names designate the same file through different paths,
551 -- Normalize_Pathname will return the same canonical name in both cases.
552 -- However, there are cases when this is not true; for example, this is
553 -- not true in Unix for two hard links designating the same file.
555 -- On Windows, the returned path will start with a drive letter. If
556 -- Directory is empty (the default) and Name is a relative path or an
557 -- absolute path without drive letter, the letter of the current drive
558 -- will start the returned path. If Case_Sensitive is True (the default),
559 -- then this drive letter will be forced to upper case ("C:\...").
561 -- If Resolve_Links is set to True, then the symbolic links, on systems
562 -- that support them, will be fully converted to the name of the file or
563 -- directory pointed to. This is slightly less efficient, since it
564 -- requires system calls.
566 -- If Name is empty or the path contains symbolic links that can't be
567 -- resolved (for example there is a symbolic link circularity,
568 -- e.g. A is a symbolic link for B, and B is a symbolic link for A), then
569 -- Normalize_Pathname returns an empty string.
571 -- For case-sensitive file systems, the value of Case_Sensitive parameter
572 -- is ignored. For file systems that are not case-sensitive, such as
573 -- Windows, if this parameter is set to False, then the file and directory
574 -- names are folded to lower case. This allows checking whether two files
575 -- are the same by applying this function to their names and comparing the
576 -- results. If Case_Sensitive is set to True, this function does not change
577 -- the casing of file and directory names.
581 Fmode
: Mode
) return File_Descriptor
;
582 -- Opens file Name for appending, returning its file descriptor. File
583 -- descriptor returned is Invalid_FD if the file cannot be successfully
588 Fmode
: Mode
) return File_Descriptor
;
589 -- Open file Name for reading, returning its file descriptor. File
590 -- descriptor returned is Invalid_FD if the file cannot be opened.
592 function Open_Read_Write
594 Fmode
: Mode
) return File_Descriptor
;
595 -- Open file Name for both reading and writing, returning its file
596 -- descriptor. File descriptor returned is Invalid_FD if the file
600 (FD
: File_Descriptor
;
602 N
: Integer) return Integer;
603 -- Read N bytes to address A from file referenced by FD. Returned value is
604 -- count of bytes actually read, which can be less than N at EOF.
606 procedure Rename_File
609 Success
: out Boolean);
610 -- Rename a file. Success is set True or False indicating if the rename is
611 -- successful or not.
613 -- WARNING: In one very important respect, this function is significantly
614 -- non-portable. If New_Name already exists then on Unix systems, the call
615 -- deletes the existing file, and the call signals success. On Windows, the
616 -- call fails, without doing the rename operation. See also the procedure
617 -- Ada.Directories.Rename, which portably provides the windows semantics,
618 -- i.e. fails if the output file already exists.
620 -- The following defines the mode for the Copy_File procedure below. Note
621 -- that "time stamps and other file attributes" in the descriptions below
622 -- refers to the creation and last modification times, and also the file
623 -- access (read/write/execute) status flags.
625 procedure Set_Close_On_Exec
626 (FD
: File_Descriptor
;
627 Close_On_Exec
: Boolean;
628 Status
: out Boolean);
629 -- When Close_On_Exec is True, mark FD to be closed automatically when new
630 -- program is executed by the calling process (i.e. prevent FD from being
631 -- inherited by child processes). When Close_On_Exec is False, mark FD to
632 -- not be closed on exec (i.e. allow it to be inherited). Status is False
633 -- if the operation could not be performed.
635 S_Owner
: constant := 1;
636 S_Group
: constant := 2;
637 S_Others
: constant := 4;
638 -- Constants for use in Mode parameter to Set_Executable
640 procedure Set_Executable
(Name
: String; Mode
: Positive := S_Owner
);
641 -- Change permissions on the file given by Name to make it executable
642 -- for its owner, group or others, according to the setting of Mode.
643 -- As indicated, the default if no Mode parameter is given is owner.
645 procedure Set_File_Last_Modify_Time_Stamp
(Name
: String; Time
: OS_Time
);
646 -- Given the name of a file or directory, Name, set the last modification
647 -- time stamp. This function must be used for an unopened file.
649 procedure Set_Non_Readable
(Name
: String);
650 -- Change permissions on the named file to make it non-readable for
651 -- its owner. The writable and executable permissions are not
654 procedure Set_Non_Writable
(Name
: String);
655 -- Change permissions on the named file to make it non-writable for its
656 -- owner. The readable and executable permissions are not modified.
658 procedure Set_Read_Only
(Name
: String) renames Set_Non_Writable
;
659 -- This renaming is provided for backwards compatibility with previous
660 -- versions. The use of Set_Non_Writable is preferred (clearer name).
662 procedure Set_Readable
(Name
: String);
663 -- Change permissions on the named file to make it readable for its
666 procedure Set_Writable
(Name
: String);
667 -- Change permissions on the named file to make it writable for its owner
670 (FD
: File_Descriptor
;
672 N
: Integer) return Integer;
673 -- Write N bytes from address A to file referenced by FD. The returned
674 -- value is the number of bytes written, which can be less than N if a
675 -- disk full condition was detected.
677 -- The following section contains low-level routines using addresses to
678 -- pass file name and executable name. In each routine the name must be
679 -- Nul-Terminated. For complete documentation refer to the equivalent
680 -- routine (using String in place of C_File_Name) defined above.
682 subtype C_File_Name
is System
.Address
;
683 -- This subtype is used to document that a parameter is the address of a
684 -- null-terminated string containing the name of a file.
688 Pathname
: C_File_Name
;
689 Success
: out Boolean;
690 Mode
: Copy_Mode
:= Copy
;
691 Preserve
: Attribute
:= Time_Stamps
);
693 procedure Copy_Time_Stamps
694 (Source
: C_File_Name
;
696 Success
: out Boolean);
700 Fmode
: Mode
) return File_Descriptor
;
702 function Create_New_File
704 Fmode
: Mode
) return File_Descriptor
;
706 procedure Delete_File
(Name
: C_File_Name
; Success
: out Boolean);
708 function File_Time_Stamp
(Name
: C_File_Name
) return OS_Time
;
710 function Is_Directory
(Name
: C_File_Name
) return Boolean;
711 function Is_Executable_File
(Name
: C_File_Name
) return Boolean;
712 function Is_Owner_Readable_File
(Name
: C_File_Name
) return Boolean;
713 function Is_Regular_File
(Name
: C_File_Name
) return Boolean;
714 function Is_Symbolic_Link
(Name
: C_File_Name
) return Boolean;
715 function Is_Owner_Writable_File
(Name
: C_File_Name
) return Boolean;
717 function Locate_Regular_File
718 (File_Name
: C_File_Name
;
719 Path
: C_File_Name
) return String_Access
;
723 Fmode
: Mode
) return File_Descriptor
;
727 Fmode
: Mode
) return File_Descriptor
;
729 function Open_Read_Write
731 Fmode
: Mode
) return File_Descriptor
;
733 procedure Rename_File
734 (Old_Name
: C_File_Name
;
735 New_Name
: C_File_Name
;
736 Success
: out Boolean);
742 subtype Argument_List
is String_List
;
743 -- Type used for argument list in call to Spawn. The lower bound of the
744 -- array should be 1, and the length of the array indicates the number of
747 subtype Argument_List_Access
is String_List_Access
;
748 -- Type used to return Argument_List without dragging in secondary stack.
749 -- Note that there is a Free procedure declared for this subtype which
750 -- frees the array and all referenced strings.
752 type Process_Id
is private;
753 -- A private type used to identify a process activated by the following
754 -- non-blocking calls. The only meaningful operation on this type is a
755 -- comparison for equality.
757 Invalid_Pid
: constant Process_Id
;
758 -- A special value used to indicate errors, as described below
760 function Current_Process_Id
return Process_Id
;
761 -- Returns the current process id or Invalid_Pid if not supported by the
764 function Argument_String_To_List
765 (Arg_String
: String) return Argument_List_Access
;
766 -- Take a string that is a program and its arguments and parse it into an
767 -- Argument_List. Note that the result is allocated on the heap, and must
768 -- be freed by the programmer (when it is no longer needed) to avoid
770 -- On Windows, backslashes are used as directory separators. On Unix,
771 -- however, they are used to escape the following character, so that for
772 -- instance "-d=name\ with\ space" is a single argument. In the result
773 -- list, the backslashes have been cleaned up when needed. The previous
774 -- example will thus result a single-element array, where the element is
775 -- "-d=name with space" (Unix) or "-d=name\ with\ space" (windows).
777 procedure Kill
(Pid
: Process_Id
; Hard_Kill
: Boolean := True);
778 -- Kill the process designated by Pid. Does nothing if Pid is Invalid_Pid
779 -- or on platforms where it is not supported, such as VxWorks. Hard_Kill
780 -- is True by default, and when True the process is terminated immediately.
781 -- If Hard_Kill is False, then a signal SIGINT is sent to the process on
782 -- POSIX OS or a ctrl-C event on Windows, allowing the process a chance to
783 -- terminate properly using a corresponding handler.
785 procedure Kill_Process_Tree
(Pid
: Process_Id
; Hard_Kill
: Boolean := True);
786 -- Kill the process designated by Pid and all it's children processes.
787 -- Does nothing if Pid is Invalid_Pid or on platforms where it is not
788 -- supported, such as VxWorks. Hard_Kill is True by default, and when True
789 -- the processes are terminated immediately. If Hard_Kill is False, then a
790 -- signal SIGINT is sent to the processes on POSIX OS or a ctrl-C event
791 -- on Windows, allowing the processes a chance to terminate properly
792 -- using a corresponding handler.
794 -- Note that this routine is not atomic and is supported only on Linux
795 -- and Windows. On other OS it will only kill the process identified by
798 function Non_Blocking_Spawn
799 (Program_Name
: String;
800 Args
: Argument_List
) return Process_Id
;
801 -- This is a non blocking call. The Process_Id of the spawned process is
802 -- returned. Parameters are to be used as in Spawn. If Invalid_Pid is
803 -- returned the program could not be spawned.
805 -- Spawning processes from tasking programs is not recommended. See
806 -- "NOTE: Spawn in tasking programs" below.
808 -- This function will always return Invalid_Pid under VxWorks, since there
809 -- is no notion of executables under this OS.
811 function Non_Blocking_Spawn
812 (Program_Name
: String;
813 Args
: Argument_List
;
814 Output_File_Descriptor
: File_Descriptor
;
815 Err_To_Out
: Boolean := True) return Process_Id
;
816 -- Similar to the procedure above, but redirects the output to the file
817 -- designated by Output_File_Descriptor. If Err_To_Out is True, then the
818 -- Standard Error output is also redirected. Invalid_Pid is returned
819 -- if the program could not be spawned successfully.
821 -- Spawning processes from tasking programs is not recommended. See
822 -- "NOTE: Spawn in tasking programs" below.
824 -- This function will always return Invalid_Pid under VxWorks, since there
825 -- is no notion of executables under this OS.
827 function Non_Blocking_Spawn
828 (Program_Name
: String;
829 Args
: Argument_List
;
830 Output_File
: String;
831 Err_To_Out
: Boolean := True) return Process_Id
;
832 -- Similar to the procedure above, but saves the output of the command to
833 -- a file with the name Output_File.
835 -- Invalid_Pid is returned if the output file could not be created or if
836 -- the program could not be spawned successfully.
838 -- Spawning processes from tasking programs is not recommended. See
839 -- "NOTE: Spawn in tasking programs" below.
841 -- This function will always return Invalid_Pid under VxWorks, since there
842 -- is no notion of executables under this OS.
844 function Non_Blocking_Spawn
845 (Program_Name
: String;
846 Args
: Argument_List
;
847 Stdout_File
: String;
848 Stderr_File
: String) return Process_Id
;
849 -- Similar to the procedure above, but saves the standard output of the
850 -- command to a file with the name Stdout_File and the standard output
851 -- of the command to a file with the name Stderr_File.
853 procedure Normalize_Arguments
(Args
: in out Argument_List
);
854 -- Normalize all arguments in the list. This ensure that the argument list
855 -- is compatible with the running OS and will works fine with Spawn and
856 -- Non_Blocking_Spawn for example. If Normalize_Arguments is called twice
857 -- on the same list it will do nothing the second time. Note that Spawn
858 -- and Non_Blocking_Spawn call Normalize_Arguments automatically, but
859 -- since there is a guarantee that a second call does nothing, this
860 -- internal call will have no effect if Normalize_Arguments is called
861 -- before calling Spawn. The call to Normalize_Arguments assumes that the
862 -- individual referenced arguments in Argument_List are on the heap, and
863 -- may free them and reallocate if they are modified.
865 function Pid_To_Integer
(Pid
: Process_Id
) return Integer;
866 -- Convert a process id to an Integer. Useful for writing hash functions
867 -- for type Process_Id or to compare two Process_Id (e.g. for sorting).
870 (Program_Name
: String;
871 Args
: Argument_List
;
872 Success
: out Boolean);
873 -- This procedure spawns a program with a given list of arguments. The
874 -- first parameter of is the name of the executable. The second parameter
875 -- contains the arguments to be passed to this program. Success is False
876 -- if the named program could not be spawned or its execution completed
877 -- unsuccessfully. Note that the caller will be blocked until the
878 -- execution of the spawned program is complete. For maximum portability,
879 -- use a full path name for the Program_Name argument. On some systems
880 -- (notably Unix systems) a simple file name may also work (if the
881 -- executable can be located in the path).
883 -- Spawning processes from tasking programs is not recommended. See
884 -- "NOTE: Spawn in tasking programs" below.
886 -- Note: Arguments in Args that contain spaces and/or quotes such as
887 -- "--GCC=gcc -v" or "--GCC=""gcc -v""" are not portable across all
888 -- operating systems, and would not have the desired effect if they were
889 -- passed directly to the operating system. To avoid this problem, Spawn
890 -- makes an internal call to Normalize_Arguments, which ensures that such
891 -- arguments are modified in a manner that ensures that the desired effect
892 -- is obtained on all operating systems. The caller may call
893 -- Normalize_Arguments explicitly before the call (e.g. to print out the
894 -- exact form of arguments passed to the operating system). In this case
895 -- the guarantee a second call to Normalize_Arguments has no effect
896 -- ensures that the internal call will not affect the result. Note that
897 -- the implicit call to Normalize_Arguments may free and reallocate some
898 -- of the individual arguments.
900 -- This function will always set Success to False under VxWorks and other
901 -- similar operating systems which have no notion of the concept of
902 -- dynamically executable file. Otherwise Success is set True if the exit
903 -- status of the spawned process is zero.
906 (Program_Name
: String;
907 Args
: Argument_List
) return Integer;
908 -- Similar to the above procedure, but returns the actual status returned
909 -- by the operating system, or -1 under VxWorks and any other similar
910 -- operating systems which have no notion of separately spawnable programs.
912 -- Spawning processes from tasking programs is not recommended. See
913 -- "NOTE: Spawn in tasking programs" below.
916 (Program_Name
: String;
917 Args
: Argument_List
;
918 Output_File_Descriptor
: File_Descriptor
;
919 Return_Code
: out Integer;
920 Err_To_Out
: Boolean := True);
921 -- Similar to the procedure above, but redirects the output to the file
922 -- designated by Output_File_Descriptor. If Err_To_Out is True, then the
923 -- Standard Error output is also redirected.
924 -- Return_Code is set to the status code returned by the operating system
926 -- Spawning processes from tasking programs is not recommended. See
927 -- "NOTE: Spawn in tasking programs" below.
930 (Program_Name
: String;
931 Args
: Argument_List
;
932 Output_File
: String;
933 Success
: out Boolean;
934 Return_Code
: out Integer;
935 Err_To_Out
: Boolean := True);
936 -- Similar to the procedure above, but saves the output of the command to
937 -- a file with the name Output_File.
939 -- Success is set to True if the command is executed and its output
940 -- successfully written to the file. If Success is True, then Return_Code
941 -- will be set to the status code returned by the operating system.
942 -- Otherwise, Return_Code is undefined.
944 -- Spawning processes from tasking programs is not recommended. See
945 -- "NOTE: Spawn in tasking programs" below.
947 procedure Wait_Process
(Pid
: out Process_Id
; Success
: out Boolean);
948 -- Wait for the completion of any of the processes created by previous
949 -- calls to Non_Blocking_Spawn. The caller will be suspended until one of
950 -- these processes terminates (normally or abnormally). If any of these
951 -- subprocesses terminates prior to the call to Wait_Process (and has not
952 -- been returned by a previous call to Wait_Process), then the call to
953 -- Wait_Process is immediate. Pid identifies the process that has
954 -- terminated (matching the value returned from Non_Blocking_Spawn).
955 -- Success is set to True if this sub-process terminated successfully. If
956 -- Pid = Invalid_Pid, there were no subprocesses left to wait on.
958 -- This function will always set success to False under VxWorks, since
959 -- there is no notion of executables under this OS.
961 procedure Non_Blocking_Wait_Process
962 (Pid
: out Process_Id
; Success
: out Boolean);
963 -- Same as Wait_Process, except if there are no completed child processes,
964 -- return immediately without blocking, and return Invalid_Pid in Pid.
965 -- Not supported on all platforms; Success = False if not supported.
967 -------------------------------------
968 -- NOTE: Spawn in Tasking Programs --
969 -------------------------------------
971 -- Spawning processes in tasking programs using the above Spawn and
972 -- Non_Blocking_Spawn subprograms is not recommended, because there are
973 -- subtle interactions between creating a process and signals/locks that
974 -- can cause trouble. These issues are not specific to Ada; they depend
975 -- primarily on the operating system.
977 -- If you need to spawn processes in a tasking program, you will need to
978 -- understand the semantics of your operating system, and you are likely to
979 -- write non-portable code, because operating systems differ in this area.
981 -- The Spawn and Non_Blocking_Spawn subprograms call the following
982 -- operating system functions:
984 -- On Windows: spawnvp (blocking) or CreateProcess (non-blocking)
986 -- On Solaris: fork1, followed in the child process by execv
988 -- On other Unix-like systems: fork, followed in the child
991 -- On vxworks, spawning of processes is not supported
993 -- For details, look at the functions __gnat_portable_spawn and
994 -- __gnat_portable_no_block_spawn in adaint.c.
996 -- You should read the operating-system-specific documentation for the
997 -- above functions, paying special attention to subtle interactions with
998 -- threading, signals, locks, and file descriptors. Most of the issues are
999 -- related to the fact that on Unix, there is a window of time between fork
1000 -- and execv; Windows does not have this problem, because spawning is done
1001 -- in a single operation.
1003 -- On Posix-compliant systems, such as Linux, fork duplicates just the
1004 -- calling thread. (On Solaris, fork1 is the Posix-compliant version of
1007 -- You should avoid using signals while spawning. This includes signals
1008 -- used internally by the Ada run-time system, such as timer signals used
1009 -- to implement delay statements.
1011 -- It is best to spawn any subprocesses very early, before the parent
1012 -- process creates tasks, locks, or installs signal handlers. Certainly
1013 -- avoid doing simultaneous spawns from multiple threads of the same
1016 -- There is no problem spawning a subprocess that uses tasking: the
1017 -- problems are caused only by tasking in the parent.
1019 -- If the parent is using tasking, and needs to spawn subprocesses at
1020 -- arbitrary times, one technique is for the parent to spawn (very early)
1021 -- a particular spawn-manager subprocess whose job is to spawn other
1022 -- processes. The spawn-manager must avoid tasking. The parent sends
1023 -- messages to the spawn-manager requesting it to spawn processes, using
1024 -- whatever inter-process communication mechanism you like, such as
1027 -- In short, mixing spawning of subprocesses with tasking is a tricky
1028 -- business, and should be avoided if possible, but if it is necessary,
1029 -- the above guidelines should be followed, and you should beware of
1030 -- portability problems.
1036 function Errno
return Integer;
1037 pragma Import
(C
, Errno
, "__get_errno");
1038 -- Return the task-safe last error number
1040 function Errno_Message
1041 (Err
: Integer := Errno
;
1042 Default
: String := "") return String;
1043 -- Return a message describing the given Errno value. If none is provided
1044 -- by the system, return Default if not empty, else return a generic
1045 -- message indicating the numeric errno value.
1047 function Getenv
(Name
: String) return String_Access
;
1048 -- Get the value of the environment variable. Returns an access to the
1049 -- empty string if the environment variable does not exist or has an
1050 -- explicit null value (in some operating systems these are distinct
1051 -- cases, in others they are not; this interface abstracts away that
1052 -- difference. The argument is allocated on the heap (even in the null
1053 -- case), and needs to be freed explicitly when no longer needed to avoid
1057 pragma Import
(C
, OS_Abort
, "abort");
1058 pragma No_Return
(OS_Abort
);
1059 -- Exit to OS signalling an abort (traceback or other appropriate
1060 -- diagnostic information should be given if possible, or entry made to
1061 -- the debugger if that is possible).
1063 procedure OS_Exit
(Status
: Integer);
1064 pragma No_Return
(OS_Exit
);
1065 -- Exit to OS with given status code (program is terminated). Note that
1066 -- this is abrupt termination. All tasks are immediately terminated. There
1067 -- are no finalization or other Ada-specific cleanup actions performed. On
1068 -- systems with atexit handlers (such as Unix and Windows), atexit handlers
1071 type OS_Exit_Subprogram
is access procedure (Status
: Integer);
1073 procedure OS_Exit_Default
(Status
: Integer);
1074 pragma No_Return
(OS_Exit_Default
);
1075 -- Default implementation of procedure OS_Exit
1077 OS_Exit_Ptr
: OS_Exit_Subprogram
:= OS_Exit_Default
'Access;
1078 -- OS_Exit is implemented through this access value. It it then possible to
1079 -- change the implementation of OS_Exit by redirecting OS_Exit_Ptr to an
1080 -- other implementation.
1082 procedure Set_Errno
(Errno
: Integer);
1083 pragma Import
(C
, Set_Errno
, "__set_errno");
1084 -- Set the task-safe error number
1086 procedure Setenv
(Name
: String; Value
: String);
1087 -- Set the value of the environment variable Name to Value. This call
1088 -- modifies the current environment, but does not modify the parent
1089 -- process environment. After a call to Setenv, Getenv (Name) will always
1090 -- return a String_Access referencing the same String as Value. This is
1091 -- true also for the null string case (the actual effect may be to either
1092 -- set an explicit null as the value, or to remove the entry, this is
1093 -- operating system dependent). Note that any following calls to Spawn
1094 -- will pass an environment to the spawned process that includes the
1095 -- changes made by Setenv calls.
1097 Directory_Separator
: constant Character;
1098 -- The character that is used to separate parts of a pathname
1100 Path_Separator
: constant Character;
1101 -- The character to separate paths in an environment variable value
1104 pragma Import
(C
, Path_Separator
, "__gnat_path_separator");
1105 pragma Import
(C
, Directory_Separator
, "__gnat_dir_separator");
1106 pragma Import
(C
, Current_Time
, "__gnat_current_time");
1107 pragma Import
(C
, Current_Process_Id
, "__gnat_current_process_id");
1110 range -(2 ** 63) .. +(2 ** 63 - 1);
1111 -- Type used for timestamps in the compiler. This type is used to hold
1112 -- time stamps, but may have a different representation than C's time_t.
1113 -- This type needs to match the declaration of OS_Time in adaint.h.
1115 Invalid_Time
: constant OS_Time
:= -1;
1116 -- This value should match the return value from __gnat_file_time_*
1118 pragma Import
(Intrinsic
, "<");
1119 pragma Import
(Intrinsic
, ">");
1120 pragma Import
(Intrinsic
, "<=");
1121 pragma Import
(Intrinsic
, ">=");
1122 pragma Inline
(To_C
);
1123 pragma Inline
(To_Ada
);
1125 type Process_Id
is new Integer;
1126 Invalid_Pid
: constant Process_Id
:= -1;