1------------------------------------------------------------------------------ 2-- -- 3-- GNAT COMPILER COMPONENTS -- 4-- -- 5-- S Y S T E M . O S _ L I B -- 6-- -- 7-- S p e c -- 8-- -- 9-- Copyright (C) 1995-2013, Free Software Foundation, Inc. -- 10-- -- 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. -- 17-- -- 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. -- 21-- -- 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/>. -- 26-- -- 27-- GNAT was originally developed by the GNAT team at New York University. -- 28-- Extensive contributions were provided by Ada Core Technologies Inc. -- 29-- -- 30------------------------------------------------------------------------------ 31 32-- Operating system interface facilities 33 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. 39 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. 43 44-- Except where specifically noted, these routines are portable across all 45-- GNAT implementations on all supported operating systems. 46 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). 50 51-- Note: a distinct body for this spec is included in the .NET runtime library 52-- and must be kept in sync with changes made in this file. 53 54pragma Compiler_Unit_Warning; 55 56with System; 57with System.Strings; 58 59package System.OS_Lib is 60 pragma Preelaborate; 61 62 ----------------------- 63 -- String Operations -- 64 ----------------------- 65 66 -- These are reexported from package Strings (which was introduced to 67 -- avoid different packages declaring different types unnecessarily). 68 -- See package System.Strings for details. 69 70 subtype String_Access is Strings.String_Access; 71 72 function "=" (Left, Right : String_Access) return Boolean 73 renames Strings."="; 74 75 procedure Free (X : in out String_Access) renames Strings.Free; 76 77 subtype String_List is Strings.String_List; 78 79 function "=" (Left, Right : String_List) return Boolean 80 renames Strings."="; 81 82 function "&" (Left : String_Access; Right : String_Access) 83 return String_List renames Strings."&"; 84 function "&" (Left : String_Access; Right : String_List) 85 return String_List renames Strings."&"; 86 function "&" (Left : String_List; Right : String_Access) 87 return String_List renames Strings."&"; 88 function "&" (Left : String_List; Right : String_List) 89 return String_List renames Strings."&"; 90 91 subtype String_List_Access is Strings.String_List_Access; 92 93 function "=" (Left, Right : String_List_Access) return Boolean 94 renames Strings."="; 95 96 procedure Free (Arg : in out String_List_Access) 97 renames Strings.Free; 98 99 --------------------- 100 -- Time/Date Stuff -- 101 --------------------- 102 103 type OS_Time is private; 104 -- The OS's notion of time is represented by the private type OS_Time. 105 -- This is the type returned by the File_Time_Stamp functions to obtain 106 -- the time stamp of a specified file. Functions and a procedure (modeled 107 -- after the similar subprograms in package Calendar) are provided for 108 -- extracting information from a value of this type. Although these are 109 -- called GM, the intention is not that they provide GMT times in all 110 -- cases but rather the actual (time-zone independent) time stamp of the 111 -- file (of course in Unix systems, this *is* in GMT form). 112 113 Invalid_Time : constant OS_Time; 114 -- A special unique value used to flag an invalid time stamp value 115 116 subtype Year_Type is Integer range 1900 .. 2099; 117 subtype Month_Type is Integer range 1 .. 12; 118 subtype Day_Type is Integer range 1 .. 31; 119 subtype Hour_Type is Integer range 0 .. 23; 120 subtype Minute_Type is Integer range 0 .. 59; 121 subtype Second_Type is Integer range 0 .. 59; 122 -- Declarations similar to those in Calendar, breaking down the time 123 124 function Current_Time return OS_Time; 125 -- Return the system clock value as OS_Time 126 127 function GM_Year (Date : OS_Time) return Year_Type; 128 function GM_Month (Date : OS_Time) return Month_Type; 129 function GM_Day (Date : OS_Time) return Day_Type; 130 function GM_Hour (Date : OS_Time) return Hour_Type; 131 function GM_Minute (Date : OS_Time) return Minute_Type; 132 function GM_Second (Date : OS_Time) return Second_Type; 133 -- Functions to extract information from OS_Time value 134 135 function "<" (X, Y : OS_Time) return Boolean; 136 function ">" (X, Y : OS_Time) return Boolean; 137 function ">=" (X, Y : OS_Time) return Boolean; 138 function "<=" (X, Y : OS_Time) return Boolean; 139 -- Basic comparison operators on OS_Time with obvious meanings. Note that 140 -- these have Intrinsic convention, so for example it is not permissible 141 -- to create accesses to any of these functions. 142 143 procedure GM_Split 144 (Date : OS_Time; 145 Year : out Year_Type; 146 Month : out Month_Type; 147 Day : out Day_Type; 148 Hour : out Hour_Type; 149 Minute : out Minute_Type; 150 Second : out Second_Type); 151 -- Analogous to the Split routine in Ada.Calendar, takes an OS_Time and 152 -- provides a representation of it as a set of component parts, to be 153 -- interpreted as a date point in UTC. 154 155 ---------------- 156 -- File Stuff -- 157 ---------------- 158 159 -- These routines give access to the open/creat/close/read/write level of 160 -- I/O routines in the typical C library (these functions are not part of 161 -- the ANSI C standard, but are typically available in all systems). See 162 -- also package Interfaces.C_Streams for access to the stream level 163 -- routines. 164 165 -- Note on file names. If a file name is passed as type String in any of 166 -- the following specifications, then the name is a normal Ada string and 167 -- need not be NUL-terminated. However, a trailing NUL character is 168 -- permitted, and will be ignored (more accurately, the NUL and any 169 -- characters that follow it will be ignored). 170 171 type File_Descriptor is new Integer; 172 -- Corresponds to the int file handle values used in the C routines 173 174 Standin : constant File_Descriptor := 0; 175 Standout : constant File_Descriptor := 1; 176 Standerr : constant File_Descriptor := 2; 177 -- File descriptors for standard input output files 178 179 Invalid_FD : constant File_Descriptor := -1; 180 -- File descriptor returned when error in opening/creating file 181 182 type Mode is (Binary, Text); 183 for Mode'Size use Integer'Size; 184 for Mode use (Binary => 0, Text => 1); 185 -- Used in all the Open and Create calls to specify if the file is to be 186 -- opened in binary mode or text mode. In systems like Unix, this has no 187 -- effect, but in systems capable of text mode translation, the use of 188 -- Text as the mode parameter causes the system to do CR/LF translation 189 -- and also to recognize the DOS end of file character on input. The use 190 -- of Text where appropriate allows programs to take a portable Unix view 191 -- of DOS-format files and process them appropriately. 192 193 function Open_Read 194 (Name : String; 195 Fmode : Mode) return File_Descriptor; 196 -- Open file Name for reading, returning file descriptor File descriptor 197 -- returned is Invalid_FD if file cannot be opened. 198 199 function Open_Read_Write 200 (Name : String; 201 Fmode : Mode) return File_Descriptor; 202 -- Open file Name for both reading and writing, returning file descriptor. 203 -- File descriptor returned is Invalid_FD if file cannot be opened. 204 205 function Create_File 206 (Name : String; 207 Fmode : Mode) return File_Descriptor; 208 -- Creates new file with given name for writing, returning file descriptor 209 -- for subsequent use in Write calls. If the file already exists, it is 210 -- overwritten. File descriptor returned is Invalid_FD if file cannot be 211 -- successfully created. 212 213 function Create_Output_Text_File (Name : String) return File_Descriptor; 214 -- Creates new text file with given name suitable to redirect standard 215 -- output, returning file descriptor. File descriptor returned is 216 -- Invalid_FD if file cannot be successfully created. 217 218 function Create_New_File 219 (Name : String; 220 Fmode : Mode) return File_Descriptor; 221 -- Create new file with given name for writing, returning file descriptor 222 -- for subsequent use in Write calls. This differs from Create_File in 223 -- that it fails if the file already exists. File descriptor returned is 224 -- Invalid_FD if the file exists or cannot be created. 225 226 Temp_File_Len : constant Integer := 12; 227 -- Length of name returned by Create_Temp_File call (GNAT-XXXXXX & NUL) 228 229 subtype Temp_File_Name is String (1 .. Temp_File_Len); 230 -- String subtype set by Create_Temp_File 231 232 procedure Create_Temp_File 233 (FD : out File_Descriptor; 234 Name : out Temp_File_Name); 235 -- Create and open for writing a temporary file in the current working 236 -- directory. The name of the file and the File Descriptor are returned. 237 -- The File Descriptor returned is Invalid_FD in the case of failure. No 238 -- mode parameter is provided. Since this is a temporary file, there is no 239 -- point in doing text translation on it. 240 -- 241 -- On some operating systems, the maximum number of temp files that can be 242 -- created with this procedure may be limited. When the maximum is reached, 243 -- this procedure returns Invalid_FD. On some operating systems, there may 244 -- be a race condition between processes trying to create temp files at the 245 -- same time in the same directory using this procedure. 246 247 procedure Create_Temp_File 248 (FD : out File_Descriptor; 249 Name : out String_Access); 250 -- Create and open for writing a temporary file in the current working 251 -- directory. The name of the file and the File Descriptor are returned. 252 -- It is the responsibility of the caller to deallocate the access value 253 -- returned in Name. 254 -- 255 -- The file is opened in binary mode (no text translation). 256 -- 257 -- This procedure will always succeed if the current working directory is 258 -- writable. If the current working directory is not writable, then 259 -- Invalid_FD is returned for the file descriptor and null for the Name. 260 -- There is no race condition problem between processes trying to create 261 -- temp files at the same time in the same directory. 262 263 procedure Create_Temp_Output_File 264 (FD : out File_Descriptor; 265 Name : out String_Access); 266 -- Create and open for writing a temporary file in the current working 267 -- directory suitable to redirect standard output. The name of the file and 268 -- the File Descriptor are returned. It is the responsibility of the caller 269 -- to deallocate the access value returned in Name. 270 -- 271 -- The file is opened in text mode 272 -- 273 -- This procedure will always succeed if the current working directory is 274 -- writable. If the current working directory is not writable, then 275 -- Invalid_FD is returned for the file descriptor and null for the Name. 276 -- There is no race condition problem between processes trying to create 277 -- temp files at the same time in the same directory. 278 279 procedure Close (FD : File_Descriptor; Status : out Boolean); 280 -- Close file referenced by FD. Status is False if the underlying service 281 -- failed. Reasons for failure include: disk full, disk quotas exceeded 282 -- and invalid file descriptor (the file may have been closed twice). 283 284 procedure Close (FD : File_Descriptor); 285 -- Close file referenced by FD. This form is used when the caller wants to 286 -- ignore any possible error (see above for error cases). 287 288 procedure Set_Close_On_Exec 289 (FD : File_Descriptor; 290 Close_On_Exec : Boolean; 291 Status : out Boolean); 292 -- When Close_On_Exec is True, mark FD to be closed automatically when new 293 -- program is executed by the calling process (i.e. prevent FD from being 294 -- inherited by child processes). When Close_On_Exec is False, mark FD to 295 -- not be closed on exec (i.e. allow it to be inherited). Status is False 296 -- if the operation could not be performed. 297 298 procedure Delete_File (Name : String; Success : out Boolean); 299 -- Deletes file. Success is set True or False indicating if the delete is 300 -- successful. 301 302 procedure Rename_File 303 (Old_Name : String; 304 New_Name : String; 305 Success : out Boolean); 306 -- Rename a file. Success is set True or False indicating if the rename is 307 -- successful or not. 308 -- 309 -- WARNING: In one very important respect, this function is significantly 310 -- non-portable. If New_Name already exists then on Unix systems, the call 311 -- deletes the existing file, and the call signals success. On Windows, the 312 -- call fails, without doing the rename operation. See also the procedure 313 -- Ada.Directories.Rename, which portably provides the windows semantics, 314 -- i.e. fails if the output file already exists. 315 316 -- The following defines the mode for the Copy_File procedure below. Note 317 -- that "time stamps and other file attributes" in the descriptions below 318 -- refers to the creation and last modification times, and also the file 319 -- access (read/write/execute) status flags. 320 321 type Copy_Mode is 322 (Copy, 323 -- Copy the file. It is an error if the target file already exists. The 324 -- time stamps and other file attributes are preserved in the copy. 325 326 Overwrite, 327 -- If the target file exists, the file is replaced otherwise the file 328 -- is just copied. The time stamps and other file attributes are 329 -- preserved in the copy. 330 331 Append); 332 -- If the target file exists, the contents of the source file is 333 -- appended at the end. Otherwise the source file is just copied. The 334 -- time stamps and other file attributes are preserved if the 335 -- destination file does not exist. 336 337 type Attribute is 338 (Time_Stamps, 339 -- Copy time stamps from source file to target file. All other 340 -- attributes are set to normal default values for file creation. 341 342 Full, 343 -- All attributes are copied from the source file to the target file. 344 -- This includes the timestamps, and for example also includes 345 -- read/write/execute attributes in Unix systems. 346 347 None); 348 -- No attributes are copied. All attributes including the time stamp 349 -- values are set to normal default values for file creation. 350 351 -- Note: The default is Time_Stamps, which corresponds to the normal 352 -- default on Windows style systems. Full corresponds to the typical 353 -- effect of "cp -p" on Unix systems, and None corresponds to the typical 354 -- effect of "cp" on Unix systems. 355 356 -- Note: Time_Stamps and Full are not supported on VMS and VxWorks 5 357 358 procedure Copy_File 359 (Name : String; 360 Pathname : String; 361 Success : out Boolean; 362 Mode : Copy_Mode := Copy; 363 Preserve : Attribute := Time_Stamps); 364 -- Copy a file. Name must designate a single file (no wild cards allowed). 365 -- Pathname can be a filename or directory name. In the latter case Name 366 -- is copied into the directory preserving the same file name. Mode 367 -- defines the kind of copy, see above with the default being a normal 368 -- copy in which the target file must not already exist. Success is set to 369 -- True or False indicating if the copy is successful (depending on the 370 -- specified Mode). 371 -- 372 -- Note: this procedure is only supported to a very limited extent on VMS. 373 -- The only supported mode is Overwrite, and the only supported value for 374 -- Preserve is None, resulting in the default action which for Overwrite 375 -- is to leave attributes unchanged. Furthermore, the copy only works for 376 -- simple text files. 377 378 procedure Copy_Time_Stamps (Source, Dest : String; Success : out Boolean); 379 -- Copy Source file time stamps (last modification and last access time 380 -- stamps) to Dest file. Source and Dest must be valid filenames, 381 -- furthermore Dest must be writable. Success will be set to True if the 382 -- operation was successful and False otherwise. 383 -- 384 -- Note: this procedure is not supported on VMS and VxWorks 5. On these 385 -- platforms, Success is always set to False. 386 387 function Read 388 (FD : File_Descriptor; 389 A : System.Address; 390 N : Integer) return Integer; 391 -- Read N bytes to address A from file referenced by FD. Returned value is 392 -- count of bytes actually read, which can be less than N at EOF. 393 394 function Write 395 (FD : File_Descriptor; 396 A : System.Address; 397 N : Integer) return Integer; 398 -- Write N bytes from address A to file referenced by FD. The returned 399 -- value is the number of bytes written, which can be less than N if a 400 -- disk full condition was detected. 401 402 Seek_Cur : constant := 1; 403 Seek_End : constant := 2; 404 Seek_Set : constant := 0; 405 -- Used to indicate origin for Lseek call 406 407 procedure Lseek 408 (FD : File_Descriptor; 409 offset : Long_Integer; 410 origin : Integer); 411 pragma Import (C, Lseek, "__gnat_lseek"); 412 -- Sets the current file pointer to the indicated offset value, relative 413 -- to the current position (origin = SEEK_CUR), end of file (origin = 414 -- SEEK_END), or start of file (origin = SEEK_SET). 415 416 function File_Length (FD : File_Descriptor) return Long_Integer; 417 pragma Import (C, File_Length, "__gnat_file_length"); 418 -- Get length of file from file descriptor FD 419 420 function File_Time_Stamp (Name : String) return OS_Time; 421 -- Given the name of a file or directory, Name, obtains and returns the 422 -- time stamp. This function can be used for an unopened file. Returns 423 -- Invalid_Time is Name doesn't correspond to an existing file. 424 425 function File_Time_Stamp (FD : File_Descriptor) return OS_Time; 426 -- Get time stamp of file from file descriptor FD Returns Invalid_Time is 427 -- FD doesn't correspond to an existing file. 428 429 function Normalize_Pathname 430 (Name : String; 431 Directory : String := ""; 432 Resolve_Links : Boolean := True; 433 Case_Sensitive : Boolean := True) return String; 434 -- Returns a file name as an absolute path name, resolving all relative 435 -- directories, and symbolic links. The parameter Directory is a fully 436 -- resolved path name for a directory, or the empty string (the default). 437 -- Name is the name of a file, which is either relative to the given 438 -- directory name, if Directory is non-null, or to the current working 439 -- directory if Directory is null. The result returned is the normalized 440 -- name of the file. For most cases, if two file names designate the same 441 -- file through different paths, Normalize_Pathname will return the same 442 -- canonical name in both cases. However, there are cases when this is not 443 -- true; for example, this is not true in Unix for two hard links 444 -- designating the same file. 445 -- 446 -- On Windows, the returned path will start with a drive letter except 447 -- when Directory is not empty and does not include a drive letter. If 448 -- Directory is empty (the default) and Name is a relative path or an 449 -- absolute path without drive letter, the letter of the current drive 450 -- will start the returned path. If Case_Sensitive is True (the default), 451 -- then this drive letter will be forced to upper case ("C:\..."). 452 -- 453 -- If Resolve_Links is set to True, then the symbolic links, on systems 454 -- that support them, will be fully converted to the name of the file or 455 -- directory pointed to. This is slightly less efficient, since it 456 -- requires system calls. 457 -- 458 -- If Name cannot be resolved, is invalid (for example if it is too big) or 459 -- is null on entry (for example if there is symbolic link circularity, 460 -- e.g. A is a symbolic link for B, and B is a symbolic link for A), then 461 -- Normalize_Pathname returns an empty string. 462 -- 463 -- In VMS, if Name follows the VMS syntax file specification, it is first 464 -- converted into Unix syntax. If the conversion fails, Normalize_Pathname 465 -- returns an empty string. 466 -- 467 -- For case-sensitive file systems, the value of Case_Sensitive parameter 468 -- is ignored. For file systems that are not case-sensitive, such as 469 -- Windows and OpenVMS, if this parameter is set to False, then the file 470 -- and directory names are folded to lower case. This allows checking 471 -- whether two files are the same by applying this function to their names 472 -- and comparing the results. If Case_Sensitive is set to True, this 473 -- function does not change the casing of file and directory names. 474 475 function Is_Absolute_Path (Name : String) return Boolean; 476 -- Returns True if Name is an absolute path name, i.e. it designates a 477 -- file or directory absolutely rather than relative to another directory. 478 479 function Is_Regular_File (Name : String) return Boolean; 480 -- Determines if the given string, Name, is the name of an existing 481 -- regular file. Returns True if so, False otherwise. Name may be an 482 -- absolute path name or a relative path name, including a simple file 483 -- name. If it is a relative path name, it is relative to the current 484 -- working directory. 485 486 function Is_Directory (Name : String) return Boolean; 487 -- Determines if the given string, Name, is the name of a directory. 488 -- Returns True if so, False otherwise. Name may be an absolute path 489 -- name or a relative path name, including a simple file name. If it is 490 -- a relative path name, it is relative to the current working directory. 491 492 function Is_Readable_File (Name : String) return Boolean; 493 -- Determines if the given string, Name, is the name of an existing file 494 -- that is readable. Returns True if so, False otherwise. Note that this 495 -- function simply interrogates the file attributes (e.g. using the C 496 -- function stat), so it does not indicate a situation in which a file may 497 -- not actually be readable due to some other process having exclusive 498 -- access. 499 500 function Is_Executable_File (Name : String) return Boolean; 501 -- Determines if the given string, Name, is the name of an existing file 502 -- that is executable. Returns True if so, False otherwise. Note that this 503 -- function simply interrogates the file attributes (e.g. using the C 504 -- function stat), so it does not indicate a situation in which a file may 505 -- not actually be readable due to some other process having exclusive 506 -- access. 507 508 function Is_Writable_File (Name : String) return Boolean; 509 -- Determines if the given string, Name, is the name of an existing file 510 -- that is writable. Returns True if so, False otherwise. Note that this 511 -- function simply interrogates the file attributes (e.g. using the C 512 -- function stat), so it does not indicate a situation in which a file may 513 -- not actually be writeable due to some other process having exclusive 514 -- access. 515 516 function Is_Symbolic_Link (Name : String) return Boolean; 517 -- Determines if the given string, Name, is the path of a symbolic link on 518 -- systems that support it. Returns True if so, False if the path is not a 519 -- symbolic link or if the system does not support symbolic links. 520 -- 521 -- A symbolic link is an indirect pointer to a file; its directory entry 522 -- contains the name of the file to which it is linked. Symbolic links may 523 -- span file systems and may refer to directories. 524 525 procedure Set_Writable (Name : String); 526 -- Change permissions on the named file to make it writable for its owner 527 528 procedure Set_Non_Writable (Name : String); 529 -- Change permissions on the named file to make it non-writable for its 530 -- owner. The readable and executable permissions are not modified. 531 532 procedure Set_Read_Only (Name : String) renames Set_Non_Writable; 533 -- This renaming is provided for backwards compatibility with previous 534 -- versions. The use of Set_Non_Writable is preferred (clearer name). 535 536 procedure Set_Executable (Name : String); 537 -- Change permissions on the named file to make it executable for its owner 538 539 procedure Set_Readable (Name : String); 540 -- Change permissions on the named file to make it readable for its 541 -- owner. 542 543 procedure Set_Non_Readable (Name : String); 544 -- Change permissions on the named file to make it non-readable for 545 -- its owner. The writable and executable permissions are not 546 -- modified. 547 548 function Locate_Exec_On_Path 549 (Exec_Name : String) return String_Access; 550 -- Try to locate an executable whose name is given by Exec_Name in the 551 -- directories listed in the environment Path. If the Exec_Name does not 552 -- have the executable suffix, it will be appended before the search. 553 -- Otherwise works like Locate_Regular_File below. If the executable is 554 -- not found, null is returned. 555 -- 556 -- Note that this function allocates memory for the returned value. This 557 -- memory needs to be deallocated after use. 558 559 function Locate_Regular_File 560 (File_Name : String; 561 Path : String) return String_Access; 562 -- Try to locate a regular file whose name is given by File_Name in the 563 -- directories listed in Path. If a file is found, its full pathname is 564 -- returned; otherwise, a null pointer is returned. If the File_Name given 565 -- is an absolute pathname, then Locate_Regular_File just checks that the 566 -- file exists and is a regular file. Otherwise, if the File_Name given 567 -- includes directory information, Locate_Regular_File first checks if the 568 -- file exists relative to the current directory. If it does not, or if 569 -- the File_Name given is a simple file name, the Path argument is parsed 570 -- according to OS conventions, and for each directory in the Path a check 571 -- is made if File_Name is a relative pathname of a regular file from that 572 -- directory. 573 -- 574 -- Note that this function allocates some memory for the returned value. 575 -- This memory needs to be deallocated after use. 576 577 function Get_Debuggable_Suffix return String_Access; 578 -- Return the debuggable suffix convention. Usually this is the same as 579 -- the convention for Get_Executable_Suffix. The result is allocated on 580 -- the heap and should be freed after use to avoid storage leaks. 581 582 function Get_Target_Debuggable_Suffix return String_Access; 583 -- Return the target debuggable suffix convention. Usually this is the same 584 -- as the convention for Get_Executable_Suffix. The result is allocated on 585 -- the heap and should be freed after use to avoid storage leaks. 586 587 function Get_Executable_Suffix return String_Access; 588 -- Return the executable suffix convention. The result is allocated on the 589 -- heap and should be freed after use to avoid storage leaks. 590 591 function Get_Object_Suffix return String_Access; 592 -- Return the object suffix convention. The result is allocated on the heap 593 -- and should be freed after use to avoid storage leaks. 594 595 function Get_Target_Executable_Suffix return String_Access; 596 -- Return the target executable suffix convention. The result is allocated 597 -- on the heap and should be freed after use to avoid storage leaks. 598 599 function Get_Target_Object_Suffix return String_Access; 600 -- Return the target object suffix convention. The result is allocated on 601 -- the heap and should be freed after use to avoid storage leaks. 602 603 -- The following section contains low-level routines using addresses to 604 -- pass file name and executable name. In each routine the name must be 605 -- Nul-Terminated. For complete documentation refer to the equivalent 606 -- routine (using String in place of C_File_Name) defined above. 607 608 subtype C_File_Name is System.Address; 609 -- This subtype is used to document that a parameter is the address of a 610 -- null-terminated string containing the name of a file. 611 612 -- All the following functions need comments ??? 613 614 function Open_Read 615 (Name : C_File_Name; 616 Fmode : Mode) return File_Descriptor; 617 618 function Open_Read_Write 619 (Name : C_File_Name; 620 Fmode : Mode) return File_Descriptor; 621 622 function Create_File 623 (Name : C_File_Name; 624 Fmode : Mode) return File_Descriptor; 625 626 function Create_New_File 627 (Name : C_File_Name; 628 Fmode : Mode) return File_Descriptor; 629 630 procedure Delete_File (Name : C_File_Name; Success : out Boolean); 631 632 procedure Rename_File 633 (Old_Name : C_File_Name; 634 New_Name : C_File_Name; 635 Success : out Boolean); 636 637 procedure Copy_File 638 (Name : C_File_Name; 639 Pathname : C_File_Name; 640 Success : out Boolean; 641 Mode : Copy_Mode := Copy; 642 Preserve : Attribute := Time_Stamps); 643 644 procedure Copy_Time_Stamps 645 (Source, Dest : C_File_Name; 646 Success : out Boolean); 647 648 function File_Time_Stamp (Name : C_File_Name) return OS_Time; 649 -- Returns Invalid_Time is Name doesn't correspond to an existing file 650 651 function Is_Regular_File (Name : C_File_Name) return Boolean; 652 function Is_Directory (Name : C_File_Name) return Boolean; 653 function Is_Readable_File (Name : C_File_Name) return Boolean; 654 function Is_Executable_File (Name : C_File_Name) return Boolean; 655 function Is_Writable_File (Name : C_File_Name) return Boolean; 656 function Is_Symbolic_Link (Name : C_File_Name) return Boolean; 657 658 function Locate_Regular_File 659 (File_Name : C_File_Name; 660 Path : C_File_Name) return String_Access; 661 662 ------------------ 663 -- Subprocesses -- 664 ------------------ 665 666 subtype Argument_List is String_List; 667 -- Type used for argument list in call to Spawn. The lower bound of the 668 -- array should be 1, and the length of the array indicates the number of 669 -- arguments. 670 671 subtype Argument_List_Access is String_List_Access; 672 -- Type used to return Argument_List without dragging in secondary stack. 673 -- Note that there is a Free procedure declared for this subtype which 674 -- frees the array and all referenced strings. 675 676 procedure Normalize_Arguments (Args : in out Argument_List); 677 -- Normalize all arguments in the list. This ensure that the argument list 678 -- is compatible with the running OS and will works fine with Spawn and 679 -- Non_Blocking_Spawn for example. If Normalize_Arguments is called twice 680 -- on the same list it will do nothing the second time. Note that Spawn 681 -- and Non_Blocking_Spawn call Normalize_Arguments automatically, but 682 -- since there is a guarantee that a second call does nothing, this 683 -- internal call will have no effect if Normalize_Arguments is called 684 -- before calling Spawn. The call to Normalize_Arguments assumes that the 685 -- individual referenced arguments in Argument_List are on the heap, and 686 -- may free them and reallocate if they are modified. 687 688 procedure Spawn 689 (Program_Name : String; 690 Args : Argument_List; 691 Success : out Boolean); 692 -- This procedure spawns a program with a given list of arguments. The 693 -- first parameter of is the name of the executable. The second parameter 694 -- contains the arguments to be passed to this program. Success is False 695 -- if the named program could not be spawned or its execution completed 696 -- unsuccessfully. Note that the caller will be blocked until the 697 -- execution of the spawned program is complete. For maximum portability, 698 -- use a full path name for the Program_Name argument. On some systems 699 -- (notably Unix systems) a simple file name may also work (if the 700 -- executable can be located in the path). 701 -- 702 -- Spawning processes from tasking programs is not recommended. See 703 -- "NOTE: Spawn in tasking programs" below. 704 -- 705 -- Note: Arguments in Args that contain spaces and/or quotes such as 706 -- "--GCC=gcc -v" or "--GCC=""gcc -v""" are not portable across all 707 -- operating systems, and would not have the desired effect if they were 708 -- passed directly to the operating system. To avoid this problem, Spawn 709 -- makes an internal call to Normalize_Arguments, which ensures that such 710 -- arguments are modified in a manner that ensures that the desired effect 711 -- is obtained on all operating systems. The caller may call 712 -- Normalize_Arguments explicitly before the call (e.g. to print out the 713 -- exact form of arguments passed to the operating system). In this case 714 -- the guarantee a second call to Normalize_Arguments has no effect 715 -- ensures that the internal call will not affect the result. Note that 716 -- the implicit call to Normalize_Arguments may free and reallocate some 717 -- of the individual arguments. 718 -- 719 -- This function will always set Success to False under VxWorks and other 720 -- similar operating systems which have no notion of the concept of 721 -- dynamically executable file. Otherwise Success is set True if the exit 722 -- status of the spawned process is zero. 723 724 function Spawn 725 (Program_Name : String; 726 Args : Argument_List) return Integer; 727 -- Similar to the above procedure, but returns the actual status returned 728 -- by the operating system, or -1 under VxWorks and any other similar 729 -- operating systems which have no notion of separately spawnable programs. 730 -- 731 -- Spawning processes from tasking programs is not recommended. See 732 -- "NOTE: Spawn in tasking programs" below. 733 734 procedure Spawn 735 (Program_Name : String; 736 Args : Argument_List; 737 Output_File_Descriptor : File_Descriptor; 738 Return_Code : out Integer; 739 Err_To_Out : Boolean := True); 740 -- Similar to the procedure above, but redirects the output to the file 741 -- designated by Output_File_Descriptor. If Err_To_Out is True, then the 742 -- Standard Error output is also redirected. 743 -- Return_Code is set to the status code returned by the operating system 744 -- 745 -- Spawning processes from tasking programs is not recommended. See 746 -- "NOTE: Spawn in tasking programs" below. 747 748 procedure Spawn 749 (Program_Name : String; 750 Args : Argument_List; 751 Output_File : String; 752 Success : out Boolean; 753 Return_Code : out Integer; 754 Err_To_Out : Boolean := True); 755 -- Similar to the procedure above, but saves the output of the command to 756 -- a file with the name Output_File. 757 -- 758 -- Success is set to True if the command is executed and its output 759 -- successfully written to the file. If Success is True, then Return_Code 760 -- will be set to the status code returned by the operating system. 761 -- Otherwise, Return_Code is undefined. 762 -- 763 -- Spawning processes from tasking programs is not recommended. See 764 -- "NOTE: Spawn in tasking programs" below. 765 766 type Process_Id is private; 767 -- A private type used to identify a process activated by the following 768 -- non-blocking calls. The only meaningful operation on this type is a 769 -- comparison for equality. 770 771 Invalid_Pid : constant Process_Id; 772 -- A special value used to indicate errors, as described below 773 774 function Pid_To_Integer (Pid : Process_Id) return Integer; 775 -- Convert a process id to an Integer. Useful for writing hash functions 776 -- for type Process_Id or to compare two Process_Id (e.g. for sorting). 777 778 function Non_Blocking_Spawn 779 (Program_Name : String; 780 Args : Argument_List) return Process_Id; 781 -- This is a non blocking call. The Process_Id of the spawned process is 782 -- returned. Parameters are to be used as in Spawn. If Invalid_Pid is 783 -- returned the program could not be spawned. 784 -- 785 -- Spawning processes from tasking programs is not recommended. See 786 -- "NOTE: Spawn in tasking programs" below. 787 -- 788 -- This function will always return Invalid_Pid under VxWorks, since there 789 -- is no notion of executables under this OS. 790 791 function Non_Blocking_Spawn 792 (Program_Name : String; 793 Args : Argument_List; 794 Output_File_Descriptor : File_Descriptor; 795 Err_To_Out : Boolean := True) return Process_Id; 796 -- Similar to the procedure above, but redirects the output to the file 797 -- designated by Output_File_Descriptor. If Err_To_Out is True, then the 798 -- Standard Error output is also redirected. Invalid_Pid is returned 799 -- if the program could not be spawned successfully. 800 -- 801 -- Spawning processes from tasking programs is not recommended. See 802 -- "NOTE: Spawn in tasking programs" below. 803 -- 804 -- This function will always return Invalid_Pid under VxWorks, since there 805 -- is no notion of executables under this OS. 806 807 function Non_Blocking_Spawn 808 (Program_Name : String; 809 Args : Argument_List; 810 Output_File : String; 811 Err_To_Out : Boolean := True) return Process_Id; 812 -- Similar to the procedure above, but saves the output of the command to 813 -- a file with the name Output_File. 814 -- 815 -- Invalid_Pid is returned if the output file could not be created or if 816 -- the program could not be spawned successfully. 817 -- 818 -- Spawning processes from tasking programs is not recommended. See 819 -- "NOTE: Spawn in tasking programs" below. 820 -- 821 -- This function will always return Invalid_Pid under VxWorks, since there 822 -- is no notion of executables under this OS. 823 824 procedure Wait_Process (Pid : out Process_Id; Success : out Boolean); 825 -- Wait for the completion of any of the processes created by previous 826 -- calls to Non_Blocking_Spawn. The caller will be suspended until one of 827 -- these processes terminates (normally or abnormally). If any of these 828 -- subprocesses terminates prior to the call to Wait_Process (and has not 829 -- been returned by a previous call to Wait_Process), then the call to 830 -- Wait_Process is immediate. Pid identifies the process that has 831 -- terminated (matching the value returned from Non_Blocking_Spawn). 832 -- Success is set to True if this sub-process terminated successfully. If 833 -- Pid = Invalid_Pid, there were no subprocesses left to wait on. 834 -- 835 -- This function will always set success to False under VxWorks, since 836 -- there is no notion of executables under this OS. 837 838 function Argument_String_To_List 839 (Arg_String : String) return Argument_List_Access; 840 -- Take a string that is a program and its arguments and parse it into an 841 -- Argument_List. Note that the result is allocated on the heap, and must 842 -- be freed by the programmer (when it is no longer needed) to avoid 843 -- memory leaks. 844 845 ------------------------------------- 846 -- NOTE: Spawn in Tasking Programs -- 847 ------------------------------------- 848 849 -- Spawning processes in tasking programs using the above Spawn and 850 -- Non_Blocking_Spawn subprograms is not recommended, because there are 851 -- subtle interactions between creating a process and signals/locks that 852 -- can cause trouble. These issues are not specific to Ada; they depend 853 -- primarily on the operating system. 854 855 -- If you need to spawn processes in a tasking program, you will need to 856 -- understand the semantics of your operating system, and you are likely to 857 -- write non-portable code, because operating systems differ in this area. 858 859 -- The Spawn and Non_Blocking_Spawn subprograms call the following 860 -- operating system functions: 861 862 -- On Windows: spawnvp (blocking) or CreateProcess (non-blocking) 863 864 -- On Solaris: fork1, followed in the child process by execv 865 866 -- On other Unix-like systems, and on VMS: fork, followed in the child 867 -- process by execv. 868 869 -- On vxworks, nucleus, and RTX, spawning of processes is not supported 870 871 -- For details, look at the functions __gnat_portable_spawn and 872 -- __gnat_portable_no_block_spawn in adaint.c. 873 874 -- You should read the operating-system-specific documentation for the 875 -- above functions, paying special attention to subtle interactions with 876 -- threading, signals, locks, and file descriptors. Most of the issues are 877 -- related to the fact that on Unix, there is a window of time between fork 878 -- and execv; Windows does not have this problem, because spawning is done 879 -- in a single operation. 880 881 -- On Posix-compliant systems, such as Linux, fork duplicates just the 882 -- calling thread. (On Solaris, fork1 is the Posix-compliant version of 883 -- fork.) 884 885 -- You should avoid using signals while spawning. This includes signals 886 -- used internally by the Ada run-time system, such as timer signals used 887 -- to implement delay statements. 888 889 -- It is best to spawn any subprocesses very early, before the parent 890 -- process creates tasks, locks, or installs signal handlers. Certainly 891 -- avoid doing simultaneous spawns from multiple threads of the same 892 -- process. 893 894 -- There is no problem spawning a subprocess that uses tasking: the 895 -- problems are caused only by tasking in the parent. 896 897 -- If the parent is using tasking, and needs to spawn subprocesses at 898 -- arbitrary times, one technique is for the parent to spawn (very early) 899 -- a particular spawn-manager subprocess whose job is to spawn other 900 -- processes. The spawn-manager must avoid tasking. The parent sends 901 -- messages to the spawn-manager requesting it to spawn processes, using 902 -- whatever inter-process communication mechanism you like, such as 903 -- sockets. 904 905 -- In short, mixing spawning of subprocesses with tasking is a tricky 906 -- business, and should be avoided if possible, but if it is necessary, 907 -- the above guidelines should be followed, and you should beware of 908 -- portability problems. 909 910 ------------------- 911 -- Miscellaneous -- 912 ------------------- 913 914 function Getenv (Name : String) return String_Access; 915 -- Get the value of the environment variable. Returns an access to the 916 -- empty string if the environment variable does not exist or has an 917 -- explicit null value (in some operating systems these are distinct 918 -- cases, in others they are not; this interface abstracts away that 919 -- difference. The argument is allocated on the heap (even in the null 920 -- case), and needs to be freed explicitly when no longer needed to avoid 921 -- memory leaks. 922 923 procedure Setenv (Name : String; Value : String); 924 -- Set the value of the environment variable Name to Value. This call 925 -- modifies the current environment, but does not modify the parent 926 -- process environment. After a call to Setenv, Getenv (Name) will always 927 -- return a String_Access referencing the same String as Value. This is 928 -- true also for the null string case (the actual effect may be to either 929 -- set an explicit null as the value, or to remove the entry, this is 930 -- operating system dependent). Note that any following calls to Spawn 931 -- will pass an environment to the spawned process that includes the 932 -- changes made by Setenv calls. This procedure is not available on VMS. 933 934 procedure OS_Exit (Status : Integer); 935 pragma No_Return (OS_Exit); 936 -- Exit to OS with given status code (program is terminated). Note that 937 -- this is abrupt termination. All tasks are immediately terminated. There 938 -- are no finalization or other Ada-specific cleanup actions performed. On 939 -- systems with atexit handlers (such as Unix and Windows), atexit handlers 940 -- are called. 941 942 type OS_Exit_Subprogram is access procedure (Status : Integer); 943 944 procedure OS_Exit_Default (Status : Integer); 945 pragma No_Return (OS_Exit_Default); 946 -- Default implementation of procedure OS_Exit 947 948 OS_Exit_Ptr : OS_Exit_Subprogram := OS_Exit_Default'Access; 949 -- OS_Exit is implemented through this access value. It it then possible to 950 -- change the implementation of OS_Exit by redirecting OS_Exit_Ptr to an 951 -- other implementation. 952 953 procedure OS_Abort; 954 pragma Import (C, OS_Abort, "abort"); 955 pragma No_Return (OS_Abort); 956 -- Exit to OS signalling an abort (traceback or other appropriate 957 -- diagnostic information should be given if possible, or entry made to 958 -- the debugger if that is possible). 959 960 function Errno return Integer; 961 pragma Import (C, Errno, "__get_errno"); 962 -- Return the task-safe last error number 963 964 procedure Set_Errno (Errno : Integer); 965 pragma Import (C, Set_Errno, "__set_errno"); 966 -- Set the task-safe error number 967 968 function Errno_Message 969 (Err : Integer := Errno; 970 Default : String := "") return String; 971 -- Return a message describing the given Errno value. If none is provided 972 -- by the system, return Default if not empty, else return a generic 973 -- message indicating the numeric errno value. 974 975 Directory_Separator : constant Character; 976 -- The character that is used to separate parts of a pathname 977 978 Path_Separator : constant Character; 979 -- The character to separate paths in an environment variable value 980 981private 982 pragma Import (C, Path_Separator, "__gnat_path_separator"); 983 pragma Import (C, Directory_Separator, "__gnat_dir_separator"); 984 pragma Import (C, Current_Time, "__gnat_current_time"); 985 986 type OS_Time is 987 range -(2 ** (Standard'Address_Size - Integer'(1))) .. 988 +(2 ** (Standard'Address_Size - Integer'(1)) - 1); 989 -- Type used for timestamps in the compiler. This type is used to hold 990 -- time stamps, but may have a different representation than C's time_t. 991 -- This type needs to match the declaration of OS_Time in adaint.h. 992 993 -- Add pragma Inline statements for comparison operations on OS_Time. It 994 -- would actually be nice to use pragma Import (Intrinsic) here, but this 995 -- was not properly supported till GNAT 3.15a, so that would cause 996 -- bootstrap path problems. To be changed later ??? 997 998 Invalid_Time : constant OS_Time := -1; 999 -- This value should match the return value from __gnat_file_time_* 1000 1001 pragma Inline ("<"); 1002 pragma Inline (">"); 1003 pragma Inline ("<="); 1004 pragma Inline (">="); 1005 1006 type Process_Id is new Integer; 1007 Invalid_Pid : constant Process_Id := -1; 1008 1009end System.OS_Lib; 1010