home *** CD-ROM | disk | FTP | other *** search
/ Geek Gadgets 1 / ADE-1.bin / ade-dist / gnat-2.06-src.tgz / tar.out / fsf / gnat / ada / g-os_lib.ads < prev    next >
Text File  |  1996-09-28  |  12KB  |  273 lines
  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.26 $                             --
  10. --                                                                          --
  11. --        Copyright (c) 1992,1993,1994,1995 NYU, All Rights Reserved        --
  12. --                                                                          --
  13. -- The GNAT library is free software; you can redistribute it and/or modify --
  14. -- it under terms of the GNU Library General Public License as published by --
  15. -- the Free Software  Foundation; either version 2, or (at your option) any --
  16. -- later version.  The GNAT library is distributed in the hope that it will --
  17. -- be useful, but WITHOUT ANY WARRANTY;  without even  the implied warranty --
  18. -- of MERCHANTABILITY  or  FITNESS FOR  A PARTICULAR PURPOSE.  See the  GNU --
  19. -- Library  General  Public  License for  more  details.  You  should  have --
  20. -- received  a copy of the GNU  Library  General Public License  along with --
  21. -- the GNAT library;  see the file  COPYING.LIB.  If not, write to the Free --
  22. -- Free Software Foundation, 675 Mass Ave, Cambridge, MA 02139, USA.        --
  23. --                                                                          --
  24. ------------------------------------------------------------------------------
  25.  
  26. --  This package types and procedures for interfacing to the underlying OS.
  27. --  It is used by the GNAT compiler and by tools associated with the GNAT
  28. --  compiler, and therefore works for the various OS-s to which GNAT has
  29. --  been ported.  This package will undoubtedly grow as new services are
  30. --  needed by various tools.
  31.  
  32. --  This package tends to use fairly low-level Ada in order to not bring
  33. --  in large portions of the RTL.  For example, functions return access
  34. --  to string as part of avoiding functions returning unconstrained types;
  35. --  types related to dates are defined here instead of using the types
  36. --  from Calendar, since use of Calendar forces linking in of tasking code.
  37.  
  38. with System;
  39.  
  40. package GNAT.OS_Lib is
  41.  
  42.    type String_Access is access String;
  43.  
  44.    ---------------------
  45.    -- Time/Date Stuff --
  46.    ---------------------
  47.  
  48.    --  The OS's notion of time is represented by the private type OS_Time.
  49.    --  This is the type returned by the File_Time_Stamp functions to obtain
  50.    --  the file stam of a specified file. Functions and a procedure (modeled
  51.    --  after the similar subprograms in package Calendar) are provided for
  52.    --  extracting information from a value of this type. Although these are
  53.    --  called GM, the intention is not that they provide GMT times in all
  54.    --  cases but rather the actual (time-zone independent) time stamp of the
  55.    --  file (of course in Unix systems, this *is* in GMT form).
  56.  
  57.    type OS_Time is private;
  58.  
  59.    subtype Year_Type   is Integer range 1900 .. 2099;
  60.    subtype Month_Type  is Integer range    1 ..   12;
  61.    subtype Day_Type    is Integer range    1 ..   31;
  62.    subtype Hour_Type   is Integer range    0 ..   23;
  63.    subtype Minute_Type is Integer range    0 ..   59;
  64.    subtype Second_Type is Integer range    0 ..   59;
  65.  
  66.    function GM_Year    (Date : OS_Time) return Year_Type;
  67.    function GM_Month   (Date : OS_Time) return Month_Type;
  68.    function GM_Day     (Date : OS_Time) return Day_Type;
  69.    function GM_Hour    (Date : OS_Time) return Hour_Type;
  70.    function GM_Minute  (Date : OS_Time) return Minute_Type;
  71.    function GM_Second  (Date : OS_Time) return Second_Type;
  72.  
  73.    procedure GM_Split
  74.      (Date    : OS_Time;
  75.       Year    : out Year_Type;
  76.       Month   : out Month_Type;
  77.       Day     : out Day_Type;
  78.       Hour    : out Hour_Type;
  79.       Minute  : out Minute_Type;
  80.       Second  : out Second_Type);
  81.  
  82.    ----------------
  83.    -- File Stuff --
  84.    ----------------
  85.  
  86.    --  These routines give access to the open/creat/close/read/write level
  87.    --  of I/O routines in the typical C library (these functions are not
  88.    --  part of the ANSI C standard, but are typically available in all
  89.    --  systems). See also package Interfaces.C_Streams for access to the
  90.    --  stream level routines.
  91.  
  92.    type File_Descriptor is private;
  93.    --  Corresponds to the int file handle values used in the C routines,
  94.  
  95.    Standin  : constant File_Descriptor;
  96.    Standout : constant File_Descriptor;
  97.    Standerr : constant File_Descriptor;
  98.    --  File descriptors for standard input output files
  99.  
  100.    Invalid_FD : constant File_Descriptor;
  101.    --  File descriptor returned when error in opening/creating file;
  102.  
  103.    type Mode is (Binary, Text);
  104.    for Mode'Size use Integer'Size;
  105.    for Mode use (Binary => 0, Text => 1);
  106.    --  Used in all the Open and Create calls to specify if the file is to be
  107.    --  opened in binary mode or text mode. In systems like Unix, this has no
  108.    --  effect, but in systems capable of text mode translation, the use of
  109.    --  Text as the mode parameter causes the system to do CR/LF translation
  110.    --  and also to recognize the DOS end of file character on input. The use
  111.    --  of Text where appropriate allows programs to take a portable Unix view
  112.    --  of DOs-format files and process them appropriately.
  113.  
  114.    function Open_Read
  115.      (Name  : System.Address;
  116.       Fmode : Mode)
  117.       return  File_Descriptor;
  118.    pragma Import (C, Open_Read, "open_read");
  119.    --  Open file Name (NUL-terminated) for reading, returning file descriptor
  120.    --  File descriptor returned is Invalid_FD if file cannot be opened.
  121.  
  122.    function Create_File
  123.      (Name  : System.Address;
  124.       Fmode : Mode)
  125.       return  File_Descriptor;
  126.    pragma Import (C, Create_File, "open_create");
  127.    --  Creates new file with given name (NUL-terminated) for writing, returning
  128.    --  file descriptor for subsequent use in Write calls. File descriptor
  129.    --  returned is Invalid_FD if file cannot be successfully created.
  130.  
  131.    function Create_New_File
  132.      (Name  : System.Address;
  133.       Fmode : Mode)
  134.       return  File_Descriptor;
  135.    pragma Import (C, Create_New_File, "open_new");
  136.    --  Create new file with given name (NUL-terminated) for writing,
  137.    --  returning file descriptor for subsequent use in Write calls.  This
  138.    --  differs from Create_File in that it fails if the file already exists.
  139.    --  File descriptor returned is Invalid_FD if the file exists or cannot
  140.    --  be created.
  141.  
  142.    Temp_File_Len : constant Integer := 12;
  143.    --  Length of name returned by Create_Temp_File call (GNAT-XXXXXX & NUL)
  144.  
  145.    subtype Temp_File_Name is String (1 .. Temp_File_Len);
  146.    --  String subtype set by Create_Temp_File
  147.  
  148.    procedure Create_Temp_File
  149.      (FD   : out File_Descriptor;
  150.       Name : out Temp_File_Name);
  151.    --  Create and open for writing a temporary file.  The name of the
  152.    --  file and the File Descriptor are returned.  The File Descriptor
  153.    --  returned is Invalid_FD in the case of failure. No mode parameter
  154.    --  is provided. Since this is a temporary file, there is no point in
  155.    --  doing text translation on it.
  156.  
  157.    procedure Close (FD : File_Descriptor);
  158.    pragma Import (C, Close, "close");
  159.    --  Close file referenced by FD
  160.  
  161.    procedure Delete_File (Name : System.Address; Success : out Boolean);
  162.    --  Deletes a file. Name is the address of the NUL-terminated file name
  163.    --  Success is set True or False indicating if the delete is successful.
  164.  
  165.    function Read
  166.      (FD : File_Descriptor;
  167.       A  : System.Address;
  168.       N  : Integer)
  169.    return Integer;
  170.    pragma Import (C, Read, "read");
  171.    --  Read N bytes to address A from file referenced by FD. Returned value
  172.    --  is count of bytes actually read, which can be less than N at EOF.
  173.  
  174.    function Write
  175.      (FD   : File_Descriptor;
  176.       A    : System.Address;
  177.       N    : Integer)
  178.       return Integer;
  179.    pragma Import (C, Write, "write");
  180.    --  Write N bytes from address A to file referenced by FD. The returned
  181.    --  value is the number of bytes written, which can be less than N if
  182.    --  a disk full condition was detected.
  183.  
  184.    function File_Length (FD : File_Descriptor) return Long_Integer;
  185.    pragma Import (C, File_Length, "file_length");
  186.    --  Get length of file from descriptor
  187.  
  188.    function File_Time_Stamp (Name : String) return OS_Time;
  189.    --  Get time stamp of file from name (use for unopened file)
  190.  
  191.    function File_Time_Stamp (FD : File_Descriptor) return OS_Time;
  192.    --  Get time stamp of file from descriptor
  193.  
  194.    function Is_Regular_File (Name : String) return Boolean;
  195.    --  The named file exists and is a regular file
  196.  
  197.    function Is_Directory (Name : String) return Boolean;
  198.    --  The named file exists and is a directory
  199.  
  200.    function Locate_Regular_File
  201.      (File_Name : String;
  202.       Path      : String)
  203.       return      String_Access;
  204.    --  Try to locate a regular file whose name is given by File_Name in the
  205.    --  directories listed in Path.  If a file is found, its full pathname is
  206.    --  returned; otherwise, a null pointer is returned. If the File_Name given
  207.    --  is an absolute pathname, then Locate_Regular_File just checks that the
  208.    --  file exists and is a regular file.  Otherwise, the Path argument is
  209.    --  parsed according to OS conventions, and for each directory in the Path
  210.    --  a check is made if File_Name is a relative pathname of a regular file
  211.    --  from that directory.
  212.    --
  213.    --  This is most often used for finding executables.
  214.  
  215.    ------------------
  216.    -- Subprocesses --
  217.    ------------------
  218.  
  219.    type Argument_List is array (Integer range <>) of String_Access;
  220.  
  221.    procedure Spawn
  222.      (Program_Name : String;
  223.       Args         : Argument_List;
  224.       Success      : out Boolean);
  225.    --  The first parameter of function Spawn is the FULL PATHNAME of
  226.    --  the executable.  The second parameter contains the arguments
  227.    --  to be passed to the program (in typical argc/argv form).
  228.  
  229.    -------------------
  230.    -- Miscellaneous --
  231.    -------------------
  232.  
  233.    function Getenv (Name : String) return String_Access;
  234.    --  Get the value of the environment variable. Returns the empty
  235.    --  string if the environment variable does not exist.
  236.    --  doesn't exist
  237.  
  238.    procedure OS_Exit  (Status : Integer);
  239.    pragma Import (C, OS_Exit, "exit");
  240.    --  Exit to OS with given status code (program is terminated)
  241.  
  242.    procedure OS_Abort;
  243.    pragma Import (C, OS_Abort, "abort");
  244.    --  Exit to OS signalling an abort (traceback or other appropriate
  245.    --  diagnostic information should be given if possible, or entry made
  246.    --  to the debugger if that is possible).
  247.  
  248.    Directory_Separator : constant Character;
  249.    --  The character that is used to separate parts of a pathname.
  250.  
  251.    Path_Separator      : constant Character;
  252.    --  The character to separate paths in an environment variable value.
  253.  
  254. private
  255.    Dirsep_Char : Character;
  256.    pragma Import (C, Dirsep_Char, "dirsep_char");
  257.    Directory_Separator : constant Character := Dirsep_Char;
  258.  
  259.    Pathsep_Char : Character;
  260.    pragma Import (C, Pathsep_Char, "pathsep_char");
  261.    Path_Separator      : constant Character := Pathsep_Char;
  262.  
  263.    type OS_Time is new Long_Integer;
  264.  
  265.    type File_Descriptor is new Integer;
  266.  
  267.    Standin    : constant File_Descriptor :=  0;
  268.    Standout   : constant File_Descriptor :=  1;
  269.    Standerr   : constant File_Descriptor :=  2;
  270.    Invalid_FD : constant File_Descriptor := -1;
  271.  
  272. end GNAT.OS_Lib;
  273.