Go to the first, previous, next, last section, table of contents.


Basic file/stream handling

Author(s): Daniel Cabeza, Mats Carlsson.

Version: 1.11#222 (2004/5/24, 13:8:7 CEST)

Version of last change: 1.11#125 (2003/12/29, 18:52:30 CET)

This module provides basic predicates for handling files and streams, in order to make input/output on them.

Usage and interface (streams_basic)

Documentation on exports (streams_basic)

PREDICATE: open/3:

open(File, Mode, Stream)

Open File with mode Mode and return in Stream the stream associated with the file. No extension is implicit in File.

General properties:

Usage 1: * ISO *

Usage 2:

PREDICATE: open/4:

open(File, Mode, Stream, Options)

Same as open(File, Mode, Stream) with options Options. See the definition of open_option_list/1 for details.

Usage:

REGTYPE: open_option_list/1:

A list of options for open/4, currently the meaningful options are:

lock
Try to set an advisory lock for the file. If the open mode is read, the lock is a read (shared) lock, else it is a write (exclusive) lock. If the lock cannot be acquired, the call waits until it is released (but can fail in exceptional cases).
lock_nb
Same as lock, but the call immediately fails if the lock cannot be acquired.
lock(Lock_Mode)
Same as lock, but specifying in Lock_Mode whether the lock is read (also shared) or write (also exclusive). This option has be included for compatibility with the SWI-Prolog locking options, because in general the type of lock should match the open mode as in the lock option.
lock_nb(Lock_Mode)
Same as the previous option but with the lock_nb behavior.

All file locking is implemented via the POSIX function fcntl(). Please refer to its manual page for details.

Usage: open_option_list(L)

PREDICATE: close/1:

close(Stream)

Close the stream Stream.

Usage: * ISO *

PREDICATE: set_input/1:

set_input(Stream)

Set the current input stream to Stream. A notion of current input stream is maintained by the system, so that input predicates with no explicit stream operate on the current input stream. Initially it is set to user_input.

Usage: * ISO *

PREDICATE: current_input/1:

current_input(Stream)

Unify Stream with the current input stream. In addition to the ISO behavior, stream aliases are allowed. This is useful for most applications checking whether a stream is the standard input or output.

Usage: * ISO *

PREDICATE: set_output/1:

set_output(Stream)

Set the current output stream to Stream. A notion of current output stream is maintained by the system, so that output predicates with no explicit stream operate on the current output stream. Initially it is set to user_output.

Usage: * ISO *

PREDICATE: current_output/1:

current_output(Stream)

Unify Stream with the current output stream. The same comment as for current_input/1 applies.

Usage: * ISO *

PREDICATE: character_count/2:

character_count(Stream, Count)

Count characters have been read from or written to Stream.

Usage:

PREDICATE: line_count/2:

line_count(Stream, Count)

Count lines have been read from or written to Stream.

Usage:

PREDICATE: line_position/2:

line_position(Stream, Count)

Count characters have been read from or written to the current line of Stream.

Usage:

PREDICATE: flush_output/1:

flush_output(Stream)

Flush any buffered data to output stream Stream.

Usage: * ISO *

PREDICATE: flush_output/0:

flush_output(flush_output

Behaves like current_output(S), flush_output(S)

PREDICATE: clearerr/1:

clearerr(Stream)

Clear the end-of-file and error indicators for input stream Stream.

Usage:

PREDICATE: current_stream/3:

current_stream(Filename, Mode, Stream)

Stream is a stream which was opened in mode Mode and which is connected to the absolute file name Filename (an atom) or to the file descriptor Filename (an integer). This predicate can be used for enumerating all currently open streams through backtracking.

General properties:

Usage 1:

Usage 2:

PREDICATE: stream_code/2:

stream_code(Stream, StreamCode)

StreamCode is the file descriptor (an integer) corresponding to the Prolog stream Stream.

Usage 1:

Usage 2:

PREDICATE: absolute_file_name/2:

absolute_file_name(RelFileSpec, AbsFileSpec)

If RelFileSpec is an absolute pathname then do an absolute lookup. If RelFileSpec is a relative pathname then prefix the name with the name of the current directory and do an absolute lookup. If RelFileSpec is a path alias, perform the lookup following the path alias rules (see sourcename/1). In all cases: if a matching file with suffix .pl exists, then AbsFileSpec will be unified with this file. Failure to open a file normally causes an exception. The behaviour can be controlled by the fileerrors prolog flag.

Usage: absolute_file_name(RelFileSpec, AbsFileSpec)

PREDICATE: absolute_file_name/7:

absolute_file_name(Spec, Opt, Suffix, CurrDir, AbsFile, AbsBase, AbsDir)

AbsFile is the absolute name (with full path) of Spec, which has an optional first suffix Opt and an optional second suffix Suffix, when the current directory is CurrDir. AbsBase is the same as AbsFile, but without the second suffix, and AbsDir is the absolute path of the directory where AbsFile is. The Ciao compiler invokes this predicate with Opt='_opt' and Suffix='.pl' when searching source files.

Usage:

REGTYPE: sourcename/1:

A source name is a flexible way of referring to a concrete file. A source name is either a relative or absolute filename given as:

In all cases certain filename extensions (e.g., .pl) can be implicit. In the first form above, file names can be relative to the current directory. Also, file names beginning with ~ or $ are treated specially. For example,

'~/ciao/sample.pl'
is equivalent to '/home/staff/herme/ciao/sample.pl', if /home/staff/herme is the user's home directory. (This is also equivalent to '$HOME/ciao/sample.pl' as explained below.)
'~bardo/prolog/sample.pl'
is equivalent to '/home/bardo/prolog/sample.pl', if /home/bardo is bardo's home directory.
'$UTIL/sample.pl'
is equivalent to '/usr/local/src/utilities/sample.pl', if /usr/local/src/utilities is the value of the environment variable UTIL.

The second form allows using path aliases. Such aliases allow refering to files not with absolute file system paths but with paths which are relative to predefined (or user-defined) abstract names. For example, given the path alias myutils which has been defined to refer to path '/home/bardo/utilities', if that directory contains the file stuff.pl then the term myutils(stuff) in a use_module/1 declaration would refer to the file '/home/bardo/utilities/stuff.pl' (the .pl extension is implicit in the use_module/1 declaration). As a special case, if that directory contains a subdirectory named stuff which in turn contains the file stuff.pl, the same term would refer to the file '/home/bardo/utilities/stuff/stuff.pl'. If a path alias is related to several paths, all paths are scanned in sequence until a match is found. For information on predefined path aliases or how to define new path aliases, see file_search_path/2.

Usage: sourcename(F)

REGTYPE: stream/1:

Streams correspond to the file pointers used at the operating system level, and usually represent opened files. There are four special streams which correspond with the operating system standard streams:

user_input
The standard input stream, i.e. the terminal, usually.
user_output
The standard output stream, i.e. the terminal, usually.
user_error
The standard error stream.
user
The standard input or output stream, depending on context.

Usage: stream(S)

REGTYPE: stream_alias/1:

Usage: stream_alias(S)

REGTYPE: io_mode/1:

Can have the following values:

read
Open the file for input.
write
Open the file for output. The file is created if it does not already exist, the file will otherwise be truncated.
append
Open the file for output. The file is created if it does not already exist, the file will otherwise be appended to.

Usage: io_mode(M)

Documentation on multifiles (streams_basic)

PREDICATE: file_search_path/2:

file_search_path(Alias, Path)

The path alias Alias is linked to path Path. Both arguments must be atoms. New facts (or clauses) of this predicate can be asserted to define new path aliases. Predefined path aliases in Ciao are:

library
Initially points to all Ciao library paths. See library_directory/1.
engine
The path of the Ciao engine builtins.
.
The current path ('.').

The predicate is multifile.

The predicate is of type dynamic.

PREDICATE: library_directory/1:

library_directory(Path)

Path is a library path (a path represented by the path alias library). Predefined library paths in Ciao are '$CIAOLIB/lib', '$CIAOLIB/library', and '$CIAOLIB/contrib', given that $CIAOLIB is the path of the root ciao library directory. More library paths can be defined by asserting new facts (or clauses) of this predicate.

The predicate is multifile.

The predicate is of type dynamic.


Go to the first, previous, next, last section, table of contents.