⟦109860943⟧

TextFile

-- 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
DataMuseum.dk

Rational R1000/400

⟦109860943⟧ TextFile

Derivation

TextFile
