6.1.2 ISO Streams

open(+SourceSink,+Mode,-Stream)

ISO
open/1 creates a stream for the source or sink designated in SourceSink, and binds Stream to a structure representing that stream.

• If SourceSink is an atom, or the term file(File) where File is an atom, the stream is a file stream. In this case Mode can be
  • read to create an input stream. In Windows, whether the file is textual or binary is determined by the file's properties.
  • write to create an output stream. Any previous file with a similar path is removed and a (textual) file is created which becomes a record of the output stream.
  • write_binary to create an output stream. Any previous file with a similar path is removed and a file is created which becomes a record of the output stream. The file created is binary in Windows, while in UNIX write_binary has the same effect as write.
  • append to create an output stream. In this case the output stream is appended to the contents of the file, if it exists, and otherwise a new file is created for (textual) output
  • append_binary to create an output stream. In this case the output stream is appended to the contents of the file, if it exists, and otherwise a new file is created for (binary) output
• If SourceSink is the term atom(Atom) where Atom is an atom, the stream is an atom stream. In this case Mode currently can only be read. This stream class, which reads from interned atoms, is analogous to C's sscanf() function.
• If SourceSink is the term pipe(FIleDescriptor) where FileDescriptor is an integer, then a pipe stream is opened in the mode for FileDescriptor.

ISO Compatability Note: This predicate extends the ISO definition of open/3 to include strings and pipes as well as the file modes write_binary and append_binary.

Error Cases

• SourceSink or Mode is not instantiated
  • instantiation_error
• Mode is not a valid I/O mode
  • domain_error(io_mode,Mode)
• SourceSink is a file and cannot be opened, or opened in the desired mode
  • permission_error(open,file,SourceSink)

open(+File,+Mode,-Stream,+Options)

ISO
open/4 behaves as does open/3, but allows a list of options to be given. The option alias(A) allows the stream to be aliased to an atom A. The ISO option type(T) has no effect on file streams in UNIX, which are always textual, but in Windows if T is binary a binary file is opened. The ISO option reposition(Boolean) currently has no effect on streams, because whether or not the stream is repositionable or not depends on the stream class. And finally, the ISO option eof_action(Action) currently has no effect on file streams. Appropriate warnings are given if an option list includes these option types.

Error Cases Error cases are the same as open/3 but with the addition:

• Option_list contains an option O that is not a stream option.
  • domain_error(stream_option,O)

close(+Stream_or_alias,+OptionsList)

ISO
close/2 closes the stream or alias Stream_or_alias. OptionsList allows the user to declare whether a permission error will be raised in XSB upon a resource or system error from the closing function (e.g. fclose() or other system function). If OptionsList is non-empty and contains only terms unifying with force(true) then such an error will be ignored (possibly leading to unacknowledged loss of data). Otherwise, a permission error is thrown if fclose() or other system function returns an error condition. If the stream class of Stream_or_alias is an atom, then the only action taken is to close the stream itself - the interned atom itself is not affected.

Error Cases

• Stream_or_alias is not instantiated to a stream term or alias.
  • domain_error(stream_or_alias,Stream_or_alias)
• Stream_or_alias is not associated with an open stream
  • existence_error(stream,Stream_or_alias)
• OptionList contains an option O that is not a closing option.
  • domain_error(close_option,O)
• OptionList contains conflicting options
  • domain_error(close_option,OptionList)
• Closing the stream produces an error (and OptionsList is a non-empty list containing terms of the form force(true)).
  • permission_error(close,file,Stream_or_alias)

close(+Stream_or_alias)

ISO
close/1 closes the stream or alias Stream_or_alias.
Behaves as close(Stream_or_alias,[force(false)]).

set_input(+Stream_or_alias)

ISO
Makes file Stream_or_alias the current input stream.

Error Cases

• Stream_or_alias is not instantiated to a stream term or alias.
  • domain_error(stream_or_alias,Stream_or_alias)
• Stream_or_alias is not an open input stream
  • existence_error(stream,Stream_or_alias)

set_output(+Stream_or_alias)

ISO
Makes file Stream_or_alias the current output stream.

Error Cases

• Stream_or_alias is not instantiated to a stream term or alias.
  • domain_error(stream_or_alias,Stream_or_alias)
• Stream_or_alias is not associated with an open output stream
  • existence_error(stream,Stream_or_alias)

stream_property(?Stream,?Property)

ISO
This predicate backtracks through the various stream properties that unify with Property for the stream Stream. Currently, the following properties are defined.

• stream_class(C) gives the stream class for a file: i.e. file, atom, console or pipe.

• file_name(F) is a property of Stream, if Stream is a file stream and F is the file name associate with Stream. The full operating system path is used.
• type(T) is a property of Stream, if Stream is a file stream and T is the file type of Stream: text or binary.
• mode(M) is a property of Stream, if M represents the I/O mode with which Stream was opened: i.e. read, write, append, write_binary, etc., as appropriate for the class of Stream.
• alias(A) is a property of Stream, if Stream was opened with alias A.
• input is a property of Stream, if Stream was opened in the I/O mode: read.
• output is a property of Stream, if Stream was opened in the I/O mode: write, append, write_binary, or append_binary.
• reposition(Bool) is true, if Stream is repositionable, and false otherwise.
• end_of_stream(E) returns at if the end of stream condition for Stream is true, and not otherwise.
• position(Pos) returns the current position of the stream as determined by fseek or the byte-offset of the current stream within an atom. In either case, if an end-of-stream condition occurs, the token end_of_file is returned.

• eof_action(Action) is reposition if the stream class is console, eof_code if the stream class is file, and error is the stream class is pipe or atom.

flush_output(+Stream_or_alias)

ISO
Any buffered data in Stream_or_alias gets flushed. If Stream is not buffered (i.e. if it is of class atom), no action is taken.

Error Cases

• Stream is not instantiated to a stream term or alias.
  • domain_error(stream,Stream)
• Stream is not associated with an open output stream
  • existence_error(stream,Stream)
• Flushing (i.e. fflush()) returns an error.
  • permission_error(flush,stream,Stream)

flush_output

ISO
Any buffered data in the current output stream gets flushed.

set_stream_position(+Stream_or_alias,+Position)

ISO
If the stream associated with Stream_or_alias is repositionable (i.e. is a file or atom), sets the stream position indicator for the next input or output operation. Position is a positive integer, taken to be the number of bytes the stream is to be placed from the origin.

Error Cases

• Stream_or_alias is not instantiated to a stream term or alias.
  • domain_error(stream_or_alias,Stream_or_alias)
• Position is not instantiated to a positive integer.
  • domain_error(stream_position,Position)
• Stream_or_alias is not associated with an open stream
  • existence_error(stream,Stream_or_alias)
• Stream_or_alias is not repositionable, or repositioning returns an error.
  • permission_error(resposition,stream,Stream_or_alias)

at_end_of_stream(+Stream_or_alias)

ISO
Succeeds if Stream_or_alias has position at or past the end of stream.

Error Cases

• Stream_or_alias is not instantiated to a stream term or alias
  • domain_error(stream,Stream_or_alias)
• Stream_or_alias is not an open stream
  • existence_error(stream,Stream_or_alias)

at_end_of_stream

ISO
Acts as at_end_of_stream/1 but using the current input stream.