File : g-dirope.ads


------------------------------------------------------------------------------
--                                                                          --
--                         GNAT COMPILER COMPONENTS                         --
--                                                                          --
--            G N A T . D I R E C T O R Y _ O P E R A T I O N S             --
--                                                                          --
--                                 S p e c                                  --
--                                                                          --
--                            $Revision: 1.4 $                              --
--                                                                          --
--            Copyright (C) 1998-1999 Ada Core Technologies, Inc.           --
--                                                                          --
-- GNAT is free software;  you can  redistribute it  and/or modify it under --
-- terms of the  GNU General Public License as published  by the Free Soft- --
-- ware  Foundation;  either version 2,  or (at your option) any later ver- --
-- sion.  GNAT is distributed in the hope that it will be useful, but WITH- --
-- OUT ANY WARRANTY;  without even the  implied warranty of MERCHANTABILITY --
-- or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License --
-- for  more details.  You should have  received  a copy of the GNU General --
-- Public License  distributed with GNAT;  see file COPYING.  If not, write --
-- to  the Free Software Foundation,  59 Temple Place - Suite 330,  Boston, --
-- MA 02111-1307, USA.                                                      --
--                                                                          --
-- As a special exception,  if other files  instantiate  generics from this --
-- unit, or you link  this unit with other files  to produce an executable, --
-- this  unit  does not  by itself cause  the resulting  executable  to  be --
-- covered  by the  GNU  General  Public  License.  This exception does not --
-- however invalidate  any other reasons why  the executable file  might be --
-- covered by the  GNU Public License.                                      --
--                                                                          --
-- GNAT is maintained by Ada Core Technologies Inc (http://www.gnat.com).   --
--                                                                          --
------------------------------------------------------------------------------

--  Directory operations

--  This package provides routines for manipulating directories. A directory
--  can be treated as a file, using open and close routines, and a scanning
--  routine is provided for iterating through the entries in a directory.

package GNAT.Directory_Operations is

   type Dir_Type is limited private;
   --  A value used to reference a directory. Conceptually this value includes
   --  the identity of the directory, and a sequential position within it.

   Directory_Error : exception;
   --  Exception raised if the directory cannot be opened.

   procedure Change_Dir (Dir_Name : String);
   --  Changes the working directory of the current execution environment
   --  to the directory named by Dir_Name.

   procedure Close (Dir : in out Dir_Type);
   --  Closes the directory stream refered to by Dir. On return, Dir is set
   --  to Null_Dir. Close_Dir raises Directory_Error if Dir = Null_Dir.

   function Get_Current_Dir return String;
   --  Returns the current working directory for the running process. The
   --  returned value is the prefix to be prepended to the simple file name
   --  to obtain a full file name (in the case of Unix and DOS based systems,
   --  this means that it will contain a closing file separator).

   procedure Get_Current_Dir (Dir : out String; Last : out Natural);
   --  Returns the current working directory for the running process. The name
   --  is returned in Dir; Last is the index in Dir such that Dir (Last) is the
   --  last character written. If Dir is too small for the dir name, the name
   --  will be truncated before beeing copied to Dir.
   --  The returned value is the prefix to be prepended to the  simple file
   --  name to obtain a full file name (in the case of Unix and DOS based
   --  systems, this means that it will contain a closing file separator).

   function Is_Open (Dir : Dir_Type) return Boolean;
   --  Returns True if Dir is open, or False otherwise.

   procedure Open (Dir : out Dir_Type; Dir_Name : in String);
   --  Opens the directory named by Dir_Name and returns a Dir_Type value
   --  that refers to this directory, and is positioned at the first entry.
   --  Directory_Error is raised if Dir_Name cannot be accessed.

   procedure Read
     (Dir  : in out Dir_Type;
      Str  : out String;
      Last : out Natural);
   --  Reads the next entry from the directory and sets Str to the name
   --  of that entry. Last is the index in Str such that Str (Last) is the
   --  last character written. Last is 0 when there is no more file in the
   --  directory. If Str is too small for the file name, the file name will
   --  be truncated before beeing copied to Str. Directory_Error is raised
   --  if Dir is not open. It is unspecified if entries for the current
   --  and parent directories are returned (e.g. '.' and '..' in Unix).
   --  The directory is returned in target-OS form

   function Read_Is_Thread_Safe return Boolean;
   --  Indicates if procedure Read is thread safe. On systems where the
   --  target system supports this functionality, Read is thread safe,
   --  and this function returns True (e.g. this will be the case on any
   --  Unix or Unix-like system providing a correct implementation of the
   --  function readdir_r). If the system cannot provide a thread safe
   --  implementation of Read, then this function returns False.

private

   type Dir_Type_Value;
   type Dir_Type is access Dir_Type_Value;

end GNAT.Directory_Operations;