<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>Function set "Stream factory functions" - Function set "Stream factory functions"</title>
<link href="faldoc.css" rel="stylesheet" type="text/css"/>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
</head>
<body class="faldoc_body">
<div class="navitop">
<div class="tabs">
<ul>
<li><a href="./index.html"><span>Main</span></a></li>
<li><a href="./pages.html"><span>Related pages</span></a></li>
<li><a href="./groups.html"><span>Groups</span></a></li>
<li><a href="./funset.html"><span>Function sets</span></a></li>
<li><a href="./classes.html"><span>Classes</span></a></li>
<li><a href="./objects.html"><span>Objects</span></a></li>
<li><a href="./functions.html"><span>All functions</span></a></li>
<li><a href="./globals.html"><span>Globals</span></a></li>
</ul>
</div>
</div>
<hr/>
<h1 class="faldoc_title">Function set "Stream factory functions"</h1>
<p class="faldoc_brief">Function creating or opening file and system streams. </p>
<p class="faldoc_brief"><a href="#more">more...</a></p>
<h2 class="faldoc_title">Summary</h2>
<table class="faldoc_list">
<tr><td><a href="#IOStream">IOStream()</a></td><td>Creates a stream for input and output. </td></tr>
<tr><td><a href="#InputStream">InputStream()</a></td><td>Open a system file for reading. </td></tr>
<tr><td><a href="#OutputStream">OutputStream()</a></td><td>Creates a stream for output only. </td></tr>
<tr><td><a href="#stdErr">stdErr()</a></td><td>Creates an object mapped to the standard error of the Virtual Machine. </td></tr>
<tr><td><a href="#stdErrRaw">stdErrRaw()</a></td><td>Creates a stream that interfaces the standard error stream of the host process. </td></tr>
<tr><td><a href="#stdIn">stdIn()</a></td><td>Creates an object mapped to the standard input of the Virtual Machine. </td></tr>
<tr><td><a href="#stdInRaw">stdInRaw()</a></td><td>Creates a stream that interfaces the standard input stream of the host process. </td></tr>
<tr><td><a href="#stdOut">stdOut()</a></td><td>Creates an object mapped to the standard output of the Virtual Machine. </td></tr>
<tr><td><a href="#stdOutRaw">stdOutRaw()</a></td><td>Creates a stream that interfaces the standard output stream of the host process. </td></tr>
</table>
<a name="more"><h2 class="faldoc_title">Detailed description</h2></a>
<table class="faldoc_function">
</table>
<br/>
<p class="item_brief">Function creating or opening file and system streams. </p>
<p class="faldoc_text">Stream factory functions create a stream object bound to a system file. As the open or create operation may fail, using a factory function is more appropriate, as they can avoid creating the underlying stream object when not needed. Also, they can setup the proper stream subclass to manage special files. </p>
<p class="faldoc_text">Stream factory function often accept a parameter to determine the sharing mode. Only some systems implements correctly this functionality, so use with caution. Predefined constant that can be used as share mode are: </p>
<ul>
<li><b>FILE_EXCLUSIVE</b>: The calling scripts own the shared file; other processes trying to open the file, or even the same process, should receive an error. </li><li><b>FILE_SHARE_READ</b>: A file opened in this way can be opened by other processes, but only for read operations. </li><li><b>FILE_SHARE</b>: Any process may open and overwrite the file. </li>
</ul>
<p class="faldoc_text">Function creating files, as IOStream() and OutputStream() accepts also a creation ownership mode. This is actually an octal number that is directly passed to the POSIX systems for directory ownership creation. It has currently no meaning for MS-Windows systems. </p>
<h2 class="faldoc_title">Members</h2>
<h3 class="faldoc_funcname"><a name="IOStream">IOStream()</a></h3>
<p class="item_brief">Creates a stream for input and output. </p>
<p class="faldoc_funcdecl">IOStream( fileName, [createMode], [shareMode] )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">fileName</td><td class="faldoc_paramdesc">A relative or absolute path to a file to be opened for input </td></tr>
<tr><td class="faldoc_optparam">createMode</td><td class="faldoc_optparamdesc">If given, the ownership of the created file. </td></tr><tr><td class="faldoc_optparam">shareMode</td><td class="faldoc_optparamdesc">If given, the share mode. </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc"> A new valid <a href="./class_Stream.html">Stream</a> instance on success. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">If the function is successful, it creates the given fileName and returns a valid stream object by which the underlying file may be read. If an already existing file name is given, then the file is truncated and its access right are updated. Calling read methods on the returned object will fail, raising an error. </p>
<p class="faldoc_text">If the file can be created, its sharing mode can be controlled by providing a shareMode parameter. In case the shareMode is not given, then the maximum publicity is used. </p>
<p class="faldoc_text">If the file cannot be created, an error containing a valid fsError code is raised. </p>
<p class="faldoc_text"> See <a href="./funset_core_stream_factory.html">Stream factory functions</a> for a description of the shared modes. </p>
</p>
<h3 class="faldoc_funcname"><a name="InputStream">InputStream()</a></h3>
<p class="item_brief">Open a system file for reading. </p>
<p class="faldoc_funcdecl">InputStream( fileName, [shareMode] )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">fileName</td><td class="faldoc_paramdesc">A relative or absolute path to a file to be opened for input </td></tr>
<tr><td class="faldoc_optparam">shareMode</td><td class="faldoc_optparamdesc">If given, the share mode. </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc"> A new valid <a href="./class_Stream.html">Stream</a> instance on success. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">If the function is successful, it opens the given fileName and returns a valid stream object by which the underlying file may be read. Calling write methods on the returned object will fail, raising an error. </p>
<p class="faldoc_text">If the optional share parameter is not given, the maximum share publicity available on the system will be used. </p>
<p class="faldoc_text">If the file cannot be open, an error containing a valid fsError code is raised. </p>
<p class="faldoc_text"> See <a href="./funset_core_stream_factory.html">Stream factory functions</a> for a description of the shared modes. </p>
</p>
<h3 class="faldoc_funcname"><a name="OutputStream">OutputStream()</a></h3>
<p class="item_brief">Creates a stream for output only. </p>
<p class="faldoc_funcdecl">OutputStream( fileName, [createMode], [shareMode] )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">fileName</td><td class="faldoc_paramdesc">A relative or absolute path to a file to be opened for input </td></tr>
<tr><td class="faldoc_optparam">createMode</td><td class="faldoc_optparamdesc">If given, the ownership of the created file. </td></tr><tr><td class="faldoc_optparam">shareMode</td><td class="faldoc_optparamdesc">If given, the share mode. </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc"> A new valid <a href="./class_Stream.html">Stream</a> instance on success. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">If the function is successful, it creates the given fileName and returns a valid stream object by which the underlying file may be read. If an already existing file name is given, then the file is truncated and its access right are updated. Calling read methods on the returned object will fail, raising an error. </p>
<p class="faldoc_text">If the file can be created, its sharing mode can be controlled by providing a shareMode parameter. In case the shareMode is not given, then the maximum publicity is used. </p>
<p class="faldoc_text">If the file cannot be created, an error containing a valid fsError code is raised. </p>
<p class="faldoc_text"> See <a href="./funset_core_stream_factory.html">Stream factory functions</a> for a description of the shared modes. </p>
</p>
<h3 class="faldoc_funcname"><a name="stdErr">stdErr()</a></h3>
<p class="item_brief">Creates an object mapped to the standard error of the Virtual Machine. </p>
<p class="faldoc_funcdecl">stdErr</p>
<table class="faldoc_function">
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc"> A new valid <a href="./class_Stream.html">Stream</a> instance on success. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">The returned stream maps output operations on the standard error stream of the virtual machine hosting the script. </p>
<p class="faldoc_text">The returned stream is a clone of the stream used by the Virtual Machine as standard error stream. This means that every transcoding applied by the VM is also available to the script, and that, when running in embedding applications, the stream will be handled by the embedder. </p>
<p class="faldoc_text">As a clone of this stream is held in the VM, closing it will have actually no effect, except that of invalidating the instance returned by this function. </p>
<p class="faldoc_text">Read operations will fail raising an I/O error. </p>
</p>
<h3 class="faldoc_funcname"><a name="stdErrRaw">stdErrRaw()</a></h3>
<p class="item_brief">Creates a stream that interfaces the standard error stream of the host process. </p>
<p class="faldoc_funcdecl">stdErrRaw</p>
<table class="faldoc_function">
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc"> A new valid <a href="./class_Stream.html">Stream</a> instance on success. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text"> The returned stream maps output operations on the standard error stream of the process hosting the script. The returned stream is bound directly with the process error stream, without any automatic transcoding applied. <a href="./class_Stream.html#writeText">Stream.writeText</a> will write the text as stream of bytes to the stream, unless <a href="./class_Stream.html#setEncoding">Stream.setEncoding</a> is explicitly called on the returned instance. </p>
<p class="faldoc_text">Closing this stream has the effect to close the standard error stream of the process running the script (if the operation is allowed by the embedding application). Applications reading from the error stream of the script will be notified that the stream has been closed, and won't be left pending in reading this stream. </p>
<p class="faldoc_text">The stream is write only. Read operations will cause an I/O to be raised. </p>
</p>
<h3 class="faldoc_funcname"><a name="stdIn">stdIn()</a></h3>
<p class="item_brief">Creates an object mapped to the standard input of the Virtual Machine. </p>
<p class="faldoc_funcdecl">stdIn</p>
<table class="faldoc_function">
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc"> A new valid <a href="./class_Stream.html">Stream</a> instance on success. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">The returned read-only stream is mapped to the standard input of the virtual machine hosting the script. Read operations will return the characters from the input stream as they are available. The readAvailable() method of the returned stream will indicate if read operations may block. Calling the read() method will block until some character can be read, or will fill the given buffer up the amount of currently available characters. </p>
<p class="faldoc_text">The returned stream is a clone of the stream used by the Virtual Machine as standard input stream. This means that every transcoding applied by the VM is also available to the script, and that, when running in embedding applications, the stream will be handled by the embedder. </p>
<p class="faldoc_text">As a clone of this stream is held in the VM, closing it will have actually no effect, except that of invalidating the instance returned by this function. </p>
<p class="faldoc_text">Read operations will fail raising an I/O error. </p>
</p>
<h3 class="faldoc_funcname"><a name="stdInRaw">stdInRaw()</a></h3>
<p class="item_brief">Creates a stream that interfaces the standard input stream of the host process. </p>
<p class="faldoc_funcdecl">stdInRaw</p>
<table class="faldoc_function">
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc"> A new valid <a href="./class_Stream.html">Stream</a> instance on success. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text"> The returned stream maps input operations on the standard input of the process hosting the script. The returned stream is bound directly with the process input stream, without any automatic transcoding applied. <a href="./class_Stream.html#readText">Stream.readText</a> will read the text as stream of binary data coming from the stream, unless <a href="./class_Stream.html#setEncoding">Stream.setEncoding</a> is explicitly called on the returned instance. </p>
<p class="faldoc_text">Closing this stream has the effect to close the standard input stream of the process running the script (if the operation is allowed by the embedding application). Applications trying to write data to the script process will be notified that the script has closed the stream and is not willing to receive data anymore. </p>
<p class="faldoc_text">The stream is read only. Write operations will cause an I/O to be raised. </p>
</p>
<h3 class="faldoc_funcname"><a name="stdOut">stdOut()</a></h3>
<p class="item_brief">Creates an object mapped to the standard output of the Virtual Machine. </p>
<p class="faldoc_funcdecl">stdOut</p>
<table class="faldoc_function">
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc"> A new valid <a href="./class_Stream.html">Stream</a> instance on success. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">The returned stream maps output operations on the standard output stream of the process hosting the script. </p>
<p class="faldoc_text">The returned stream is a clone of the stream used by the Virtual Machine as standard output stream. This means that every transcoding applied by the VM is also available to the script, and that, when running in embedding applications, the stream will be handled by the embedder. </p>
<p class="faldoc_text">As a clone of this stream is held in the VM, closing it will have actually no effect, except that of invalidating the instance returned by this function. </p>
<p class="faldoc_text">Read operations will fail raising an I/O error. </p>
</p>
<h3 class="faldoc_funcname"><a name="stdOutRaw">stdOutRaw()</a></h3>
<p class="item_brief">Creates a stream that interfaces the standard output stream of the host process. </p>
<p class="faldoc_funcdecl">stdOutRaw</p>
<table class="faldoc_function">
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc"> A new valid <a href="./class_Stream.html">Stream</a> instance on success. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text"> The returned stream maps output operations on the standard output stream of the process hosting the script. The returned stream is bound directly with the process output, without any automatic transcoding applied. <a href="./class_Stream.html#writeText">Stream.writeText</a> will write the text as stream of bytes to the stream, unless <a href="./class_Stream.html#setEncoding">Stream.setEncoding</a> is explicitly called on the returned instance. </p>
<p class="faldoc_text">Closing this stream has the effect to close the standard output of the process running the script (if the operation is allowed by the embedding application). Print functions, fast print operations, default error reporting and so on will be unavailable from this point on. </p>
<p class="faldoc_text">Applications reading from the output stream of the process running the scripts, in example, piped applications, will recognize that the script has completed its output, and will disconnect immediately, while the script may continue to run. </p>
<p class="faldoc_text">The stream is write only. Read operations will cause an IoError to be raised. </p>
</p>
<hr/>
<div class="navibottom">
<center>
<a href="./index.html">Main</a> - <a href="./pages.html">Related pages</a> - <a href="./groups.html">Groups</a> - <a href="./funset.html">Function sets</a> - <a href="./classes.html">Classes</a> - <a href="./objects.html">Objects</a> - <a href="./functions.html">All functions</a> - <a href="./globals.html">Globals</a>
</center>
</div>
</div>
<div class="faldoc_signature">Made with <a href="http://www.falconpl.org">faldoc 2.2.0</div>
</body>
</html>
