close(+Stream)

Stream

Stream handle or alias (atom)

Description

Used to explicitly close a stream. Stream can be a symbolic stream name or a stream handle.

When Stream is a stream handle, the stream is closed, but any symbolic stream aliases associated with it still refer to this (now closed) stream, until they are either closed as well, or redirected to other streams.

When Stream is a symbolic stream name, the stream gets closed (unless it was already closed using a different alias or handle), and the alias gets detached and no longer refers to a stream.

If a stream has several aliases, every alias should be closed explicitly. If a stream has handles and aliases, then only the aliases need to be closed. If a stream has only handles, it is enough to close it using one of the handles.

If a stream has only handles, it is actually not absolutely necessary to close it at all: it will be closed automatically when the handles become inaccessible, e.g. due to failure or garbage collection of the handles. In particular, it is NOT necessary to take precautions for closing a stream in case of failure or abort across the stream opening.

The predefined stream aliases and the standard streams always remain open. Trying to close them has the following effect:

Current streams (input, output, warning_output, log_output, error):

the stream is closed (unless it was directed to a standard stream), and the alias is reset to the corresponding user_XXX alias

Default streams (user_input, user_output, user_error):

the stream is closed (unless it was directed to a standard stream), and the alias is reset to the corresponding stdXXX alias

Standard streams (stdin, stdout, stderr, null):

no effect

Modes and Determinism

• close(+) is det

Exceptions

(4) instantiation fault

Stream is not instantiated.

(5) type error

Stream is instantiated, but not to a stream handle or an atom.

(40) stale object handle

Stream is a handle that was already closed.

(170) system interface error

Operating system could not close the stream.

(193) illegal stream specification

Stream is an illegal stream specification.

(196) trying to modify a system stream

Trying to close a system stream (handled by default).

Examples

      % Open and close using a handle
      ?- open(file1,write,S), write(S,hello), close(S).
      Yes (0.00s cpu)

      % Open and close using an alias name
      ?- open(file1,write,a), write(a,hello), close(a).
      Yes (0.00s cpu)

      % WRONG: Closing the stream via handle, but not closing the alias:
      % (alias refers to a closed stream)
      ?- open(file1,write,S), set_stream(a,S), write(a,hello),
         close(S), write(a, world).
      illegal stream mode in write(a, world)
      Abort

      % OK: Closing the stream via its alias only:
      ?- open(file1,write,S), set_stream(a,S), write(a,hello),
         close(a), write(a, world).
      illegal stream specification in write(a, world)
      Abort

      % OK: handle-only stream gets auto-closed on abort
      ?- open(file1, read, S), abort.
      Abort

      % OK: handle-only stream gets auto-closed on failure
      ?- open(file1, read, S), fail.
      No (0.00s cpu)

      % OK: handle-only stream gets auto-closed on abort (and file deleted)
      ?- open(file2, write, S, [delete_file(when_lost)]), abort.
      Abort

      % OK: handle-only stream gets auto-closed on failure (and file deleted)
      ?- open(file2, write, S, [delete_file(when_lost)]), fail.
      No (0.00s cpu)


Error:
      close(Stream).         (Error 4).
      close("4").            (Error 5).
      close(S),close(S).     (Error 40).
      close(10).             (Error 193).
      close(nostream).       (Error 193).
      close(output).         (Error 196).

See Also