home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 10 Tools / 10-Tools.zip / adav313.zip / gnat-3_13p-os2-bin-20010916.zip / emx / gnatlib / s-fileio.ads < prev    next >
Text File  |  2000-07-19  |  12KB  |  259 lines
  1. ------------------------------------------------------------------------------
  2. --                                                                          --
  3. --                         GNAT RUN-TIME COMPONENTS                         --
  4. --                                                                          --
  5. --                       S Y S T E M . F I L E _ I O                        --
  6. --                                                                          --
  7. --                                 S p e c                                  --
  8. --                                                                          --
  9. --                            $Revision: 1.16 $                             --
  10. --                                                                          --
  11. --          Copyright (C) 1992-1998, 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. -- GNAT was originally developed  by the GNAT team at  New York University. --
  32. -- It is now maintained by Ada Core Technologies Inc (http://www.gnat.com). --
  33. --                                                                          --
  34. ------------------------------------------------------------------------------
  35.  
  36. --  This package provides support for the routines described in (RM A.8.2)
  37. --  which are common to Text_IO, Direct_IO, Sequential_IO and Stream_IO.
  38.  
  39. with Interfaces.C_Streams;
  40.  
  41. with System.File_Control_Block;
  42.  
  43. package System.File_IO is
  44.  
  45.    package FCB renames System.File_Control_Block;
  46.    package ICS renames Interfaces.C_Streams;
  47.  
  48.    ---------------------
  49.    -- File Management --
  50.    ---------------------
  51.  
  52.    procedure Open
  53.      (File_Ptr  : in out FCB.AFCB_Ptr;
  54.       Dummy_FCB : in out FCB.AFCB'Class;
  55.       Mode      : FCB.File_Mode;
  56.       Name      : String;
  57.       Form      : String;
  58.       Amethod   : Character;
  59.       Creat     : Boolean;
  60.       Text      : Boolean;
  61.       C_Stream  : ICS.FILEs := ICS.NULL_Stream);
  62.    --  This routine is used for both Open and Create calls:
  63.    --
  64.    --    File_Ptr is the file type, which must be null on entry
  65.    --    (i.e. the file must be closed before the call).
  66.    --
  67.    --    Dummy_FCB is a default initialized file control block of appropriate
  68.    --    type. Note that the tag of this record indicates the type and length
  69.    --    of the control block. This control block is used only for the purpose
  70.    --    of providing the controlling argument for calling the write version
  71.    --    of Allocate_AFCB. It has no other purpose, and its fields are never
  72.    --    read or written.
  73.    --
  74.    --    Mode is the required mode
  75.    --
  76.    --    Name is the file name, with a null string indicating that a temporary
  77.    --    file is to be created (only permitted in create mode, not open mode)
  78.    --
  79.    --    Creat is True for a create call, and false for an open call
  80.    --
  81.    --    Text is set True to open the file in text mode (w+t or r+t) instead
  82.    --    of the usual binary mode open (w+b or r+b).
  83.    --
  84.    --    Form is the form string given in the open or create call, this is
  85.    --    stored in the AFCB, but otherwise is not used by this or any other
  86.    --    routine in this unit (except Form which retrieves the original value)
  87.    --
  88.    --    Amethod indicates the access method
  89.    --
  90.    --      D = Direct_IO
  91.    --      Q = Sequential_IO
  92.    --      S = Stream_IO
  93.    --      T = Text_IO
  94.    --      W = Wide_Text_IO
  95.    --
  96.    --    C_Stream is left at its default value for the normal case of an
  97.    --    Open or Create call as defined in the RM. The only time this is
  98.    --    non-null is for the Open call from Ada.xxx_IO.C_Streams.Open.
  99.    --
  100.    --  On return, if the open/create succeeds, then the fields of File are
  101.    --  filled in, and this value is copied to the heap. File_Ptr points to
  102.    --  this allocated file control block. If the open/create fails, then the
  103.    --  fields of File are undefined, and File_Ptr is unchanged.
  104.  
  105.    procedure Close (File : in out FCB.AFCB_Ptr);
  106.    --  The file is closed, all storage associated with it is released, and
  107.    --  File is set to null. Note that this routine calls AFCB_Close to perform
  108.    --  any specialized close actions, then closes the file at the system level,
  109.    --  then frees the mode and form strings, and finally calls AFCB_Free to
  110.    --  free the file control block itself, setting File to null.
  111.  
  112.    procedure Delete (File : in out FCB.AFCB_Ptr);
  113.    --  The indicated file is unlinked
  114.  
  115.    procedure Reset (File : in out FCB.AFCB_Ptr; Mode : in FCB.File_Mode);
  116.    --  The file is reset, and the mode changed as indicated.
  117.  
  118.    procedure Reset (File : in out FCB.AFCB_Ptr);
  119.    --  The files is reset, and the mode is unchanged
  120.  
  121.    function Mode (File : in FCB.AFCB_Ptr) return FCB.File_Mode;
  122.    --  Returns the mode as supplied by create, open or reset
  123.  
  124.    function Name (File : in FCB.AFCB_Ptr) return String;
  125.    --  Returns the file name as supplied by Open or Create. Raises Use_Error
  126.    --  if used with temporary files or standard files.
  127.  
  128.    function Form (File : in FCB.AFCB_Ptr) return String;
  129.    --  Returns the form as supplied by create, open or reset
  130.    --  The string is normalized to all lower case letters.
  131.  
  132.    function Is_Open (File : in FCB.AFCB_Ptr) return Boolean;
  133.    --  Determines if file is open or not
  134.  
  135.    ----------------------
  136.    -- Utility Routines --
  137.    ----------------------
  138.  
  139.    --  Some internal routines not defined in A.8.2. These are routines which
  140.    --  provide required common functionality shared by separate packages.
  141.  
  142.    procedure Chain_File (File : FCB.AFCB_Ptr);
  143.    --  Used to chain the given file into the list of open files. Normally this
  144.    --  is done implicitly by Open. Chain_File is used for the spcial cases of
  145.    --  the system files defined by Text_IO (stdin, stdout, stderr) which are
  146.    --  not opened in the normal manner. Note that the caller is responsible
  147.    --  for task lock out to protect the global data structures if this is
  148.    --  necessary (it is needed for the calls from within this unit itself,
  149.    --  but not required for the calls from Text_IO and Wide_Text_IO that
  150.    --  are made during elaboration of the environment task).
  151.  
  152.    procedure Check_File_Open (File : FCB.AFCB_Ptr);
  153.    --  If the current file is not open, then Status_Error is raised.
  154.    --  Otherwise control returns normally (with File pointing to the
  155.    --  control block for the open file.
  156.  
  157.    procedure Check_Read_Status (File : FCB.AFCB_Ptr);
  158.    --  If the current file is not open, then Status_Error is raised. If
  159.    --  the file is open, then the mode is checked to ensure that reading
  160.    --  is permitted, and if not Mode_Error is raised, otherwise control
  161.    --  returns normally.
  162.  
  163.    procedure Check_Write_Status (File : FCB.AFCB_Ptr);
  164.    --  If the current file is not open, then Status_Error is raised. If
  165.    --  the file is open, then the mode is checked to ensure that writing
  166.    --  is permitted, and if not Mode_Error is raised, otherwise control
  167.    --  returns normally.
  168.  
  169.    function End_Of_File (File : FCB.AFCB_Ptr) return Boolean;
  170.    --  File must be opened in read mode. True is returned if the stream is
  171.    --  currently positioned at the end of file, otherwise False is returned.
  172.    --  The position of the stream is not affected.
  173.  
  174.    procedure Flush (File : FCB.AFCB_Ptr);
  175.    --  Flushes the stream associated with the given file. The file must be
  176.    --  open and in write mode (if not, an appropriate exception is raised)
  177.  
  178.    function Form_Boolean
  179.      (Form    : String;
  180.       Keyword : String;
  181.       Default : Boolean)
  182.       return    Boolean;
  183.    --  Searches form string for an entry of the form Keyword=xx where xx is
  184.    --  either Yes/No or y/n. Returns True if Yes or Y is found, False if No
  185.    --  or N is found. If the keyword parameter is not found, returns the
  186.    --  value given as Default. May raise Use_Error if a form string syntax
  187.    --  error is detected. Keyword and Form must be in lower case.
  188.  
  189.    function Form_Integer
  190.      (Form    : String;
  191.       Keyword : String;
  192.       Default : Integer)
  193.       return    Integer;
  194.    --  Searches form string for an entry of the form Keyword=xx where xx is
  195.    --  an unsigned decimal integer in the range 0 to 999_999. Returns this
  196.    --  integer value if it is found. If the keyword parameter is not found,
  197.    --  returns the value given as Default. Raise Use_Error if a form string
  198.    --  syntax error is detected. Keyword and Form must be in lower case.
  199.  
  200.    procedure Form_Parameter
  201.      (Form    : String;
  202.       Keyword : String;
  203.       Start   : out Natural;
  204.       Stop    : out Natural);
  205.    --  Searches form string for an entry of the form Keyword=xx and if found
  206.    --  Sets Start and Stop to the first and last characters of xx. Keyword
  207.    --  and Form must be in lower case. If no entry matches, then Start is
  208.    --  set to zero. Use_Error can be raised if a malformed string is found,
  209.    --  but there is no guarantee of full syntax checking.
  210.  
  211.    procedure Read_Buf
  212.      (File : FCB.AFCB_Ptr;
  213.       Buf  : Address;
  214.       Siz  : Interfaces.C_Streams.size_t);
  215.    --  Reads Siz bytes from File.Stream into Buf. The caller has checked
  216.    --  that the file is open in read mode. Raises an exception if Siz bytes
  217.    --  cannot be read (End_Error if no data was read, Data_Error if a partial
  218.    --  buffer was read, Device_Error if an error occurs).
  219.  
  220.    procedure Read_Buf
  221.      (File  : FCB.AFCB_Ptr;
  222.       Buf   : Address;
  223.       Siz   : in Interfaces.C_Streams.size_t;
  224.       Count : out Interfaces.C_Streams.size_t);
  225.    --  Reads Siz bytes from File.Stream into Buf. The caller has checked
  226.    --  that the file is open in read mode. Device Error is raised if an error
  227.    --  occurs. Count is the actual number of bytes read, which may be less
  228.    --  than Siz if the end of file is encountered.
  229.  
  230.    procedure Append_Set (File : FCB.AFCB_Ptr);
  231.    --  If the mode of the file is Append_File, then the file is positioned
  232.    --  at the end of file using fseek, otherwise this call has no effect.
  233.  
  234.    procedure Write_Buf
  235.      (File : FCB.AFCB_Ptr;
  236.       Buf  : Address;
  237.       Siz  : Interfaces.C_Streams.size_t);
  238.    --  Writes size_t bytes to File.Stream from Buf. The caller has checked
  239.    --  that the file is open in write mode. Raises Device_Error if the
  240.    --  complete buffer cannot be written.
  241.  
  242.    procedure Make_Unbuffered (File : FCB.AFCB_Ptr);
  243.  
  244.    procedure Make_Line_Buffered
  245.      (File     : FCB.AFCB_Ptr;
  246.       Line_Siz : Interfaces.C_Streams.size_t);
  247.  
  248.    procedure Make_Buffered
  249.      (File     : FCB.AFCB_Ptr;
  250.       Buf_Siz  : Interfaces.C_Streams.size_t);
  251.  
  252. private
  253.    pragma Inline (Check_Read_Status);
  254.    pragma Inline (Check_Write_Status);
  255.    pragma Inline (Form);
  256.    pragma Inline (Mode);
  257.  
  258. end System.File_IO;
  259.