/usr/lib/swi-prolog/doc/Manual/IO.html

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">

<HTML>
<HEAD>
<TITLE>SWI-Prolog 5.11.18 Reference Manual: Section 4.15</TITLE><LINK REL=home HREF="index.html">
<LINK REL=contents HREF="Contents.html">
<LINK REL=index HREF="DocIndex.html">
<LINK REL=summary HREF="summary.html">
<LINK REL=previous HREF="examineprog.html">
<LINK REL=next HREF="streamstat.html">
<STYLE type="text/css">
/* Style sheet for SWI-Prolog latex2html
*/

dd.defbody
{ margin-bottom: 1em;
}

dt.pubdef
{ background-color: #c5e1ff;
}

dt.multidef
{ background-color: #c8ffc7;
}

.bib dd
{ margin-bottom: 1em;
}

.bib dt
{ float: left;
margin-right: 1.3ex;
}

pre.code
{ margin-left: 1.5em;
margin-right: 1.5em;
border: 1px dotted;
padding-top: 5px;
padding-left: 5px;
padding-bottom: 5px;
background-color: #f8f8f8;
}

div.navigate
{ text-align: center;
background-color: #f0f0f0;
border: 1px dotted;
padding: 5px;
}

div.title
{ text-align: center;
padding-bottom: 1em;
font-size: 200%;
font-weight: bold;
}

div.author
{ text-align: center;
font-style: italic;
}

div.abstract
{ margin-top: 2em;
background-color: #f0f0f0;
border: 1px dotted;
padding: 5px;
margin-left: 10%; margin-right:10%;
}

div.abstract-title
{ text-align: center;
padding: 5px;
font-size: 120%;
font-weight: bold;
}

div.toc-h1
{ font-size: 200%;
font-weight: bold;
}

div.toc-h2
{ font-size: 120%;
font-weight: bold;
margin-left: 2em;
}

div.toc-h3
{ font-size: 100%;
font-weight: bold;
margin-left: 4em;
}

div.toc-h4
{ font-size: 100%;
margin-left: 6em;
}

span.sec-nr
{
}

span.sec-title
{
}

span.pred-ext
{ font-weight: bold;
}

span.pred-tag
{ float: right;
padding-top: 0.2em;
font-size: 80%;
font-style: italic;
color: #202020;
}

/* Footnotes */

sup.fn { color: blue; text-decoration: underline; }
span.fn-text { display: none; }
sup.fn span {display: none;}
sup:hover span
{ display: block !important;
position: absolute; top: auto; left: auto; width: 80%;
color: #000; background: white;
border: 2px solid;
padding: 5px; margin: 10px; z-index: 100;
font-size: smaller;
}
</STYLE>
</HEAD>
<BODY BGCOLOR="white">
<DIV class="navigate"><A class="nav" href="index.html"><IMG SRC="home.gif" BORDER=0 ALT="Home"></A>
<A class="nav" href="Contents.html"><IMG SRC="index.gif" BORDER=0 ALT="Contents"></A>
<A class="nav" href="DocIndex.html"><IMG SRC="yellow_pages.gif" BORDER=0 ALT="Index"></A>
<A class="nav" href="summary.html"><IMG SRC="info.gif" BORDER=0 ALT="Summary"></A>
<A class="nav" href="examineprog.html"><IMG SRC="prev.gif" BORDER=0 ALT="Previous"></A>
<A class="nav" href="streamstat.html"><IMG SRC="next.gif" BORDER=0 ALT="Next"></A>
</DIV>

<H2><A NAME="sec:4.15"><SPAN class="sec-nr">4.15</SPAN> <SPAN class="sec-title">Input 
and output</SPAN></A></H2>

<A NAME="sec:IO"></A>

<P>SWI-Prolog provides two different packages for input and output. The 
native I/O system is based on the ISO standard predicates <A NAME="idx:open3:717"></A><A class="pred" href="IO.html#open/3">open/3</A>,
<A NAME="idx:close1:718"></A><A class="pred" href="IO.html#close/1">close/1</A> 
and friends.<SUP class="fn">43<SPAN class="fn-text">Actually based on 
Quintus Prolog, providing this interface before the ISO standard 
existed.</SPAN></SUP> Being more widely portable and equipped with a 
clearer and more robust specification, new code is encouraged to use 
these predicates for manipulation of I/O streams.

<P><A class="sec" href="IO.html">Section 4.15.2</A> describes <A NAME="idx:tell1:719"></A><A class="pred" href="IO.html#tell/1">tell/1</A>, <A NAME="idx:see1:720"></A><A class="pred" href="IO.html#see/1">see/1</A> 
and friends, providing I/O in the spirit of the traditional Edinburgh 
standard. These predicates are layered on top of the ISO predicates. 
Both packages are fully integrated; the user may switch freely between 
them.

<H3><A NAME="sec:4.15.1"><SPAN class="sec-nr">4.15.1</SPAN> <SPAN class="sec-title">ISO 
Input and Output Streams</SPAN></A></H3>

<A NAME="sec:isoIO"></A>

<P>The predicates described in this section provide ISO compliant I/O, 
where streams are explicitly created using the predicate <A NAME="idx:open3:721"></A><A class="pred" href="IO.html#open/3">open/3</A>. 
The resulting stream identifier is then passed as a parameter to the 
reading and writing predicates to specify the source or destination of 
the data.

<P>This schema is not vulnerable to filename and stream ambiguities as 
well as changes to the working directory. On the other hand, using the 
notion of current-I/O simplifies reusability of code without the need to 
pass arguments around. E.g., see <A NAME="idx:withoutputto2:722"></A><A class="pred" href="IO.html#with_output_to/2">with_output_to/2</A>.

<P>SWI-Prolog streams are, compatible to the ISO standard, either input 
or output streams. To accomodate portability to other systems, a pair of 
streams can be packed into a <EM>stream-pair</EM>. See
<A NAME="idx:streampair3:723"></A><A class="pred" href="IO.html#stream_pair/3">stream_pair/3</A> 
for details.

<P>SWI-Prolog stream-handles are unique symbols that have no syntactical 
representation. They are written as <CODE>\bnfmeta{stream}(hex-number)</CODE>, 
which is not valid input for <A NAME="idx:read1:724"></A><A class="pred" href="termrw.html#read/1">read/1</A>. 
They are realised using a <EM>blob</EM> of type <CODE>stream</CODE> (see <A NAME="idx:blob2:725"></A><A class="pred" href="typetest.html#blob/2">blob/2</A> 
and <A class="sec" href="foreigninclude.html">section 9.4.7</A>).

<DL class="latex">
<DT class="pubdef"><span class="pred-tag">[ISO]</span><A NAME="open/4"><STRONG>open</STRONG>(<VAR>+SrcDest, 
+Mode, -Stream, +Options</VAR>)</A></DT>
<DD class="defbody">
ISO compliant predicate to open a stream. <VAR>SrcDest</VAR> is either 
an atom, specifying a file, or a term `<CODE>pipe(<VAR>Command</VAR>)</CODE>', 
like <A NAME="idx:see1:726"></A><A class="pred" href="IO.html#see/1">see/1</A> 
and <A NAME="idx:tell1:727"></A><A class="pred" href="IO.html#tell/1">tell/1</A>. <VAR>Mode</VAR> 
is one of <CODE>read</CODE>, <CODE>write</CODE>,
<CODE>append</CODE> or <CODE>update</CODE>. Mode <CODE>append</CODE> 
opens the file for writing, positioning the file-pointer at the end. 
Mode <CODE>update</CODE> opens the file for writing, positioning the 
file-pointer at the beginning of the file without truncating the file. <VAR>Stream</VAR> 
is either a variable, in which case it is bound to an integer 
identifying the stream, or an atom, in which case this atom will be the 
stream identifier.<SUP class="fn">44<SPAN class="fn-text">New code 
should use the <CODE>alias(Alias)</CODE> option for compatibility with 
the ISO standard</SPAN></SUP> The <VAR>Options</VAR> list can contain 
the following options:

<DL class="latex">
<DT><STRONG>type</STRONG>(<VAR>Type</VAR>)</DT>
<DD class="defbody">
Using type <CODE>text</CODE> (default), Prolog will write a text-file in 
an operating-system compatible way. Using type <CODE>binary</CODE> the 
bytes will be read or written without any translation. See also the 
option <CODE>encoding</CODE>.</DD>
<DT><STRONG>alias</STRONG>(<VAR>Atom</VAR>)</DT>
<DD class="defbody">
Gives the stream a name. Below is an example. Be careful with this 
option as stream-names are global. See also <A NAME="idx:setstream2:728"></A><A class="pred" href="IO.html#set_stream/2">set_stream/2</A>.

<PRE class="code">
?- open(data, read, Fd, [alias(input)]).

        ...,
        read(input, Term),
        ...
</PRE>

</DD>
<DT><STRONG>encoding</STRONG>(<VAR>Encoding</VAR>)</DT>
<DD class="defbody">
Define the encoding used for reading and writing text to this stream. 
The default encoding for type <CODE>text</CODE> is derived from the 
Prolog flag <A class="flag" href="flags.html#flag:encoding">encoding</A>. 
For <CODE>binary</CODE> streams the default encoding is <CODE>octet</CODE>. 
For details on encoding issues, see <A class="sec" href="widechars.html">section 
2.17.1</A>.</DD>
<DT><STRONG>bom</STRONG>(<VAR>Bool</VAR>)</DT>
<DD class="defbody">
Check for a BOM (<EM>Byte Order Marker</EM>) or write one. If omitted, 
the default is <CODE>true</CODE> for mode <CODE>read</CODE> and
<CODE>false</CODE> for mode <CODE>write</CODE>. See also <A NAME="idx:streamproperty2:729"></A><A class="pred" href="IO.html#stream_property/2">stream_property/2</A> 
and especially <A class="sec" href="widechars.html">section 2.17.1.1</A> 
for a discussion on this feature.</DD>
<DT><STRONG>eof_action</STRONG>(<VAR>Action</VAR>)</DT>
<DD class="defbody">
Defines what happens if the end of the input stream is reached. Action
<CODE>eof_code</CODE> makes <A NAME="idx:get01:730"></A><A class="pred" href="chario.html#get0/1">get0/1</A> 
and friends return -1 and <A NAME="idx:read1:731"></A><A class="pred" href="termrw.html#read/1">read/1</A> 
and friends return the atom <CODE>end_of_file</CODE>. Repetitive reading 
keeps yielding the same result. Action <CODE>error</CODE> is like <CODE>eof_code</CODE>, 
but repetitive reading will raise an error. With action <CODE>reset</CODE>, 
Prolog will examine the file again and return more data if the file has 
grown.</DD>
<DT><STRONG>buffer</STRONG>(<VAR>Buffering</VAR>)</DT>
<DD class="defbody">
Defines output buffering. The atom <CODE>full</CODE> (default) defines 
full buffering, <CODE>line</CODE> buffering by line, and <CODE>false</CODE> 
implies the stream is fully unbuffered. Smaller buffering is useful if 
another process or the user is waiting for the output as it is being 
produced. See also <A NAME="idx:flushoutput01:732"></A><A class="pred" href="chario.html#flush_output/0">flush_output/[0,1]</A>. 
This option is not an ISO option.</DD>
<DT><STRONG>close_on_abort</STRONG>(<VAR>Bool</VAR>)</DT>
<DD class="defbody">
If <CODE>true</CODE> (default), the stream is closed on an abort (see
<A NAME="idx:abort0:733"></A><A class="pred" href="toplevel.html#abort/0">abort/0</A>). 
If <CODE>false</CODE>, the stream is not closed. If it is an output 
stream, it will be flushed however. Useful for logfiles and if the 
stream is associated to a process (using the <CODE>pipe/1</CODE> 
construct).</DD>
<DT><STRONG>lock</STRONG>(<VAR>LockingMode</VAR>)</DT>
<DD class="defbody">
Try to obtain a lock on the open file. Default is <CODE>none</CODE>, 
which does not lock the file. The value <CODE>read</CODE> or <CODE>shared</CODE> 
means other processes may read the file, but not write it. The value
<CODE>write</CODE> or <CODE>exclusive</CODE> means no other process may 
read or write the file.

<P>Locks are acquired through the POSIX function fcntl() using the 
command
<CODE>F_SETLKW</CODE>, which makes a blocked call wait for the lock to 
be released. Please note that fcntl() locks are <EM>advisory</EM> and 
therefore only other applications using the same advisory locks honour 
your lock. As there are many issues around locking in Unix, especially 
related to NFS (network file system), please study the fcntl() manual 
page before trusting your locks!

<P>The <CODE>lock</CODE> option is a SWI-Prolog extension.</DD>
<DT><STRONG>wait</STRONG>(<VAR>Bool</VAR>)</DT>
<DD class="defbody">
This option can be combined with the <CODE>lock</CODE> option. If
<CODE>false</CODE> (default <CODE>true</CODE>), the open call returns 
immediately with an exception if the file is locked. The exception has 
the format
<CODE>permission_error(lock, source_sink, SrcDest)</CODE>.
</DD>
</DL>

<P>The option <CODE>reposition</CODE> is not supported in SWI-Prolog. 
All streams connected to a file may be repositioned.</DD>
<DT class="pubdef"><span class="pred-tag">[ISO]</span><A NAME="open/3"><STRONG>open</STRONG>(<VAR>+SrcDest, 
+Mode, ?Stream</VAR>)</A></DT>
<DD class="defbody">
Equivalent to <A NAME="idx:open4:734"></A><A class="pred" href="IO.html#open/4">open/4</A> 
with an empty option-list.</DD>
<DT class="pubdef"><A NAME="open_null_stream/1"><STRONG>open_null_stream</STRONG>(<VAR>?Stream</VAR>)</A></DT>
<DD class="defbody">
Open an output stream that produces no output. All counting functions 
are enabled on such a stream. It can be used to discard output (like 
Unix <CODE>/dev/null</CODE>) or exploit the counting properties. The 
initial encoding of <VAR>Stream</VAR> is <CODE>utf8</CODE>, enabling 
arbitrary Unicode output. The encoding can be changed to determine 
byte-counts of the output in a particular encoding or validate output is 
possible in a particular encoding. For example, the code below 
determines the number of characters emitted when writing <VAR>Term</VAR>.

<PRE class="code">
write_length(Term, Len) :-
        open_null_stream(Out),
        write(Out, Term),
        character_count(Out, Len0),
        close(Out),
        Len = Len0.
</PRE>

</DD>
<DT class="pubdef"><span class="pred-tag">[ISO]</span><A NAME="close/1"><STRONG>close</STRONG>(<VAR>+Stream</VAR>)</A></DT>
<DD class="defbody">
Close the specified stream. If <VAR>Stream</VAR> is not open, an 
existence error is raised. However, closing a stream multiple times may 
crash Prolog. This is particularly true for multi-threaded applications.

<P>If the closed stream is the current input or output stream, the 
terminal is made the current input or output.</DD>
<DT class="pubdef"><span class="pred-tag">[ISO]</span><A NAME="close/2"><STRONG>close</STRONG>(<VAR>+Stream, 
+Options</VAR>)</A></DT>
<DD class="defbody">
Provides <CODE>close(Stream, [force(true)])</CODE> as the only option. 
Called this way, any resource error (such as write-errors while flushing 
the output buffer) are ignored.</DD>
<DT class="pubdef"><span class="pred-tag">[ISO]</span><A NAME="stream_property/2"><STRONG>stream_property</STRONG>(<VAR>?Stream, 
?StreamProperty</VAR>)</A></DT>
<DD class="defbody">
ISO compatible predicate for querying status of open I/O streams.
<VAR>StreamProperty</VAR> is one of:

<DL class="latex">
<DT><STRONG>alias</STRONG>(<VAR>Atom</VAR>)</DT>
<DD class="defbody">
If <VAR>Atom</VAR> is bound, test of the stream has the specified alias. 
Otherwise unify <VAR>Atom</VAR> with the first alias of the stream.<SUP class="fn">bug<SPAN class="fn-text">Backtracking 
does not give other aliases.</SPAN></SUP></DD>
<DT><STRONG>buffer</STRONG>(<VAR>Buffering</VAR>)</DT>
<DD class="defbody">
SWI-Prolog extension to query the buffering mode of this stream.
<VAR>Buffering</VAR> is one of <CODE>full</CODE>, <CODE>line</CODE> or <CODE>false</CODE>. 
See also <A NAME="idx:open4:735"></A><A class="pred" href="IO.html#open/4">open/4</A>.</DD>
<DT><STRONG>buffer_size</STRONG>(<VAR>Integer</VAR>)</DT>
<DD class="defbody">
SWI-Prolog extension to query the size of the I/O buffer associated to a 
stream in bytes. Fails of the stream is not buffered.</DD>
<DT><STRONG>bom</STRONG>(<VAR>Bool</VAR>)</DT>
<DD class="defbody">
If present and <CODE>true</CODE>, a BOM (<EM>Byte Order Mark</EM>) was 
detected while opening the file for reading or a BOM was written while 
opening the stream. See <A class="sec" href="widechars.html">section 
2.17.1.1</A> for details.</DD>
<DT><STRONG>close_on_abort</STRONG>(<VAR>Bool</VAR>)</DT>
<DD class="defbody">
Determine whether or not the stream is closed by <A NAME="idx:abort0:736"></A><A class="pred" href="toplevel.html#abort/0">abort/0</A>. 
By default streams are closed.</DD>
<DT><STRONG>close_on_exec</STRONG>(<VAR>Bool</VAR>)</DT>
<DD class="defbody">
Determine whether or not the stream is closed when executing a new 
process (exec() in Unix, CreateProcess() in Windows). Default is to 
close streams. This maps to fcntl() <CODE>F_SETFD</CODE> using the flag
<CODE>FD_CLOEXEC</CODE> on Unix and (negated) <CODE>HANDLE_FLAG_INHERIT</CODE> 
on Windows.</DD>
<DT><STRONG>encoding</STRONG>(<VAR>Encoding</VAR>)</DT>
<DD class="defbody">
Query the encoding used for text. See <A class="sec" href="widechars.html">section 
2.17.1</A> for an overview of wide character and encoding issues in 
SWI-Prolog.</DD>
<DT><STRONG>end_of_stream</STRONG>(<VAR>E</VAR>)</DT>
<DD class="defbody">
If <VAR>Stream</VAR> is an input stream, unify <VAR>E</VAR> with one of 
the atoms <CODE>not</CODE>, <CODE>at</CODE> or <CODE>past</CODE>. See 
also
<A NAME="idx:atendofstream01:737"></A><A class="pred" href="chario.html#at_end_of_stream/0">at_end_of_stream/[0,1]</A>.</DD>
<DT><STRONG>eof_action</STRONG>(<VAR>A</VAR>)</DT>
<DD class="defbody">
Unify <VAR>A</VAR> with one of <CODE>eof_code</CODE>, <CODE>reset</CODE> 
or
<CODE>error</CODE>. See <A NAME="idx:open4:738"></A><A class="pred" href="IO.html#open/4">open/4</A> 
for details.</DD>
<DT><STRONG>file_name</STRONG>(<VAR>Atom</VAR>)</DT>
<DD class="defbody">
If <VAR>Stream</VAR> is associated to a file, unify <VAR>Atom</VAR> to 
the name of this file.</DD>
<DT><STRONG>file_no</STRONG>(<VAR>Integer</VAR>)</DT>
<DD class="defbody">
If the stream is associated with a POSIX file-descriptor, unify
<VAR>Integer</VAR> with the descriptor number. SWI-Prolog extension used 
primarily for integration with foreign code. See also Sfileno() from
<CODE>SWI-Stream.h</CODE>.</DD>
<DT><STRONG>input</STRONG></DT>
<DD class="defbody">
True if <VAR>Stream</VAR> has mode <CODE>read</CODE>.</DD>
<DT><STRONG>mode</STRONG>(<VAR>IOMode</VAR>)</DT>
<DD class="defbody">
Unify <VAR>IOMode</VAR> to the mode given to <A NAME="idx:open4:739"></A><A class="pred" href="IO.html#open/4">open/4</A> 
for opening the stream. Values are: <CODE>read</CODE>, <CODE>write</CODE>, <CODE>append</CODE> 
and the SWI-Prolog extension <CODE>update</CODE>.</DD>
<DT><STRONG>newline</STRONG>(<VAR>NewlineMode</VAR>)</DT>
<DD class="defbody">
One of <CODE>posix</CODE> or <CODE>dos</CODE>. If <CODE>dos</CODE>, 
text-streams will emit <CODE>\r\n</CODE> for <CODE>\n</CODE> and discard <CODE>\r</CODE> 
from input streams. Default depends on the operating system.</DD>
<DT><STRONG>nlink</STRONG>(<VAR>-Count</VAR>)</DT>
<DD class="defbody">
Number of hard links to the file. This expresses the number of `names' 
the file has. Not supported on all operating systems and the value might 
be bogus. See the documentation of fstat() for your OS and the value
<TT>st_nlink</TT>.</DD>
<DT><STRONG>output</STRONG></DT>
<DD class="defbody">
True if <VAR>Stream</VAR> has mode <CODE>write</CODE>, <CODE>append</CODE> 
or
<CODE>update</CODE>.</DD>
<DT><STRONG>position</STRONG>(<VAR>Term</VAR>)</DT>
<DD class="defbody">
Unify <VAR>Term</VAR> with the current stream-position. A 
stream-position is an opaque term whose fields can be extracted using
<A NAME="idx:streampositiondata3:740"></A><A class="pred" href="IO.html#stream_position_data/3">stream_position_data/3</A>. 
See also <A NAME="idx:setstreamposition2:741"></A><A class="pred" href="IO.html#set_stream_position/2">set_stream_position/2</A>.</DD>
<DT><STRONG>reposition</STRONG>(<VAR>Bool</VAR>)</DT>
<DD class="defbody">
Unify <VAR>Bool</VAR> with <VAR>true</VAR> if the position of the stream 
can be set (see <A NAME="idx:seek4:742"></A><A class="pred" href="IO.html#seek/4">seek/4</A>). 
It is assumed the position can be set if the stream has a <EM>seek-function</EM> 
and is not based on a POSIX file-descriptor that is not associated to a 
regular file.</DD>
<DT><STRONG>representation_errors</STRONG>(<VAR>Mode</VAR>)</DT>
<DD class="defbody">
Determines behaviour of character output if the stream cannot represent 
a character. For example, an ISO Latin-1 stream cannot represent 
Cyrillic characters. The behaviour is one of <CODE>error</CODE> (throw 
and I/O error exception), <CODE>prolog</CODE> (write <CODE>\...\</CODE> 
escape code or <CODE>xml</CODE> (write <CODE>&amp;#...;</CODE> XML 
character entity). The initial mode is <CODE>prolog</CODE> for the user 
streams and
<CODE>error</CODE> for all other streams. See also <A class="sec" href="widechars.html">section 
2.17.1</A> and <A NAME="idx:setstream2:743"></A><A class="pred" href="IO.html#set_stream/2">set_stream/2</A>.</DD>
<DT><STRONG>timeout</STRONG>(<VAR>-Time</VAR>)</DT>
<DD class="defbody">
<VAR>Time</VAR> is the timeout currently associated with the stream. See
<A NAME="idx:setstream2:744"></A><A class="pred" href="IO.html#set_stream/2">set_stream/2</A> 
with the same option. If no timeout is specified,
<VAR>Time</VAR> is unified to the atom <CODE>infinite</CODE>.</DD>
<DT><STRONG>type</STRONG>(<VAR>T</VAR>)</DT>
<DD class="defbody">
Unify <VAR>Bool</VAR> with <CODE>text</CODE> or <CODE>binary</CODE>.</DD>
<DT><STRONG>tty</STRONG>(<VAR>Bool</VAR>)</DT>
<DD class="defbody">
This property is reported with <VAR>Bool</VAR> equals <CODE>true</CODE> 
if the stream is associated with a terminal. See also <A NAME="idx:setstream2:745"></A><A class="pred" href="IO.html#set_stream/2">set_stream/2</A>.
</DD>
</DL>

</DD>
<DT class="pubdef"><A NAME="current_stream/3"><STRONG>current_stream</STRONG>(<VAR>?Object, 
?Mode, ?Stream</VAR>)</A></DT>
<DD class="defbody">
The predicate <A NAME="idx:currentstream3:746"></A><A class="pred" href="IO.html#current_stream/3">current_stream/3</A> 
is used to access the status of a stream as well as to generate all open 
streams. <VAR>Object</VAR> is the name of the file opened if the stream 
refers to an open file, an integer file-descriptor if the stream 
encapsulates an operating-system stream or the atom <CODE>[]</CODE> if 
the stream refers to some other object.
<VAR>Mode</VAR> is one of <CODE>read</CODE> or <CODE>write</CODE>.</DD>
<DT class="pubdef"><A NAME="is_stream/1"><STRONG>is_stream</STRONG>(<VAR>+Term</VAR>)</A></DT>
<DD class="defbody">
True if <VAR>Term</VAR> is a stream name or valid stream handle. This 
predicate realises a safe test for the existence of a stream alias or 
handle.</DD>
<DT class="pubdef"><A NAME="stream_pair/3"><STRONG>stream_pair</STRONG>(<VAR>?StreamPair, 
?Read, ?Write</VAR>)</A></DT>
<DD class="defbody">
This predicate can be used in mode (-,+,+) to create a
<EM>stream-pair</EM> from an input stream and an output stream. 
Stream-pairs can be used by all I/O operations on streams, where the 
operation selects the appropriate member of the pair. The predicate
<A NAME="idx:close1:747"></A><A class="pred" href="IO.html#close/1">close/1</A> 
closes both streams of the pair. Mode (+,-,-) can be used to get access 
to the underlying streams.</DD>
<DT class="pubdef"><span class="pred-tag">[ISO]</span><A NAME="set_stream_position/2"><STRONG>set_stream_position</STRONG>(<VAR>+Stream, 
+Pos</VAR>)</A></DT>
<DD class="defbody">
Set the current position of <VAR>Stream</VAR> to <VAR>Pos</VAR>. <VAR>Pos</VAR> 
is a term as returned by <A NAME="idx:streamproperty2:748"></A><A class="pred" href="IO.html#stream_property/2">stream_property/2</A> 
using the <CODE>position(Pos)</CODE> property. See also <A NAME="idx:seek4:749"></A><A class="pred" href="IO.html#seek/4">seek/4</A>.</DD>
<DT class="pubdef"><A NAME="stream_position_data/3"><STRONG>stream_position_data</STRONG>(<VAR>?Field, 
+Position, -Data</VAR>)</A></DT>
<DD class="defbody">
Extracts information from the opaque stream position term as returned by <A NAME="idx:streamproperty2:750"></A><A class="pred" href="IO.html#stream_property/2">stream_property/2</A> 
requesting the <CODE>position(Position)</CODE> property.
<VAR>Field</VAR> is one of <CODE>line_count</CODE>, <CODE>line_position</CODE>,
<CODE>char_count</CODE> or <CODE>byte_count</CODE>. See also <A NAME="idx:linecount2:751"></A><A class="pred" href="streamstat.html#line_count/2">line_count/2</A>,
<A NAME="idx:lineposition2:752"></A><A class="pred" href="streamstat.html#line_position/2">line_position/2</A>, <A NAME="idx:charactercount2:753"></A><A class="pred" href="streamstat.html#character_count/2">character_count/2</A> 
and <A NAME="idx:bytecount2:754"></A><A class="pred" href="streamstat.html#byte_count/2">byte_count/2</A>.<SUP class="fn">45<SPAN class="fn-text">Introduced 
in version 5.6.4 after extending the position term with a byte-count. 
Compatible with SICStus Prolog.</SPAN></SUP></DD>
<DT class="pubdef"><A NAME="seek/4"><STRONG>seek</STRONG>(<VAR>+Stream, 
+Offset, +Method, -NewLocation</VAR>)</A></DT>
<DD class="defbody">
Reposition the current point of the given <VAR>Stream</VAR>. <VAR>Method</VAR> 
is one of <CODE>bof</CODE>, <CODE>current</CODE> or <CODE>eof</CODE>, 
indicating positioning relative to the start, current point or end of 
the underlying object. <VAR>NewLocation</VAR> is unified with the new 
offset, relative to the start of the stream.

<P>Positions are counted in `units'. A unit is 1 byte, except for 
text-files using 2-byte Unicode encoding (2 bytes) or <EM>wchar</EM> 
encoding (sizeof(wchar_t)). The latter guarantees comfortable 
interaction with wide-character text-objects. Otherwise, the use of
<A NAME="idx:seek4:755"></A><A class="pred" href="IO.html#seek/4">seek/4</A> 
on non-binary files (see <A NAME="idx:open4:756"></A><A class="pred" href="IO.html#open/4">open/4</A>) 
is of limited use, especially when using multi-byte text-encodings (e.g. UTF-8) 
or multi-byte newline files (e.g. DOS/Windows). On text-files, 
SWI-Prolog offers reliable backup to an old position using <A NAME="idx:streamproperty2:757"></A><A class="pred" href="IO.html#stream_property/2">stream_property/2</A> 
and
<A NAME="idx:setstreamposition2:758"></A><A class="pred" href="IO.html#set_stream_position/2">set_stream_position/2</A>. 
Skipping <VAR>N</VAR> character codes is achieved calling
<A NAME="idx:getcode2:759"></A><A class="pred" href="chario.html#get_code/2">get_code/2</A> <VAR>N</VAR> 
times or using <A NAME="idx:copystreamdata3:760"></A><A class="pred" href="chario.html#copy_stream_data/3">copy_stream_data/3</A>, 
directing the output to a null-stream (see <A NAME="idx:opennullstream1:761"></A><A class="pred" href="IO.html#open_null_stream/1">open_null_stream/1</A>). 
If the seek modifies the current location, the line number and character 
position in the line are set to 0.

<P>If the stream cannot be repositioned, a <CODE>permission_error</CODE> 
is raised. If applying the offset would result in a file-position less 
then zero, a <CODE>domain_error</CODE> is raised. Behaviour when seeking 
to positions beyond the size of the underlying object depend on the 
object and possibly the operating system. The predicate <A NAME="idx:seek4:762"></A><A class="pred" href="IO.html#seek/4">seek/4</A> 
is compatible with Quintus Prolog, though the error conditions and 
signalling is ISO compliant. See also <A NAME="idx:streamproperty2:763"></A><A class="pred" href="IO.html#stream_property/2">stream_property/2</A> 
and <A NAME="idx:setstreamposition2:764"></A><A class="pred" href="IO.html#set_stream_position/2">set_stream_position/2</A>.</DD>
<DT class="pubdef"><A NAME="set_stream/2"><STRONG>set_stream</STRONG>(<VAR>+Stream, 
+Attribute</VAR>)</A></DT>
<DD class="defbody">
Modify an attribute of an existing stream. <VAR>Attribute</VAR> 
specifies the stream property to set. See also <A NAME="idx:streamproperty2:765"></A><A class="pred" href="IO.html#stream_property/2">stream_property/2</A> 
and <A NAME="idx:open4:766"></A><A class="pred" href="IO.html#open/4">open/4</A>.

<DL class="latex">
<DT><STRONG>alias</STRONG>(<VAR>AliasName</VAR>)</DT>
<DD class="defbody">
Set the alias of an already created stream. If <VAR>AliasName</VAR> is 
the name of one of the standard streams is used, this stream is rebound. 
Thus, <CODE>set_stream(S, current_input)</CODE> is the same as <A NAME="idx:setinput1:767"></A><A class="pred" href="IO.html#set_input/1">set_input/1</A> 
and by setting the alias of a stream to <CODE>user_input</CODE>, etc. all 
user terminal input is read from this stream. See also <A NAME="idx:interactor0:768"></A><A class="pred" href="thutil.html#interactor/0">interactor/0</A>.</DD>
<DT><STRONG>buffer</STRONG>(<VAR>Buffering</VAR>)</DT>
<DD class="defbody">
Set the buffering mode of an already created stream. Buffering is one of <CODE>full</CODE>, <CODE>line</CODE> 
or <CODE>false</CODE>.</DD>
<DT><STRONG>buffer_size</STRONG>(<VAR>+Size</VAR>)</DT>
<DD class="defbody">
Set the size of the I/O buffer of the underlying stream to <VAR>Size</VAR> 
bytes.</DD>
<DT><STRONG>close_on_abort</STRONG>(<VAR>Bool</VAR>)</DT>
<DD class="defbody">
Determine whether or not the stream is closed by <A NAME="idx:abort0:769"></A><A class="pred" href="toplevel.html#abort/0">abort/0</A>. 
By default streams are closed.</DD>
<DT><STRONG>close_on_exec</STRONG>(<VAR>Bool</VAR>)</DT>
<DD class="defbody">
Set the <CODE>close_on_exec</CODE> property. See <A NAME="idx:streamproperty2:770"></A><A class="pred" href="IO.html#stream_property/2">stream_property/2</A>.</DD>
<DT><STRONG>encoding</STRONG>(<VAR>Atom</VAR>)</DT>
<DD class="defbody">
Defines the mapping between bytes and character codes used for the 
stream. See <A class="sec" href="widechars.html">section 2.17.1</A> for 
supported encodings.</DD>
<DT><STRONG>eof_action</STRONG>(<VAR>Action</VAR>)</DT>
<DD class="defbody">
Set end-of-file handling to one of <CODE>eof_code</CODE>, <CODE>reset</CODE> 
or
<CODE>error</CODE>.</DD>
<DT><STRONG>newline</STRONG>(<VAR>NewlineMode</VAR>)</DT>
<DD class="defbody">
Set input or output translation for newlines. See corresponding
<A NAME="idx:streamproperty2:771"></A><A class="pred" href="IO.html#stream_property/2">stream_property/2</A> 
for details. In addition to the detected modes, an input stream can be 
set in mode <CODE>detect</CODE>. It will be set to <CODE>dos</CODE> if a <CODE>\r</CODE> 
character was removed.</DD>
<DT><STRONG>timeout</STRONG>(<VAR>Seconds</VAR>)</DT>
<DD class="defbody">
This option can be used to make streams generate an exception if it 
takes longer than <VAR>Seconds</VAR> before any new data arrives at the 
stream. The value <VAR>infinite</VAR> (default) makes the stream block 
indefinitely. Like <A NAME="idx:waitforinput3:772"></A><A class="pred" href="streamstat.html#wait_for_input/3">wait_for_input/3</A>, 
this call only applies to streams that support the select() system call. 
For further information about timeout handling, see <A NAME="idx:waitforinput3:773"></A><A class="pred" href="streamstat.html#wait_for_input/3">wait_for_input/3</A>. 
The exception is of the form
<BLOCKQUOTE>
<CODE>error(<CODE>timeout_error(read, Stream)</CODE>, _)</CODE>
</BLOCKQUOTE>
</DD>
<DT><STRONG>type</STRONG>(<VAR>Type</VAR>)</DT>
<DD class="defbody">
Set the type of the stream to one of <CODE>text</CODE> or <CODE>binary</CODE>. 
See also <A NAME="idx:open4:774"></A><A class="pred" href="IO.html#open/4">open/4</A> 
and the <CODE>encoding</CODE> property of streams.</DD>
<DT><STRONG>record_position</STRONG>(<VAR>Bool</VAR>)</DT>
<DD class="defbody">
Do/do not record the line-count and line-position (see <A NAME="idx:linecount2:775"></A><A class="pred" href="streamstat.html#line_count/2">line_count/2</A> 
and <A NAME="idx:lineposition2:776"></A><A class="pred" href="streamstat.html#line_position/2">line_position/2</A>).</DD>
<DT><STRONG>representation_errors</STRONG>(<VAR>Mode</VAR>)</DT>
<DD class="defbody">
Change the behaviour when writing characters to the stream that cannot 
be represented by the encoding. See also <A NAME="idx:streamproperty2:777"></A><A class="pred" href="IO.html#stream_property/2">stream_property/2</A> 
and
<A class="sec" href="widechars.html">section 2.17.1</A>.</DD>
<DT><STRONG>file_name</STRONG>(<VAR>FileName</VAR>)</DT>
<DD class="defbody">
Set the file name associated to this stream. This call can be used to 
set the file for error-locations if <VAR>Stream</VAR> corresponds to
<VAR>FileName</VAR> and is not obtained by opening the file directly 
but, for example, through a network service.</DD>
<DT><STRONG>tty</STRONG>(<VAR>Bool</VAR>)</DT>
<DD class="defbody">
Modify whether Prolog thinks there is a terminal (i.e. human 
interaction) connected to this stream. On Unix systems the initial value 
comes from isatty(). On Windows, the initial user streams are supposed 
to be associated to a terminal. See also <A NAME="idx:streamproperty2:778"></A><A class="pred" href="IO.html#stream_property/2">stream_property/2</A>.
</DD>
</DL>

</DD>
<DT class="pubdef"><A NAME="set_prolog_IO/3"><STRONG>set_prolog_IO</STRONG>(<VAR>+In, 
+Out, +Error</VAR>)</A></DT>
<DD class="defbody">
Prepare the given streams for interactive behaviour normally associated 
to the terminal. <VAR>In</VAR> becomes the <CODE>user_input</CODE> and
<CODE>current_input</CODE> of the calling thread. <VAR>Out</VAR> becomes
<CODE>user_output</CODE> and <CODE>current_output</CODE>. If <VAR>Error</VAR> 
equals
<VAR>Out</VAR> an unbuffered stream is associated to the same 
destination and linked to <CODE>user_error</CODE>. Otherwise <VAR>Error</VAR> 
is used for
<CODE>user_error</CODE>. Output buffering for <VAR>Out</VAR> is set to
<CODE>line</CODE> and buffering on <VAR>Error</VAR> is disabled. See 
also <A NAME="idx:prolog0:779"></A><A class="pred" href="toplevel.html#prolog/0">prolog/0</A> 
and <A NAME="idx:setstream2:780"></A><A class="pred" href="IO.html#set_stream/2">set_stream/2</A>. 
The <EM>clib</EM> package provides the library <CODE>library(prolog_server)</CODE> 
creating a TCP/IP server for creating an interactive session to Prolog.
</DD>
</DL>

<H3><A NAME="sec:4.15.2"><SPAN class="sec-nr">4.15.2</SPAN> <SPAN class="sec-title">Edinburgh-style 
I/O</SPAN></A></H3>

<A NAME="sec:edinburghIO"></A>

<P>The package for implicit input and output destination is (almost) 
compatible with Edinburgh DEC-10 and C-Prolog. The reading and writing 
predicates refer to resp. the <EM>current</EM> input- and output stream. 
Initially these streams are connected to the terminal. The current 
output stream is changed using <A NAME="idx:tell1:781"></A><A class="pred" href="IO.html#tell/1">tell/1</A> 
or <A NAME="idx:append1:782"></A><A class="pred" href="IO.html#append/1">append/1</A>. 
The current input stream is changed using <A NAME="idx:see1:783"></A><A class="pred" href="IO.html#see/1">see/1</A>. 
The streams current value can be obtained using <A NAME="idx:telling1:784"></A><A class="pred" href="IO.html#telling/1">telling/1</A> 
for output- and <A NAME="idx:seeing1:785"></A><A class="pred" href="IO.html#seeing/1">seeing/1</A> 
for input streams.

<P>Source and destination are either a file, <CODE>user</CODE>, or a 
term `pipe(<VAR>Command</VAR>)'. The reserved stream name <CODE>user</CODE> 
refers to the terminal.<SUP class="fn">46<SPAN class="fn-text">The ISO 
I/O layer uses <CODE>user_input</CODE>, <CODE>user_output</CODE> and <CODE>user_error</CODE>.</SPAN></SUP> 
In the predicate descriptions below we will call the source/destination 
argument `<VAR>SrcDest</VAR>'. Below are some examples of 
source/destination specifications.

<P>
<CENTER>
<TABLE BORDER=0 FRAME=void RULES=groups>
<TR VALIGN=top><TD><CODE>?- see(data).</CODE> </TD><TD>% Start reading 
from file `data'. </TD></TR>
<TR VALIGN=top><TD><CODE>?- tell(user).</CODE> </TD><TD>% Start writing 
to the terminal. </TD></TR>
<TR VALIGN=top><TD><CODE>?- tell(pipe(lpr)).</CODE> </TD><TD>% Start 
writing to the printer.</TD></TR>
</TABLE>

</CENTER>

<P>Another example of using the <CODE>pipe/1</CODE> construct is shown 
below.<SUP class="fn">47<SPAN class="fn-text">As of version 5.3.15, the 
pipe construct is supported in the MS-Windows version, both for <B>swipl.exe</B> 
and <B>swipl-win.exe</B>. The implementation uses code from the LUA 
programming language (<A class="url" href="http://www.lua.org">http://www.lua.org</A>).</SPAN></SUP> 
Note that the <CODE>pipe/1</CODE> construct is not part of Prolog's 
standard I/O repertoire.

<PRE class="code">
getwd(Wd) :-
        seeing(Old), see(pipe(pwd)),
        collect_wd(String),
        seen, see(Old),
        atom_codes(Wd, String).

collect_wd([C|R]) :-
        get0(C), C \== -1, !,
        collect_wd(R).
collect_wd([]).
</PRE>

<H4>Compatibility notes</H4>

<P>Unlike Edinburgh Prolog systems, <A NAME="idx:telling1:786"></A><A class="pred" href="IO.html#telling/1">telling/1</A> 
and <A NAME="idx:seeing1:787"></A><A class="pred" href="IO.html#seeing/1">seeing/1</A> 
do not return the filename of the current input/output, but the 
stream-identifier, to ensure the design pattern below works under all 
circumstances.<SUP class="fn">48<SPAN class="fn-text">Filenames can be 
ambiguous and SWI-Prolog streams can refer to much more than just files.</SPAN></SUP>

<PRE class="code">
        ...,
        telling(Old), tell(x),
        ...,
        told, tell(Old),
        ...,
</PRE>

<P>The predicates <A NAME="idx:tell1:788"></A><A class="pred" href="IO.html#tell/1">tell/1</A> 
and <A NAME="idx:see1:789"></A><A class="pred" href="IO.html#see/1">see/1</A> 
first check for <CODE>user</CODE>, the
<CODE>pipe(command)</CODE> and a stream-handle. Otherwise, if the 
argument is an atom it is first compared to open streams associated to a 
file with <EM>exactly</EM> the same name. If such a stream, created 
using
<A NAME="idx:tell1:790"></A><A class="pred" href="IO.html#tell/1">tell/1</A> 
or <A NAME="idx:see1:791"></A><A class="pred" href="IO.html#see/1">see/1</A> 
exists, output (input) is switch to the open stream. Otherwise a file 
with the specified name is opened.

<P>The behaviour is compatible with Edinburgh Prolog. This is not 
without problems. Changing directory, non-file streams, multiple names 
referring to the same file easily lead to unexpected behaviour. New 
code, especially when managing multiple I/O channels should consider 
using the ISO I/O predicates defined in <A class="sec" href="IO.html">section 
4.15.1</A>.

<DL class="latex">
<DT class="pubdef"><A NAME="see/1"><STRONG>see</STRONG>(<VAR>+SrcDest</VAR>)</A></DT>
<DD class="defbody">
Open <VAR>SrcDest</VAR> for reading and make it the current input (see
<A NAME="idx:setinput1:792"></A><A class="pred" href="IO.html#set_input/1">set_input/1</A>). 
If <VAR>SrcDest</VAR> is a stream-handle, just makes this stream the 
current input. See the introduction of <A class="sec" href="IO.html">section 
4.15.2</A> for details.</DD>
<DT class="pubdef"><A NAME="tell/1"><STRONG>tell</STRONG>(<VAR>+SrcDest</VAR>)</A></DT>
<DD class="defbody">
Open <VAR>SrcDest</VAR> for writing and make it the current output (see
<A NAME="idx:setoutput1:793"></A><A class="pred" href="IO.html#set_output/1">set_output/1</A>). 
If <VAR>SrcDest</VAR> is a stream-handle, just makes this stream the 
current output. See the introduction of <A class="sec" href="IO.html">section 
4.15.2</A> for details.</DD>
<DT class="pubdef"><A NAME="append/1"><STRONG>append</STRONG>(<VAR>+File</VAR>)</A></DT>
<DD class="defbody">
Similar to <A NAME="idx:tell1:794"></A><A class="pred" href="IO.html#tell/1">tell/1</A>, 
but positions the file pointer at the end of <VAR>File</VAR> rather than 
truncating an existing file. The pipe construct is not accepted by this 
predicate.</DD>
<DT class="pubdef"><A NAME="seeing/1"><STRONG>seeing</STRONG>(<VAR>?SrcDest</VAR>)</A></DT>
<DD class="defbody">
Same as <A NAME="idx:currentinput1:795"></A><A class="pred" href="IO.html#current_input/1">current_input/1</A>, 
except that <CODE>user</CODE> is returned if the current input is the 
stream <CODE>user_input</CODE> to improve compatibility with traditional 
Edinburgh I/O. See the introduction of
<A class="sec" href="IO.html">section 4.15.2</A> for details.</DD>
<DT class="pubdef"><A NAME="telling/1"><STRONG>telling</STRONG>(<VAR>?SrcDest</VAR>)</A></DT>
<DD class="defbody">
Same as <A NAME="idx:currentoutput1:796"></A><A class="pred" href="IO.html#current_output/1">current_output/1</A>, 
except that <CODE>user</CODE> is returned if the current output is the 
stream <CODE>user_output</CODE> to improve compatibility with 
traditional Edinburgh I/O. See the introduction of
<A class="sec" href="IO.html">section 4.15.2</A> for details.</DD>
<DT class="pubdef"><A NAME="seen/0"><STRONG>seen</STRONG></A></DT>
<DD class="defbody">
Close the current input stream. The new input stream becomes
<VAR>user_input</VAR>.</DD>
<DT class="pubdef"><A NAME="told/0"><STRONG>told</STRONG></A></DT>
<DD class="defbody">
Close the current output stream. The new output stream becomes
<VAR>user_output</VAR>.
</DD>
</DL>

<H3><A NAME="sec:4.15.3"><SPAN class="sec-nr">4.15.3</SPAN> <SPAN class="sec-title">Switching 
Between Edinburgh and ISO I/O</SPAN></A></H3>

<P>The predicates below can be used for switching between the implicit- 
and the explicit stream based I/O predicates.

<DL class="latex">
<DT class="pubdef"><span class="pred-tag">[ISO]</span><A NAME="set_input/1"><STRONG>set_input</STRONG>(<VAR>+Stream</VAR>)</A></DT>
<DD class="defbody">
Set the current input stream to become <VAR>Stream</VAR>. Thus, 
open(file, read, Stream), set_input(Stream) is equivalent to see(file).
</DD>
<DT class="pubdef"><span class="pred-tag">[ISO]</span><A NAME="set_output/1"><STRONG>set_output</STRONG>(<VAR>+Stream</VAR>)</A></DT>
<DD class="defbody">
Set the current output stream to become <VAR>Stream</VAR>. See also
<A NAME="idx:withoutputto2:797"></A><A class="pred" href="IO.html#with_output_to/2">with_output_to/2</A>.
</DD>
<DT class="pubdef"><span class="pred-tag">[ISO]</span><A NAME="current_input/1"><STRONG>current_input</STRONG>(<VAR>-Stream</VAR>)</A></DT>
<DD class="defbody">
Get the current input stream. Useful to get access to the status 
predicates associated with streams.
</DD>
<DT class="pubdef"><span class="pred-tag">[ISO]</span><A NAME="current_output/1"><STRONG>current_output</STRONG>(<VAR>-Stream</VAR>)</A></DT>
<DD class="defbody">
Get the current output stream.
</DD>
</DL>

<H3><A NAME="sec:4.15.4"><SPAN class="sec-nr">4.15.4</SPAN> <SPAN class="sec-title">Write 
onto atoms, code-lists, etc.</SPAN></A></H3>

<DL class="latex">
<DT class="pubdef"><A NAME="with_output_to/2"><STRONG>with_output_to</STRONG>(<VAR>+Output, 
:Goal</VAR>)</A></DT>
<DD class="defbody">
Run <VAR>Goal</VAR> as <A NAME="idx:once1:798"></A><A class="pred" href="metacall.html#once/1">once/1</A>, 
while characters written to the current output is sent to <VAR>Output</VAR>. 
The predicate is SWI-Prolog specific, inspired by various posts to the 
mailinglist. It provides a flexible replacement for predicates such as 
sformat/3 , <A NAME="idx:swritef3:799"></A><A class="pred" href="format.html#swritef/3">swritef/3</A>,
<A NAME="idx:termtoatom2:800"></A><A class="pred" href="manipatom.html#term_to_atom/2">term_to_atom/2</A>, <A NAME="idx:atomnumber2:801"></A><A class="pred" href="manipatom.html#atom_number/2">atom_number/2</A> 
converting numbers to atoms, etc. The predicate <A NAME="idx:format3:802"></A><A class="pred" href="format.html#format/3">format/3</A> 
accepts the same terms as output argument.

<P>Applications should generally avoid creating atoms by breaking and 
concatenating other atoms as the creation of large numbers of 
intermediate atoms generally leads to poor performance, even more so in 
multi-threaded applications. This predicate supports creating 
difference-lists from character data efficiently. The example below 
defines the DCG rule <A NAME="idx:term1:803"></A><SPAN class="pred-ext">term/3</SPAN> 
to insert a term in the output:

<PRE class="code">
term(Term, In, Tail) :-
        with_output_to(codes(In, Tail), write(Term)).

?- phrase(term(hello), X).

X = [104, 101, 108, 108, 111]
</PRE>

<DL class="latex">
<DT><B>A Stream handle or alias</B></DT>
<DD class="defbody">
Temporary switch current output to the given stream. Redirection using
<A NAME="idx:withoutputto2:804"></A><A class="pred" href="IO.html#with_output_to/2">with_output_to/2</A> 
guarantees the original output is restored, also if
<VAR>Goal</VAR> fails or raises an exception. See also <A NAME="idx:callcleanup2:805"></A><A class="pred" href="metacall.html#call_cleanup/2">call_cleanup/2</A>.</DD>
<DT><STRONG>atom</STRONG>(<VAR>-Atom</VAR>)</DT>
<DD class="defbody">
Create an atom from the emitted characters. Please note the remark 
above.</DD>
<DT><STRONG>string</STRONG>(<VAR>-String</VAR>)</DT>
<DD class="defbody">
Create a string-object as defined in <A class="sec" href="strings.html">section 
4.22</A>.</DD>
<DT><STRONG>codes</STRONG>(<VAR>-Codes</VAR>)</DT>
<DD class="defbody">
Create a list of character codes from the emitted characters, similar to
<A NAME="idx:atomcodes2:806"></A><A class="pred" href="manipatom.html#atom_codes/2">atom_codes/2</A>.</DD>
<DT><STRONG>codes</STRONG>(<VAR>-Codes, -Tail</VAR>)</DT>
<DD class="defbody">
Create a list of character codes as a difference-list.</DD>
<DT><STRONG>chars</STRONG>(<VAR>-Chars</VAR>)</DT>
<DD class="defbody">
Create a list of one-character-atoms codes from the emitted characters, 
similar to <A NAME="idx:atomchars2:807"></A><A class="pred" href="manipatom.html#atom_chars/2">atom_chars/2</A>.</DD>
<DT><STRONG>chars</STRONG>(<VAR>-Chars, -Tail</VAR>)</DT>
<DD class="defbody">
Create a list of one-character-atoms as a difference-list.
</DD>
</DL>

</DD>
</DL>

<P></BODY></HTML>
swi-prolog-nox 5.10.4-3ubuntu1 / usr / lib / swi-prolog / doc / Manual / IO.html
