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

SourceSink

Atom, string or structure.

Mode

One of the atoms read, write, update, append.

Stream

Atom or variable.

Description

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

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 of open/4, 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.

Lifetime of Streams

Modes and Determinism

• open(++, +, -) is det
• open(++, +, +) is det

Exceptions

(4) instantiation fault

File or Mode is not instantiated.

(5) type error

File is not an atom, string or structure.

(5) type error

Mode is not an atom.

(5) type error

Stream is not an atom or a variable.

(170) system interface error

The operating system cannot open the file.

(192) illegal stream mode

Mode is an atom, but is not a valid mode.

Examples

    ?- open(file1, write, S), write(S, foo), close(S).
    S = $&(stream,"")
    yes.

    ?- open(file1, update, S), read(S,X), write(S,bar), close(S).
    X = foo
    S = $&(stream,"")
    yes.

    ?- open(file1, append, S), write(S, baz), close(S).
    S = $&(stream,"")
    yes.

    ?- open(file1, read, mystr), read(mystr,X), close(mystr).
    X = foobarbaz
    yes.


    ?- open(string("foo"), update, S),
                 read(S,X), write(S,bar),
                 get_stream_info(S, name, Contents), close(S).
    X = foo
    Contents = "foobar"
    yes.

    ?- open(queue(""), update, S),
                 write(S, hello), read(S, X), close(S).
    X = hello
    yes.

    ?- event_create(writeln(my_event_handler), Event),
                 open(queue(""), write, S, [event(Event)]),
                 write(S, hello).
    my_event_handler
    S = $&(stream,7)
    yes.

Error:
       open(Var,update,s).      (Error 4).
       open(file1,Mode,s).      (Error 4).
       open(2,update,s).        (Error 5).
       open(file1,"str",s).     (Error 5).
       open(file1,update,9).    (Error 5).
       open(nonex,read,s).      (Error 170). % no such file
       open(file1,atom,s).      (Error 192). % no such mode

See Also