indexing
	description: "Sequential files, viewed as persistent sequences of characters"
	library: "Free implementation of ELKS library"
	copyright: "Copyright (c) 1986-2008, Eiffel Software and others"
	license: "Eiffel Forum License v2 (see forum.txt)"
	date: "$Date: 2008-05-23 17:24:07 -0700 (Fri, 23 May 2008) $"
	revision: "$Revision: 170 $"

deferred class interface
	FILE


feature -- Initialization

	make (fn: STRING_8)
			-- Create file object with `fn' as file name.
		require
			string_exists: fn /= Void
			string_not_empty: not fn.is_empty
		ensure
			file_named: name = fn
			file_closed: is_closed

	make_create_read_write (fn: STRING_8)
			-- Create file object with `fn' as file name
			-- and open file for both reading and writing;
			-- create it if it does not exist.
		require
			string_exists: fn /= Void
			string_not_empty: not fn.is_empty
		ensure
			file_named: name = fn
			exists: exists
			open_read: is_open_read
			open_write: is_open_write

	make_open_append (fn: STRING_8)
			-- Create file object with `fn' as file name
			-- and open file in append-only mode.
		require
			string_exists: fn /= Void
			string_not_empty: not fn.is_empty
		ensure
			file_named: name = fn
			exists: exists
			open_append: is_open_append

	make_open_read (fn: STRING_8)
			-- Create file object with `fn' as file name
			-- and open file in read mode.
		require
			string_exists: fn /= Void
			string_not_empty: not fn.is_empty
		ensure
			file_named: name = fn
			exists: exists
			open_read: is_open_read

	make_open_read_append (fn: STRING_8)
			-- Create file object with `fn' as file name
			-- and open file for reading anywhere
			-- but writing at the end only.
			-- Create file if it does not exist.
		require
			string_exists: fn /= Void
			string_not_empty: not fn.is_empty
		ensure
			file_named: name = fn
			exists: exists
			open_read: is_open_read
			open_append: is_open_append

	make_open_read_write (fn: STRING_8)
			-- Create file object with `fn' as file name
			-- and open file for both reading and writing.
		require
			string_exists: fn /= Void
			string_not_empty: not fn.is_empty
		ensure
			file_named: name = fn
			exists: exists
			open_read: is_open_read
			open_write: is_open_write

	make_open_write (fn: STRING_8)
			-- Create file object with `fn' as file name
			-- and open file for writing;
			-- create it if it does not exist.
		require
			string_exists: fn /= Void
			string_not_empty: not fn.is_empty
		ensure
			file_named: name = fn
			exists: exists
			open_write: is_open_write
	
feature -- Access

	access_date: INTEGER_32
			-- Time stamp of last access made to the inode.
		require
			file_exists: exists

	date: INTEGER_32
			-- Time stamp (time of last modification)
		require
			file_exists: exists

	descriptor: INTEGER_32
			-- File descriptor as used by the operating system.
		require -- from IO_MEDIUM
			valid_handle: descriptor_available
		require else
			file_opened: not is_closed

	descriptor_available: BOOLEAN

	file_info: UNIX_FILE_INFO
			-- Collected information about the file.

	file_pointer: POINTER
			-- File pointer as required in C

	generating_type: STRING_8
			-- Name of current object's generating type
			-- (type of which it is a direct instance)
			-- (from ANY)
		ensure -- from ANY
			generating_type_not_void: Result /= Void
			generating_type_not_empty: not Result.is_empty

	generator: STRING_8
			-- Name of current object's generating class
			-- (base class of the type of which it is a direct instance)
			-- (from ANY)
		ensure -- from ANY
			generator_not_void: Result /= Void
			generator_not_empty: not Result.is_empty

	group_id: INTEGER_32
			-- Group identification of owner
		require
			file_exists: exists

	has (v: like item): BOOLEAN
			-- Does structure include an occurrence of `v'?
			-- (Reference or object equality,
			-- based on object_comparison.)
			-- (from LINEAR)
		require -- from  CONTAINER
			True
		ensure -- from CONTAINER
			not_found_in_empty: Result implies not is_empty

	index: INTEGER_32
			-- Index of current position
			-- (from LINEAR)

	index_of (v: like item; i: INTEGER_32): INTEGER_32
			-- Index of `i'-th occurrence of `v'.
			-- 0 if none.
			-- (Reference or object equality,
			-- based on object_comparison.)
			-- (from LINEAR)
		require -- from LINEAR
			positive_occurrences: i > 0
		ensure -- from LINEAR
			non_negative_result: Result >= 0

	inode: INTEGER_32
			-- I-node number
		require
			file_exists: exists

	item: CHARACTER_8
			-- Current item
		require -- from TRAVERSABLE
			not_off: not off
		require -- from ACTIVE
			readable: readable

	item_for_iteration: CHARACTER_8
			-- Item at current position
			-- (from LINEAR)
		require -- from LINEAR
			not_off: not off

	links: INTEGER_32
			-- Number of links on file
		require
			file_exists: exists

	name: STRING_8
			-- File name

	occurrences (v: like item): INTEGER_32
			-- Number of times `v' appears.
			-- (Reference or object equality,
			-- based on object_comparison.)
			-- (from LINEAR)
		require -- from  BAG
			True
		ensure -- from BAG
			non_negative_occurrences: Result >= 0

	owner_name: STRING_8
			-- Name of owner
		require
			file_exists: exists

	position: INTEGER_32
			-- Current cursor position.

	protection: INTEGER_32
			-- Protection mode, in decimal value
		require
			file_exists: exists

	retrieved: ANY
			-- Retrieved object structure
			-- To access resulting object under correct type,
			-- use assignment attempt.
			-- Will raise an exception (code `Retrieve_exception')
			-- if content is not a stored Eiffel structure.
		require -- from IO_MEDIUM
			is_readable: readable
			support_storable: support_storable
		ensure -- from IO_MEDIUM
			result_exists: Result /= Void

	separator: CHARACTER_8
			-- ASCII code of character following last word read

	user_id: INTEGER_32
			-- User identification of owner
		require
			file_exists: exists
	
feature -- Measurement

	count: INTEGER_32
			-- Size in bytes (0 if no associated physical file)
	
feature -- Comparison

	frozen deep_equal (some: ?ANY; other: like arg #1): BOOLEAN
			-- Are `some' and `other' either both void
			-- or attached to isomorphic object structures?
			-- (from ANY)
		ensure -- from ANY
			shallow_implies_deep: standard_equal (some, other) implies Result
			both_or_none_void: (some = Void) implies (Result = (other = Void))
			same_type: (Result and (some /= Void)) implies (other /= Void and then some.same_type (other))
			symmetric: Result implies deep_equal (other, some)

	frozen equal (some: ?ANY; other: like arg #1): BOOLEAN
			-- Are `some' and `other' either both void or attached
			-- to objects considered equal?
			-- (from ANY)
		ensure -- from ANY
			definition: Result = (some = Void and other = Void) or else ((some /= Void and other /= Void) and then some.is_equal (other))

	frozen is_deep_equal (other: FILE): BOOLEAN
			-- Are `Current' and `other' attached to isomorphic object structures?
			-- (from ANY)
		require -- from ANY
			other_not_void: other /= Void
		ensure -- from ANY
			shallow_implies_deep: standard_is_equal (other) implies Result
			same_type: Result implies same_type (other)
			symmetric: Result implies other.is_deep_equal (Current)

	is_equal (other: FILE): BOOLEAN
			-- Is `other' attached to an object considered
			-- equal to current object?
			-- (from ANY)
		require -- from ANY
			other_not_void: other /= Void
		ensure -- from ANY
			symmetric: Result implies other.is_equal (Current)
			consistent: standard_is_equal (other) implies Result

	same_file (fn: STRING_8): BOOLEAN
			-- Is current file the same as `a_filename'?
		require
			fn_not_void: fn /= Void
			fn_not_empty: not fn.is_empty

	frozen standard_equal (some: ?ANY; other: like arg #1): BOOLEAN
			-- Are `some' and `other' either both void or attached to
			-- field-by-field identical objects of the same type?
			-- Always uses default object comparison criterion.
			-- (from ANY)
		ensure -- from ANY
			definition: Result = (some = Void and other = Void) or else ((some /= Void and other /= Void) and then some.standard_is_equal (other))

	frozen standard_is_equal (other: FILE): BOOLEAN
			-- Is `other' attached to an object of the same type
			-- as current object, and field-by-field identical to it?
			-- (from ANY)
		require -- from ANY
			other_not_void: other /= Void
		ensure -- from ANY
			same_type: Result implies same_type (other)
			symmetric: Result implies other.standard_is_equal (Current)
	
feature -- Status report

	access_exists: BOOLEAN
			-- Does physical file exist?
			-- (Uses real UID.)

	after: BOOLEAN
			-- Is there no valid cursor position to the right of cursor position?

	before: BOOLEAN
			-- Is there no valid cursor position to the left of cursor position?

	bytes_read: INTEGER_32
			-- Last number of bytes read by read_to_managed_pointer.
			-- (from IO_MEDIUM)

	changeable_comparison_criterion: BOOLEAN
			-- May object_comparison be changed?
			-- (Answer: yes by default.)
			-- (from CONTAINER)

	conforms_to (other: ANY): BOOLEAN
			-- Does type of current object conform to type
			-- of `other' (as per Eiffel: The Language, chapter 13)?
			-- (from ANY)
		require -- from ANY
			other_not_void: other /= Void

	end_of_file: BOOLEAN
			-- Has an EOF been detected?
		require
			opened: not is_closed

	exhausted: BOOLEAN
			-- Has structure been completely explored?
			-- (from LINEAR)
		ensure -- from LINEAR
			exhausted_when_off: off implies Result

	exists: BOOLEAN
			-- Does physical file exist?
			-- (Uses effective UID.)
		require -- from  IO_MEDIUM
			True
		ensure then
			unchanged_mode: mode = old mode

	extendible: BOOLEAN
			-- May new items be added?
		require -- from  COLLECTION
			True
		require -- from  IO_MEDIUM
			True

	file_readable: BOOLEAN
			-- Is there a current item that may be read?

	file_writable: BOOLEAN
			-- Is there a current item that may be modified?

	full: BOOLEAN is False
			-- Is structure filled to capacity?

	is_access_executable: BOOLEAN
			-- Is file executable by real UID?
		require
			file_exists: exists

	is_access_owner: BOOLEAN
			-- Is file owned by real UID?
		require
			file_exists: exists

	is_access_readable: BOOLEAN
			-- Is file readable by real UID?
		require
			file_exists: exists

	is_access_writable: BOOLEAN
			-- Is file writable by real UID?
		require
			file_exists: exists

	is_block: BOOLEAN
			-- Is file a block special file?
		require
			file_exists: exists

	is_character: BOOLEAN
			-- Is file a character special file?
		require
			file_exists: exists

	is_closed: BOOLEAN
			-- Is file closed?

	is_creatable: BOOLEAN
			-- Is file creatable in parent directory?
			-- (Uses effective UID to check that parent is writable
			-- and file does not exist.)

	is_device: BOOLEAN
			-- Is file a device?
		require
			file_exists: exists

	is_directory: BOOLEAN
			-- Is file a directory?
		require
			file_exists: exists

	is_empty: BOOLEAN
			-- Is structure empty?
			-- (from FINITE)

	is_executable: BOOLEAN
			-- Is file executable?
			-- (Checks execute permission for effective UID.)
		require -- from IO_MEDIUM
			handle_exists: exists

	is_fifo: BOOLEAN
			-- Is file a named pipe?
		require
			file_exists: exists

	is_inserted (v: CHARACTER_8): BOOLEAN
			-- Has `v' been inserted by the most recent insertion?
			-- (By default, the value returned is equivalent to calling 
			-- `has (v)'. However, descendants might be able to provide more
			-- efficient implementations.)
			-- (from COLLECTION)

	is_open_append: BOOLEAN
			-- Is file open for appending?

	is_open_read: BOOLEAN
			-- Is file open for reading?

	is_open_write: BOOLEAN
			-- Is file open for writing?

	is_owner: BOOLEAN
			-- Is file owned by effective UID?
		require
			file_exists: exists

	is_plain: BOOLEAN
			-- Is file a plain file?
		require
			file_exists: exists

	is_plain_text: BOOLEAN
			-- Is file reserved for text (character sequences)?
			-- (from IO_MEDIUM)

	is_readable: BOOLEAN
			-- Is file readable?
			-- (Checks permission for effective UID.)
		require -- from IO_MEDIUM
			handle_exists: exists

	is_setgid: BOOLEAN
			-- Is file setgid?
		require
			file_exists: exists

	is_setuid: BOOLEAN
			-- Is file setuid?
		require
			file_exists: exists

	is_socket: BOOLEAN
			-- Is file a named socket?
		require
			file_exists: exists

	is_sticky: BOOLEAN
			-- Is file sticky (for memory swaps)?
		require
			file_exists: exists

	is_symlink: BOOLEAN
			-- Is file a symbolic link?
		require
			file_exists: exists

	is_writable: BOOLEAN
			-- Is file writable?
			-- (Checks write permission for effective UID.)
		require -- from IO_MEDIUM
			handle_exists: exists

	last_character: CHARACTER_8
			-- Last character read by read_character
			-- (from IO_MEDIUM)

	last_double: REAL_64
			-- Last double read by read_double
			-- (from IO_MEDIUM)

	last_integer: INTEGER_32
			-- Last integer read by read_integer
			-- (from IO_MEDIUM)

	last_integer_16: INTEGER_16
			-- Last 16-bit integer read by read_integer_16
			-- (from IO_MEDIUM)

	last_integer_32: INTEGER_32
			-- Synonymy of last_integer
			-- (from IO_MEDIUM)

	last_integer_64: INTEGER_64
			-- Last 64-bit integer read by read_integer_64
			-- (from IO_MEDIUM)

	last_integer_8: INTEGER_8
			-- Last 8-bit integer read by read_integer_8
			-- (from IO_MEDIUM)

	last_natural: NATURAL_32
			-- Last 32-bit natural read by read_natural
			-- (from IO_MEDIUM)

	last_natural_16: NATURAL_16
			-- Last 16-bit natural read by read_natural_16
			-- (from IO_MEDIUM)

	last_natural_32: NATURAL_32
			-- Synonymy of last_natural
			-- (from IO_MEDIUM)

	last_natural_64: NATURAL_64
			-- Last 64-bit natural read by read_natural_64
			-- (from IO_MEDIUM)

	last_natural_8: NATURAL_8
			-- Last 8-bit natural read by read_natural_8
			-- (from IO_MEDIUM)

	last_real: REAL_32
			-- Last real read by read_real
			-- (from IO_MEDIUM)

	last_string: ?STRING_8
			-- Last string read
			-- (from IO_MEDIUM)

	object_comparison: BOOLEAN
			-- Must search operations use equal rather than `='
			-- for comparing references? (Default: no, use `='.)
			-- (from CONTAINER)

	off: BOOLEAN
			-- Is there no item?
		require -- from  TRAVERSABLE
			True

	path_exists: BOOLEAN
			-- Does physical file name exist without resolving
			-- symbolic links?
		ensure then
			unchanged_mode: mode = old mode

	prunable: BOOLEAN
			-- Is there an item to be removed?

	readable: BOOLEAN
			-- Is there a current item that may be read?
			-- (from SEQUENCE)
		require -- from  ACTIVE
			True
		require -- from IO_MEDIUM
			handle_exists: exists

	same_type (other: ANY): BOOLEAN
			-- Is type of current object identical to type of `other'?
			-- (from ANY)
		require -- from ANY
			other_not_void: other /= Void
		ensure -- from ANY
			definition: Result = (conforms_to (other) and other.conforms_to (Current))

	support_storable: BOOLEAN
			-- Can medium be used to store an Eiffel object?
			-- (from IO_MEDIUM)

	writable: BOOLEAN
			-- Is there a current item that may be modified?
			-- (from SEQUENCE)
	
feature -- Status setting

	close
			-- Close file.
		require -- from IO_MEDIUM
			medium_is_open: not is_closed
		ensure then
			is_closed: is_closed

	compare_objects
			-- Ensure that future search operations will use equal
			-- rather than `=' for comparing references.
			-- (from CONTAINER)
		require -- from CONTAINER
			changeable_comparison_criterion: changeable_comparison_criterion
		ensure -- from CONTAINER
			object_comparison

	compare_references
			-- Ensure that future search operations will use `='
			-- rather than equal for comparing references.
			-- (from CONTAINER)
		require -- from CONTAINER
			changeable_comparison_criterion: changeable_comparison_criterion
		ensure -- from CONTAINER
			reference_comparison: not object_comparison

	create_read_write
			-- Open file in read and write mode;
			-- create it if it does not exist.
		require
			is_closed: is_closed
		ensure
			exists: exists
			open_read: is_open_read
			open_write: is_open_write

	fd_open_append (fd: INTEGER_32)
			-- Open file of descriptor `fd' in append mode.
		ensure
			exists: exists
			open_append: is_open_append

	fd_open_read (fd: INTEGER_32)
			-- Open file of descriptor `fd' in read-only mode.
		ensure
			exists: exists
			open_read: is_open_read

	fd_open_read_append (fd: INTEGER_32)
			-- Open file of descriptor `fd'
			-- in read and write-at-end mode.
		ensure
			exists: exists
			open_read: is_open_read
			open_append: is_open_append

	fd_open_read_write (fd: INTEGER_32)
			-- Open file of descriptor `fd' in read-write mode.
		ensure
			exists: exists
			open_read: is_open_read
			open_write: is_open_write

	fd_open_write (fd: INTEGER_32)
			-- Open file of descriptor `fd' in write mode.
		ensure
			exists: exists
			open_write: is_open_write

	open_append
			-- Open file in append-only mode;
			-- create it if it does not exist.
		require
			is_closed: is_closed
		ensure
			exists: exists
			open_append: is_open_append

	open_read
			-- Open file in read-only mode.
		require
			is_closed: is_closed
		ensure
			exists: exists
			open_read: is_open_read

	open_read_append
			-- Open file in read and write-at-end mode;
			-- create it if it does not exist.
		require
			is_closed: is_closed
		ensure
			exists: exists
			open_read: is_open_read
			open_append: is_open_append

	open_read_write
			-- Open file in read and write mode.
		require
			is_closed: is_closed
		ensure
			exists: exists
			open_read: is_open_read
			open_write: is_open_write

	open_write
			-- Open file in write-only mode;
			-- create it if it does not exist.
		ensure
			exists: exists
			open_write: is_open_write

	recreate_read_write (fname: STRING_8)
			-- Reopen in read-write mode with file of name `fname';
			-- create file if it does not exist.
		require
			is_open: not is_closed
			valid_name: fname /= Void
		ensure
			exists: exists
			open_read: is_open_read
			open_write: is_open_write

	reopen_append (fname: STRING_8)
			-- Reopen in append mode with file of name `fname';
			-- create file if it does not exist.
		require
			is_open: not is_closed
			valid_name: fname /= Void
		ensure
			exists: exists
			open_append: is_open_append

	reopen_read (fname: STRING_8)
			-- Reopen in read-only mode with file of name `fname';
			-- create file if it does not exist.
		require
			is_open: not is_closed
			valid_name: fname /= Void
		ensure
			exists: exists
			open_read: is_open_read

	reopen_read_append (fname: STRING_8)
			-- Reopen in read and write-at-end mode with file
			-- of name `fname'; create file if it does not exist.
		require
			is_open: not is_closed
			valid_name: fname /= Void
		ensure
			exists: exists
			open_read: is_open_read
			open_append: is_open_append

	reopen_read_write (fname: STRING_8)
			-- Reopen in read-write mode with file of name `fname'.
		require
			is_open: not is_closed
			valid_name: fname /= Void
		ensure
			exists: exists
			open_read: is_open_read
			open_write: is_open_write

	reopen_write (fname: STRING_8)
			-- Reopen in write-only mode with file of name `fname';
			-- create file if it does not exist.
		require
			is_open: not is_closed
			valid_name: fname /= Void
		ensure
			exists: exists
			open_write: is_open_write
	
feature -- Cursor movement

	back
			-- Go back one position.
		require -- from BILINEAR
			not_before: not before

	finish
			-- Go to last position.
		require -- from  LINEAR
			True
		require else
			file_opened: not is_closed

	forth
			-- Go to next position.
		require -- from LINEAR
			not_after: not after
		require else
			file_opened: not is_closed

	go (abs_position: INTEGER_32)
			-- Go to the absolute position.
			-- (New position may be beyond physical length.)
		require
			file_opened: not is_closed
			non_negative_argument: abs_position >= 0

	move (offset: INTEGER_32)
			-- Advance by `offset' from current location.
		require
			file_opened: not is_closed

	next_line
			-- Move to next input line.
		require
			is_readable: file_readable

	recede (abs_position: INTEGER_32)
			-- Go to the absolute position backwards,
			-- starting from end of file.
		require
			file_opened: not is_closed
			non_negative_argument: abs_position >= 0

	search (v: like item)
			-- Move to first position (at or after current
			-- position) where item and `v' are equal.
			-- If structure does not include `v' ensure that
			-- exhausted will be true.
			-- (Reference or object equality,
			-- based on object_comparison.)
			-- (from BILINEAR)
		ensure -- from LINEAR
			object_found: (not exhausted and object_comparison) implies equal (v, item)
			item_found: (not exhausted and not object_comparison) implies v = item

	start
			-- Go to first position.
		require -- from  TRAVERSABLE
			True
		require else
			file_opened: not is_closed
	
feature -- Element change

	add_permission (who, what: STRING_8)
			-- Add read, write, execute or setuid permission
			-- for `who' ('u', 'g' or 'o') to `what'.
		require
			who_is_not_void: who /= Void
			what_is_not_void: what /= Void
			file_descriptor_exists: exists

	append (f: like Current)
			-- Append a copy of the contents of `f'.
		require -- from SEQUENCE
			argument_not_void: f /= Void
		require else
			target_is_closed: is_closed
			source_is_closed: f.is_closed
		ensure -- from SEQUENCE
			new_count: count >= old count
		ensure then
			new_count: count = old count + f.count
			files_closed: f.is_closed and is_closed

	basic_store (object: ANY)
			-- Produce an external representation of the
			-- entire object structure reachable from `object'.
			-- Retrievable within current system only.
		require -- from IO_MEDIUM
			object_not_void: object /= Void
			extendible: extendible
			support_storable: support_storable

	change_date: INTEGER_32
			-- Time stamp of last change.
		require
			file_exists: exists

	change_group (new_group_id: INTEGER_32)
			-- Change group of file to `new_group_id' found in
			-- system password file.
		require
			file_exists: exists

	change_mode (mask: INTEGER_32)
			-- Replace mode by `mask'.
		require
			file_exists: exists