⟦16c49238f⟧

E3 Source Code



-- This is the interface file between machine-independent text_io, direct_io
-- and sequential_io implementation and the actual physical i/o device(s).
-- All Ada I/O can be reimplemented to work with a new device by reimplementing
-- the body of this single package.
--
-- Direct_io files are implemented (currently) with fixed-size elements.
--
-- The phrase "normally will be called only" will appear below - it means that
-- for VADS software, the statement is true.  However, these files are public
-- and may be used to write a low-level portable file handling system.  Some
-- users may have done this, and may therefore use these functions in ways
-- that are not anticipated by our limited usage.  If you wish to support these
-- users, you may wish to generalize your support (our support is generalized
-- where practical.)

with System;
use System;
with A_Strings;

package Os_Files is

    type File_Descriptor is new Integer;
    -- "file_descriptor" is used to identify the device-specific
    -- information control block associated with the specific file.
    -- it may be any type, but is typically either an integer (for
    -- cross systems and Unix) or a control block address (VMS).

    type File_Styles is (Text, Sequential, Direct, Special);
    -- "file_styles" identifies the Ada nature of the file.  "text" means
    -- the file is an Ada text_io file, sequential means a sequential_io
    -- file, direct means a direct_io file, and special means one of
    -- standard_input, standard_output or standard_error (all used with
    -- text_io.)


    Default_Buffer_Size : Integer := 1024;

    -- Text_io is buffered.  The buffer size may be set by calling
    -- file_support.setup_buffer, but will default on open/create to
    -- a buffer of this size.  May be reset by user.

    subtype Name_String is String (1 .. 1024);
    -- mjs@6/23/93
    -- Subtype needs to be constant range
    --
    -- file names are restricted to being no longer than a single buffer
    -- in length.  In some implementations, one or more special characters
    -- such as a closing CR are required in every text string, including
    -- file names, so these must be allowed for.

    type Open_Flags is new Integer;
    O_Rdonly : constant Open_Flags := 8#0000#;
    O_Wronly : constant Open_Flags := 8#0001#;
    O_Rdwr : constant Open_Flags := 8#0002#;
    O_Ndelay : constant Open_Flags := 8#0004#;
    O_Append : constant Open_Flags := 8#0010#;
--           Sun4 BSD Unix.
    O_Async : constant Open_Flags := 8#0100#;
    O_Creat : constant Open_Flags := 8#1000#;
    O_Trunc : constant Open_Flags := 8#2000#;
    O_Excl : constant Open_Flags := 8#4000#;
    O_Sync : constant Open_Flags := 8#10000#;

    subtype Permission is Integer range 0 .. 8#7777#;

    function "+" (Left, Right : Open_Flags) return Open_Flags;
    function "-" (Left, Right : Open_Flags) return Open_Flags;
    -- The open_flags constants are really an enumeration with a
    -- representation, but for historical reasons are left as a set
    -- of constants.  They are used to form a bit mask of allowed or
    -- requested properties for files.  They are not related to any
    -- specific external file representation, although they conform to
    -- Unix meanings.

    type File_Id_Ptr is private;
    Invalid : constant File_Id_Ptr;
    -- The file_id is a machine-dependent data structure that provides
    -- information that UNIQUELY identifies each external file.  This
    -- information is used to determine if a given external file is already
    -- open via a different file descriptor.  Typically, file names and
    -- directories can be aliased/abbreviated and so the file names are
    -- not themselves useful in uniquely identifying the physical file.
    -- On Unix, we use the inode/device numbers.  On VMS, we are forced
    -- to use the "canonicalized" file name, as there are no accessible
    -- unique internal file ids.  The "invalid" value is a file_id for an
    -- unopen file.

    Stdin_Fd : File_Descriptor;
    Stdout_Fd : File_Descriptor;
    Stderr_Fd : File_Descriptor;
    -- the machine-dependent file_descriptors of the special files
    function Std_Input_Name return String;
    function Std_Output_Name return String;
    function Std_Error_Name return String;
    -- the machine-dependent names for the special files.

    Always_Flush_Files : Boolean;
    -- Because text_io is buffered, it may be desirable that output
    -- appear immediately in the physical file.  If this global is set,
    -- then all files opened while it is set will be flushed at the end
    -- of each user transaction.  For example, if a user calls:
    --     put("what? ");
    -- Then the six characters "what? " would normally just be placed into
    -- the buffer - writing would only happen if the buffer happened to
    -- fill at one of those characters, and would then happen only up to
    -- the specific character that filled it.  If the output file is
    -- being read by a person or program as it appears, or is to be mixed
    -- with output from other tasks or programs, it is desirable that the
    -- output appear immediately.  Note that os_files_b.a implementations
    -- should turn on always_flush for any file that is known to be
    -- shared, or that is writing to a terminal.

    function Get_File_Id (Fd : File_Descriptor) return File_Id_Ptr;
    -- returns the pointer to the unique file identifier information
    -- used normally only with os_files itself, to see if external files
    -- are already in use in this program
    function File_Size
                (Fd : File_Descriptor; Elem_Size : Integer) return Integer;
    -- returns the size of the external file, in number of elements
    -- (use normally only for direct_io files.)
    function Is_Interactive (Fd : File_Descriptor) return Boolean;
    -- returns true iff file is associated with an interactive external
    -- device, such as a terminal;  is used to set always_flush.
    procedure Position_File (Fd : File_Descriptor; To, Size : Integer);
    -- used to establish the external file information to read/write
    -- at the "to"th element.  The first element is numbered 0.
    -- normally used only for direct_io files.  "size" is the element_size
    -- for the file elements (constant.)
    procedure Skip_In_File (Fd : File_Descriptor; To : Integer);
    -- used to skip ahead "to" BYTEs.  Normally called only for
    -- sequential_io files, to skip past padding bytes to the start of
    -- the next element.
    function Read (Fd : File_Descriptor; Addr : System.Address; Cnt : Integer)
                  return Integer;
    -- used to read up to "cnt" BYTEs from the file named by "fd" to the
    -- buffer memory at "addr".  It will retry on Unix or VMS, as interrupts
    -- may cause timeouts and so forth.  The actual number of characters,
    -- adjusted by "fix_end_of_record" is returned.  If "fix_end_of_record"
    -- does nothing, then the actual number of characters read is returned;
    -- an end-of-file condition is represented by a 0.  If, however,
    -- "fix_end_of_record" changes the record, then the number returned
    -- must be adjusted in a way to cooperate - a "-1" might be returned
    -- to signal EOF if it is known that fix_end_of_record will always
    -- add an end-of-record character such as a LF.  See below.
    procedure Write
                 (Fd : File_Descriptor; Addr : System.Address; Cnt : Integer);
    -- used to write "cnt" BYTEs into the current position of the file
    -- named by "fd", from the buffer memory at "addr".  It should keep
    -- attempting to write until all the bytes are written.  It should
    -- assume that the bytes are already in the correct format for the
    -- external file.
    function Same_Id (F1, F2 : File_Id_Ptr) return Boolean;
    -- returns true if the two file_ids name the same file.
    function At_End_Of_File (Fd : File_Descriptor) return Boolean;
    -- returns true iff the associated external file is at EOF.
    procedure Fix_End_Of_Record
                 (File : System.Address; Actual : in out Integer);
    -- takes a buffer and count of bytes that has presumably just been read
    -- and converts them into the format expected by Ada.  In Ada, lines
    -- of text are always terminated by an ASCII.LF (line feed);
    -- however, on systems such as VMS a CR (carriage return) may be
    -- represented implicitly in the external file.  For VMS, then, this
    -- routine adds a LF on to the end of each line read, adjusting the
    -- "actual" to include the LF.  Note that if a VMS EOF is read,
    -- our implementation on VMS expects an actual of -1, and adds the LF
    -- anyway - leaving an actual of 0, correctly indicating EOF.
    function Ok_To_Write (File : System.Address) return Boolean;
    -- on most systems, buffers are always "ok_to_write".  But on some
    -- systems, only certain kinds of lines can be output.  For example,
    -- on VMS only lines that end in ASCII.LF should be output because
    -- VMS is record-oriented - every output is considered to be a line.
    -- Note that this routine is given access to the entire file_type
    -- object.  It can therefore make changes directly in the associated
    -- buffer for the file.  These changes are typically the inverse of
    -- the changes done after reading a line by "fix_end_of_record".
    function Flushable (Fd : File_Descriptor) return Boolean;
    -- Some operating systems, for example VMS, have non-trivial
    -- ok_to_write semantics.  When it is not possible to flush buffers
    -- arbitrarily, this function should return FALSE.  This prevents
    -- non-flushable files from being opened under two different file
    -- variables - and then having a confused input/output due to buffering.
    procedure Open (File : System.Address;
                    Style : File_Styles;
                    Mode : Open_Flags);
    -- opens the named external file;  raises NAME_ERROR or USE_ERROR
    -- as appropriate for Ada semantics.  File should be opened with
    -- the given requested properties.  Note that files will normally be
    -- requested in READ/WRITE mode unless READ mode is specifically
    -- denied them.
    procedure Close (Fd : File_Descriptor);
    -- closes the given external file.  Note that if the program ends in
    -- an exception, ada_exit will eventually call close_all.a, which will
    -- step through the list of open files and close them.
    procedure Truncate (Fd : File_Descriptor);
    -- truncates the given external file
    procedure Delete (Fd : File_Descriptor; Name : A_Strings.A_String);
    -- delete named file (for VMS, name is required)
    function Get_Tempname (Root : String) return A_Strings.A_String;
    -- return string representing unique temporary file for this program.
    -- (on many hosts, a process id can be used with a count).
    function Get_Full_Name (Name : String; Style : File_Styles)
                           return A_Strings.A_String;
    -- return string representing "canonical" full name of file,
    -- including directory, etc.
    procedure Free_File_Id (Id_Ptr : in out File_Id_Ptr);

    -- pragma inline(position_file, read, write, at_end_of_file);
private
    type File_Id_Type;
    type File_Id_Ptr is access File_Id_Type;
    Invalid : constant File_Id_Ptr := null;
end Os_Files;
DataMuseum.dk

Rational R1000/400

⟦16c49238f⟧ Ada Source

Derivation

E3 Source Code

E3 Meta Data
