gcc/ada/g-os_lib.ads

   1 ------------------------------------------------------------------------------
   2 --                                                                          --
   3 --                         GNAT COMPILER COMPONENTS                         --
   4 --                                                                          --
   5 --                          G N A T . O S _ L I B                           --
   6 --                                                                          --
   7 --                                 S p e c                                  --
   8 --                                                                          --
   9 --                            $Revision: 1.2 $
  10 --                                                                          --
  11 --          Copyright (C) 1995-2001 Free Software Foundation, Inc.          --
  12 --                                                                          --
  13 -- GNAT is free software;  you can  redistribute it  and/or modify it under --
  14 -- terms of the  GNU General Public License as published  by the Free Soft- --
  15 -- ware  Foundation;  either version 2,  or (at your option) any later ver- --
  16 -- sion.  GNAT is distributed in the hope that it will be useful, but WITH- --
  17 -- OUT ANY WARRANTY;  without even the  implied warranty of MERCHANTABILITY --
  18 -- or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License --
  19 -- for  more details.  You should have  received  a copy of the GNU General --
  20 -- Public License  distributed with GNAT;  see file COPYING.  If not, write --
  21 -- to  the Free Software Foundation,  59 Temple Place - Suite 330,  Boston, --
  22 -- MA 02111-1307, USA.                                                      --
  23 --                                                                          --
  24 -- As a special exception,  if other files  instantiate  generics from this --
  25 -- unit, or you link  this unit with other files  to produce an executable, --
  26 -- this  unit  does not  by itself cause  the resulting  executable  to  be --
  27 -- covered  by the  GNU  General  Public  License.  This exception does not --
  28 -- however invalidate  any other reasons why  the executable file  might be --
  29 -- covered by the  GNU Public License.                                      --
  30 --                                                                          --
  31 -- Extensive contributions were provided by Ada Core Technologies Inc.   --
  32 --                                                                          --
  33 ------------------------------------------------------------------------------
  34
  35 --  Operating system interface facilities
  36
  37 --  This package contains types and procedures for interfacing to the
  38 --  underlying OS. It is used by the GNAT compiler and by tools associated
  39 --  with the GNAT compiler, and therefore works for the various operating
  40 --  systems to which GNAT has been ported. This package will undoubtedly
  41 --  grow as new services are needed by various tools.
  42
  43 --  This package tends to use fairly low-level Ada in order to not bring
  44 --  in large portions of the RTL. For example, functions return access
  45 --  to string as part of avoiding functions returning unconstrained types;
  46 --  types related to dates are defined here instead of using the types
  47 --  from Calendar, since use of Calendar forces linking in of tasking code.
  48
  49 --  Except where specifically noted, these routines are portable across
  50 --  all GNAT implementations on all supported operating systems.
  51
  52 with System;
  53 with Unchecked_Deallocation;
  54
  55 package GNAT.OS_Lib is
  56 pragma Elaborate_Body (OS_Lib);
  57
  58    type String_Access is access all String;
  59    --  General purpose string access type
  60
  61    procedure Free is new Unchecked_Deallocation
  62      (Object => String, Name => String_Access);
  63
  64    type String_List is array (Positive range <>) of String_Access;
  65    type String_List_Access is access all String_List;
  66    --  General purpose array and pointer for list of string accesses
  67
  68    ---------------------
  69    -- Time/Date Stuff --
  70    ---------------------
  71
  72    --  The OS's notion of time is represented by the private type OS_Time.
  73    --  This is the type returned by the File_Time_Stamp functions to obtain
  74    --  the time stamp of a specified file. Functions and a procedure (modeled
  75    --  after the similar subprograms in package Calendar) are provided for
  76    --  extracting information from a value of this type. Although these are
  77    --  called GM, the intention is not that they provide GMT times in all
  78    --  cases but rather the actual (time-zone independent) time stamp of the
  79    --  file (of course in Unix systems, this *is* in GMT form).
  80
  81    type OS_Time is private;
  82
  83    subtype Year_Type   is Integer range 1900 .. 2099;
  84    subtype Month_Type  is Integer range    1 ..   12;
  85    subtype Day_Type    is Integer range    1 ..   31;
  86    subtype Hour_Type   is Integer range    0 ..   23;
  87    subtype Minute_Type is Integer range    0 ..   59;
  88    subtype Second_Type is Integer range    0 ..   59;
  89
  90    function GM_Year    (Date : OS_Time) return Year_Type;
  91    function GM_Month   (Date : OS_Time) return Month_Type;
  92    function GM_Day     (Date : OS_Time) return Day_Type;
  93    function GM_Hour    (Date : OS_Time) return Hour_Type;
  94    function GM_Minute  (Date : OS_Time) return Minute_Type;
  95    function GM_Second  (Date : OS_Time) return Second_Type;
  96
  97    procedure GM_Split
  98      (Date    : OS_Time;
  99       Year    : out Year_Type;
 100       Month   : out Month_Type;
 101       Day     : out Day_Type;
 102       Hour    : out Hour_Type;
 103       Minute  : out Minute_Type;
 104       Second  : out Second_Type);
 105
 106    ----------------
 107    -- File Stuff --
 108    ----------------
 109
 110    --  These routines give access to the open/creat/close/read/write level
 111    --  of I/O routines in the typical C library (these functions are not
 112    --  part of the ANSI C standard, but are typically available in all
 113    --  systems). See also package Interfaces.C_Streams for access to the
 114    --  stream level routines.
 115
 116    --  Note on file names. If a file name is passed as type String in any
 117    --  of the following specifications, then the name is a normal Ada string
 118    --  and need not be NUL-terminated. However, a trailing NUL character is
 119    --  permitted, and will be ignored (more accurately, the NUL and any
 120    --  characters that follow it will be ignored).
 121
 122    type File_Descriptor is private;
 123    --  Corresponds to the int file handle values used in the C routines,
 124
 125    Standin  : constant File_Descriptor;
 126    Standout : constant File_Descriptor;
 127    Standerr : constant File_Descriptor;
 128    --  File descriptors for standard input output files
 129
 130    Invalid_FD : constant File_Descriptor;
 131    --  File descriptor returned when error in opening/creating file;
 132
 133    type Mode is (Binary, Text);
 134    for Mode'Size use Integer'Size;
 135    for Mode use (Binary => 0, Text => 1);
 136    --  Used in all the Open and Create calls to specify if the file is to be
 137    --  opened in binary mode or text mode. In systems like Unix, this has no
 138    --  effect, but in systems capable of text mode translation, the use of
 139    --  Text as the mode parameter causes the system to do CR/LF translation
 140    --  and also to recognize the DOS end of file character on input. The use
 141    --  of Text where appropriate allows programs to take a portable Unix view
 142    --  of DOs-format files and process them appropriately.
 143
 144    function Open_Read
 145      (Name  : String;
 146       Fmode : Mode)
 147       return  File_Descriptor;
 148    --  Open file Name for reading, returning file descriptor File descriptor
 149    --  returned is Invalid_FD if file cannot be opened.
 150
 151    function Open_Read_Write
 152      (Name  : String;
 153       Fmode : Mode)
 154       return  File_Descriptor;
 155    --  Open file Name for both reading and writing, returning file
 156    --  descriptor. File descriptor returned is Invalid_FD if file cannot be
 157    --  opened.
 158
 159    function Create_File
 160      (Name  : String;
 161       Fmode : Mode)
 162       return  File_Descriptor;
 163    --  Creates new file with given name for writing, returning file descriptor
 164    --  for subsequent use in Write calls. File descriptor returned is
 165    --  Invalid_FD if file cannot be successfully created
 166
 167    function Create_New_File
 168      (Name  : String;
 169       Fmode : Mode)
 170       return  File_Descriptor;
 171    --  Create new file with given name for writing, returning file descriptor
 172    --  for subsequent use in Write calls. This differs from Create_File in
 173    --  that it fails if the file already exists. File descriptor returned is
 174    --  Invalid_FD if the file exists or cannot be created.
 175
 176    Temp_File_Len : constant Integer := 12;
 177    --  Length of name returned by Create_Temp_File call (GNAT-XXXXXX & NUL)
 178
 179    subtype Temp_File_Name is String (1 .. Temp_File_Len);
 180    --  String subtype set by Create_Temp_File
 181
 182    procedure Create_Temp_File
 183      (FD   : out File_Descriptor;
 184       Name : out Temp_File_Name);
 185    --  Create and open for writing a temporary file. The name of the
 186    --  file and the File Descriptor are returned. The File Descriptor
 187    --  returned is Invalid_FD in the case of failure. No mode parameter
 188    --  is provided. Since this is a temporary file, there is no point in
 189    --  doing text translation on it.
 190
 191    procedure Close (FD : File_Descriptor);
 192    pragma Import (C, Close, "close");
 193    --  Close file referenced by FD
 194
 195    procedure Delete_File (Name : String; Success : out Boolean);
 196    --  Deletes file. Success is set True or False indicating if the delete is
 197    --  successful.
 198
 199    procedure Rename_File
 200      (Old_Name : String;
 201       New_Name : String;
 202       Success  : out Boolean);
 203    --  Rename a file. Successis set True or False indicating if the rename is
 204    --  successful.
 205
 206    function Read
 207      (FD   : File_Descriptor;
 208       A    : System.Address;
 209       N    : Integer)
 210       return Integer;
 211    pragma Import (C, Read, "read");
 212    --  Read N bytes to address A from file referenced by FD. Returned value
 213    --  is count of bytes actually read, which can be less than N at EOF.
 214
 215    function Write
 216      (FD   : File_Descriptor;
 217       A    : System.Address;
 218       N    : Integer)
 219       return Integer;
 220    pragma Import (C, Write, "write");
 221    --  Write N bytes from address A to file referenced by FD. The returned
 222    --  value is the number of bytes written, which can be less than N if
 223    --  a disk full condition was detected.
 224
 225    Seek_Cur : constant := 1;
 226    Seek_End : constant := 2;
 227    Seek_Set : constant := 0;
 228    --  Used to indicate origin for Lseek call
 229
 230    procedure Lseek
 231      (FD     : File_Descriptor;
 232       offset : Long_Integer;
 233       origin : Integer);
 234    pragma Import (C, Lseek, "lseek");
 235    --  Sets the current file pointer to the indicated offset value,
 236    --  relative to the current position (origin = SEEK_CUR), end of
 237    --  file (origin = SEEK_END), or start of file (origin = SEEK_SET).
 238
 239    function File_Length (FD : File_Descriptor) return Long_Integer;
 240    pragma Import (C, File_Length, "__gnat_file_length");
 241    --  Get length of file from file descriptor FD
 242
 243    function File_Time_Stamp (Name : String) return OS_Time;
 244    --  Given the name of a file or directory, Name, obtains and returns the
 245    --  time stamp. This function can be used for an unopend file.
 246
 247    function File_Time_Stamp (FD : File_Descriptor) return OS_Time;
 248    --  Get time stamp of file from file descriptor FD
 249
 250    function Normalize_Pathname
 251      (Name      : String;
 252       Directory : String := "")
 253       return      String;
 254    --  Returns a file name as an absolute path name, resolving all relative
 255    --  directories, and symbolic links. The parameter Directory is a fully
 256    --  resolved path name for a directory, or the empty string (the default).
 257    --  Name is the name of a file, which is either relative to the given
 258    --  directory name, if Directory is non-null, or to the current working
 259    --  directory if Directory is null. The result returned is the normalized
 260    --  name of the file. For most cases, if two file names designate the same
 261    --  file through different paths, Normalize_Pathname will return the same
 262    --  canonical name in both cases. However, there are cases when this is
 263    --  not true; for example, this is not true in Unix for two hard links
 264    --  designating the same file.
 265    --
 266    --  If Name cannot be resolved or is null on entry (for example if there is
 267    --  a circularity in symbolic links: A is a symbolic link for B, while B is
 268    --  a symbolic link for A), then Normalize_Pathname returns an empty string.
 269    --
 270    --  In VMS, if Name follows the VMS syntax file specification, it is first
 271    --  converted into Unix syntax. If the conversion fails, Normalize_Pathname
 272    --  returns an empty string.
 273
 274    function Is_Absolute_Path (Name : String) return Boolean;
 275    --  Returns True if Name is an absolute path name, i.e. it designates
 276    --  a directory absolutely, rather than relative to another directory.
 277
 278    function Is_Regular_File (Name : String) return Boolean;
 279    --  Determines if the given string, Name, is the name of an existing
 280    --  regular file. Returns True if so, False otherwise.
 281
 282    function Is_Directory (Name : String) return Boolean;
 283    --  Determines if the given string, Name, is the name of a directory.
 284    --  Returns True if so, False otherwise.
 285
 286    function Is_Writable_File (Name : String) return Boolean;
 287    --  Determines if the given string, Name, is the name of an existing
 288    --  file that is writable. Returns True if so, False otherwise.
 289
 290    function Locate_Exec_On_Path
 291      (Exec_Name : String)
 292       return      String_Access;
 293    --  Try to locate an executable whose name is given by Exec_Name in the
 294    --  directories listed in the environment Path. If the Exec_Name doesn't
 295    --  have the executable suffix, it will be appended before the search.
 296    --  Otherwise works like Locate_Regular_File below.
 297    --
 298    --  Note that this function allocates some memory for the returned value.
 299    --  This memory needs to be deallocated after use.
 300
 301    function Locate_Regular_File
 302      (File_Name : String;
 303       Path      : String)
 304       return      String_Access;
 305    --  Try to locate a regular file whose name is given by File_Name in the
 306    --  directories listed in  Path. If a file is found, its full pathname is
 307    --  returned; otherwise, a null pointer is returned. If the File_Name given
 308    --  is an absolute pathname, then Locate_Regular_File just checks that the
 309    --  file exists and is a regular file. Otherwise, the Path argument is
 310    --  parsed according to OS conventions, and for each directory in the Path
 311    --  a check is made if File_Name is a relative pathname of a regular file
 312    --  from that directory.
 313    --
 314    --  Note that this function allocates some memory for the returned value.
 315    --  This memory needs to be deallocated after use.
 316
 317    function Get_Debuggable_Suffix return String_Access;
 318    --  Return the debuggable suffix convention. Usually this is the same as
 319    --  the convention for Get_Executable_Suffix.
 320    --
 321    --  Note that this function allocates some memory for the returned value.
 322    --  This memory needs to be deallocated after use.
 323
 324    function Get_Executable_Suffix return String_Access;
 325    --  Return the executable suffix convention.
 326    --
 327    --  Note that this function allocates some memory for the returned value.
 328    --  This memory needs to be deallocated after use.
 329
 330    function Get_Object_Suffix return String_Access;
 331    --  Return the object suffix convention.
 332    --
 333    --  Note that this function allocates some memory for the returned value.
 334    --  This memory needs to be deallocated after use.
 335
 336    --  The following section contains low-level routines using addresses to
 337    --  pass file name and executable name. In each routine the name must be
 338    --  Nul-Terminated. For complete documentation refer to the equivalent
 339    --  routine (but using string) defined above.
 340
 341    subtype C_File_Name is System.Address;
 342    --  This subtype is used to document that a parameter is the address
 343    --  of a null-terminated string containing the name of a file.
 344
 345    function Open_Read
 346      (Name  : C_File_Name;
 347       Fmode : Mode)
 348       return  File_Descriptor;
 349
 350    function Open_Read_Write
 351      (Name  : C_File_Name;
 352       Fmode : Mode)
 353       return  File_Descriptor;
 354
 355    function Create_File
 356      (Name  : C_File_Name;
 357       Fmode : Mode)
 358       return  File_Descriptor;
 359
 360    function Create_New_File
 361      (Name  : C_File_Name;
 362       Fmode : Mode)
 363       return  File_Descriptor;
 364
 365    procedure Delete_File (Name : C_File_Name; Success : out Boolean);
 366
 367    procedure Rename_File
 368      (Old_Name : C_File_Name;
 369       New_Name : C_File_Name;
 370       Success  : out Boolean);
 371
 372    function File_Time_Stamp (Name : C_File_Name) return OS_Time;
 373
 374    function Is_Regular_File (Name : C_File_Name) return Boolean;
 375
 376    function Is_Directory (Name : C_File_Name) return Boolean;
 377
 378    function Is_Writable_File (Name : C_File_Name) return Boolean;
 379
 380    function Locate_Regular_File
 381      (File_Name : C_File_Name;
 382       Path      : C_File_Name)
 383       return      String_Access;
 384
 385    ------------------
 386    -- Subprocesses --
 387    ------------------
 388
 389    subtype Argument_List is String_List;
 390    --  Type used for argument list in call to Spawn. The lower bound
 391    --  of the array should be 1, and the length of the array indicates
 392    --  the number of arguments.
 393
 394    subtype Argument_List_Access is String_List_Access;
 395    --  Type used to return an Argument_List without dragging in secondary
 396    --  stack.
 397
 398    procedure Spawn
 399      (Program_Name : String;
 400       Args         : Argument_List;
 401       Success      : out Boolean);
 402    --  The first parameter of function Spawn is the name of the executable.
 403    --  The second parameter contains the arguments to be passed to the
 404    --  program. Success is False if the named program could not be spawned
 405    --  or its execution completed unsuccessfully. Note that the caller will
 406    --  be blocked until the execution of the spawned program is complete.
 407    --  For maximum portability, use a full path name for the Program_Name
 408    --  argument. On some systems (notably Unix systems) a simple file
 409    --  name may also work (if the executable can be located in the path).
 410    --
 411    --  Note: Arguments that contain spaces and/or quotes such as
 412    --        "--GCC=gcc -v" or "--GCC=""gcc-v""" are not portable
 413    --        across OSes. They may or may not have the desired effect.
 414
 415    function Spawn
 416      (Program_Name : String;
 417       Args         : Argument_List)
 418       return         Integer;
 419    --  Like above, but as function returning the exact exit status
 420
 421    type Process_Id is private;
 422    --  A private type used to identify a process activated by the following
 423    --  non-blocking call. The only meaningful operation on this type is a
 424    --  comparison for equality.
 425
 426    Invalid_Pid : constant Process_Id;
 427    --  A special value used to indicate errors, as described below.
 428
 429    function Non_Blocking_Spawn
 430      (Program_Name : String;
 431       Args         : Argument_List)
 432       return         Process_Id;
 433    --  This is a non blocking call. The Process_Id of the spawned process
 434    --  is returned. Parameters are to be used as in Spawn. If Invalid_Id
 435    --  is returned the program could not be spawned.
 436
 437    procedure Wait_Process (Pid : out Process_Id; Success : out Boolean);
 438    --  Wait for the completion of any of the processes created by previous
 439    --  calls to Non_Blocking_Spawn. The caller will be suspended until one
 440    --  of these processes terminates (normally or abnormally). If any of
 441    --  these subprocesses terminates prior to the call to Wait_Process (and
 442    --  has not been returned by a previous call to Wait_Process), then the
 443    --  call to Wait_Process is immediate. Pid identifies the process that
 444    --  has terminated (matching the value returned from Non_Blocking_Spawn).
 445    --  Success is set to True if this sub-process terminated successfully.
 446    --  If Pid = Invalid_Id, there were no subprocesses left to wait on.
 447
 448    function Argument_String_To_List
 449      (Arg_String : String)
 450       return       Argument_List_Access;
 451    --  Take a string that is a program and it's arguments and parse it into
 452    --  an Argument_List.
 453
 454    -------------------
 455    -- Miscellaneous --
 456    -------------------
 457
 458    function Getenv (Name : String) return String_Access;
 459    --  Get the value of the environment variable. Returns an access
 460    --  to the empty string if the environment variable does not exist
 461    --  or has an explicit null value (in some operating systems these
 462    --  are distinct cases, in others they are not; this interface
 463    --  abstracts away that difference.
 464
 465    procedure Setenv (Name : String; Value : String);
 466    --  Set the value of the environment variable Name to Value. This call
 467    --  modifies the current environment, but does not modify the parent
 468    --  process environment. After a call to Setenv, Getenv (Name) will
 469    --  always return a String_Access referencing the same String as Value.
 470    --  This is true also for the null string case (the actual effect may
 471    --  be to either set an explicit null as the value, or to remove the
 472    --  entry, this is operating system dependent). Note that any following
 473    --  calls to Spawn will pass an environment to the spawned process that
 474    --  includes the changes made by Setenv calls. This procedure is not
 475    --  available under VMS.
 476
 477    procedure OS_Exit (Status : Integer);
 478    pragma Import (C, OS_Exit, "__gnat_os_exit");
 479    --  Exit to OS with given status code (program is terminated)
 480
 481    procedure OS_Abort;
 482    pragma Import (C, OS_Abort, "abort");
 483    --  Exit to OS signalling an abort (traceback or other appropriate
 484    --  diagnostic information should be given if possible, or entry made
 485    --  to the debugger if that is possible).
 486
 487    function Errno return Integer;
 488    pragma Import (C, Errno, "__get_errno");
 489    --  Return the task-safe last error number.
 490
 491    procedure Set_Errno (Errno : Integer);
 492    pragma Import (C, Set_Errno, "__set_errno");
 493    --  Set the task-safe error number.
 494
 495    Directory_Separator : constant Character;
 496    --  The character that is used to separate parts of a pathname.
 497
 498    Path_Separator : constant Character;
 499    --  The character to separate paths in an environment variable value.
 500
 501 private
 502    pragma Import (C, Path_Separator, "__gnat_path_separator");
 503    pragma Import (C, Directory_Separator, "__gnat_dir_separator");
 504
 505    type OS_Time is new Integer;
 506
 507    type File_Descriptor is new Integer;
 508
 509    Standin    : constant File_Descriptor :=  0;
 510    Standout   : constant File_Descriptor :=  1;
 511    Standerr   : constant File_Descriptor :=  2;
 512    Invalid_FD : constant File_Descriptor := -1;
 513
 514    type Process_Id is new Integer;
 515    Invalid_Pid : constant Process_Id := -1;
 516
 517 end GNAT.OS_Lib;