
close(+Stream)

   Closes the stream specified by Stream.  

Arguments
   Stream              Stream handle or alias (atom)

Type
   Stream I/O

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 --- Stream is not instantiated.
     5 --- Stream is instantiated, but not to a stream handle or an atom.
    40 --- Stream is a handle that was already closed.
   170 --- Operating system could not close the stream.
   193 --- Stream is an illegal stream specification.
   196 --- 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
   close / 2, open / 3, open / 4, set_stream / 2
