
open(++SourceSink, +Mode, ?Stream, ++Options)

   Opens the I/O source or sink SourceSink in mode Mode and associates it
with the stream identifier Stream.



Arguments
   SourceSink          Atom, string or structure.
   Mode                One of the atoms read, write, update, append.
   Stream              Atom or variable.
   Options             List.

Type
   Stream I/O

Description
   This predicate opens an ECLiPSe I/O stream.


   The most common use is for opening files. In this case, SourceSink
   is a file name (atom or string).


   Mode is one of the following



    read         open for reading
    write        open for writing
    update       open for reading and writing
    append       open for writing at the end

   A file must already exist if it is to be opened in read mode.  A file
   opened in append mode is opened in write mode at the end of the file.
   If an existing file is opened in write mode, it is truncated to zero
   size, i.e. its previous content is lost.


   If Stream is a variable, it will be instantiated to a system-generated
   stream handle.  This handle can subsequently be used to identify the
   stream.  If Stream is an atom, then this atom will be used as a symbolic
   alias name for the stream (like with the alias(Name) option, or
   set_stream/2).  The use of handles should be preferred.


   If SourceSink is of the form string(InitialString), then a so-called
   string stream is opened.  A string stream is basically an in-memory
   file and its initial contents is the string InitialString.
   A string stream can be used like any other stream, i.e. it is possible
   to read, write and seek like on a true file.
   The current contents of a string stream can at any time be retrieved
   as a whole using get_stream_info(Stream, name, Contents).


   If SourceSink is of the form queue(InitialString), then a queue
   stream is opened. It behaves like a string that can be written at the
   end and read from the beginning.  Seeking is not allowed on queues.
   The current contents of a queue can at any time be retrieved as a
   whole using get_stream_info(Stream, name, Contents). Queues are
   considered to be at end-of-file while they are empty. 
   Queues can be configured to raise an event every time something
   is written to the previously empty queue (see open/4).


   If SourceSink is of the form fd(Integer), then the stream in opened
   onto an existing operating system file descriptor.


   Options is a list of zero or more of the following stream options:

alias(Name)
    Make the stream known under an alternative name.  Name is an atom,
    and must not already be a stream alias. See also set_stream/2.

compress(OnOff)
    a hint for output operations (e.g. write_exdr/2) to use a more
    compact output format (output streams only). OnOff is one of the
    atoms on or off. The default is on (for files, pipes and sockets)
    or off (for queues and string streams).

delete_file(When)
    This option applies to file streams only: the value 'when_closed'
    causes the associated file to be deleted as soon as the stream is closed
    (whether implicitly or explicitly).  The value 'when_lost' causes
    the associated file to be deleted only when the stream is implicitly
    closed, either because of failure across the opening, or because
    its handles were garbage collected.  The default is 'off'.

encoding(Code)
    The character encoding used on the stream.  In version 6.1, the
    only allowed values are: octet, ascii, and iso_latin_1 (the default).

end_of_line(CrLf)
    This option affects only write-streams and determines which
    end-of-line character sequence is written by predicates like nl/1,
    writeln/1 and printf/3.  Possible values are the atoms lf and
    crlf.  The default for string and queue streams is lf, for other
    streams it is operating-system dependent.

eof_action(Action)
    Controls how end-of-file is handled on this stream.  Possible values
    are: 'eof_code' (return an code appropriate to the input predicate used
    - this is the default), 'error' (raise an error), 'reset' (like eof_code,
    but allow further read attempts on the stream).

event(Name)
    This option configures a read-queue stream or a socket stream to raise
    the given event whenever data arrives on the previously empty stream.
    This option is intended for queue streams in embedded applications
    of ECLiPSe, or for socket streams in remote connection setups.  The
    event handler should consume all data that is available on the stream.
    Name must be an atom or an event handle.

flush(Where)
    This option affects only write-streams and allows to configure a
    stream to automatically flush after every line written.  Where is
    one of the atoms end_of_line (flush automatically after every
    line) or flush (require explicit flushing).  The default setting
    is flush, except for tty streams where the default is end_of_line.

macro_expansion(OnOff)
    Input streams only. Specifies whether term-macros (see macro/3) will
    be expanded when reading from this stream using read/2, read_term/3 etc.
    OnOff is one of the atoms on or off, the default is on.

output_options(OptionList)
    Write-streams only. Specifies the default output options that will be
    used when printing terms onto this stream, e.g. using write/2.
    The format of OptionList is the same as the one accepted by the
    write_term/2,3 predicates.
    Note that certain output predicates can override these default
    settings, e.g. writeq/2, write_term/3, printf/3, etc.

reposition(Bool)
    The option reposition(true) verifies that the stream can be repositioned,
    i.e. that seek/2 can be used on it.  Otherwise an error is raised.
    The option reposition(false) has no effect.

yield(OnOff)
    This option is intended for queue streams in embedded applications
    of ECLiPSe.  It configures the stream to yield control to the host
    program whenever a read-queue reaches end-of-file or a write-queue
    gets flushed.  See the Embedding Manual for more details.  OnOff
    is one of the atoms on or off.



Lifetime of Streams
   A stream lives until it is closed.  Streams that are only referenced by
   handle are closed automatically, either on failure across the open/3,4
   predicate, or after all copies of their handle become unused and garbage
   collected.  This means that no extra precautions have to be taken to
   ensure that streams are closed on failure or when aborting.
   Handle-streams can optionally be closed explicitly if their lifetime
   is statically known in the program.  Streams that have aliases cannot
   be closed automatically: all aliases must be closed explicitly.

   NOTE: Stream handles are not normal Prolog terms!  They can not be
   assembled, decomposed, or occur in Prolog text.



Modes and Determinism
   open(++, +, -, ++) is det
   open(++, +, +, ++) is det

Exceptions
     4 --- File or Mode is not instantiated.
     5 --- File is not an atom, string or structure.
     5 --- Mode is not an atom.
     5 --- Stream is not an atom or a variable.
   170 --- The operating system cannot open the file.
   192 --- Mode is an atom, but is not a valid mode.

Examples
   
    See open/3.





See Also
   open / 3, existing_file / 4, close / 1, close / 2, set_stream_property / 3, at / 2, at_eof / 1, current_stream / 1, get_stream_info / 3, seek / 2, set_stream / 2, stream_select / 3, stream_truncate / 1, flush / 1, write_term / 2, write_term / 3
