/usr/share/mozart/doc/system/node55.html is in mozart-doc 1.4.0-8ubuntu1.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 | <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<HTML><HEAD><TITLE>20 Files, Sockets, and Pipes: Open</TITLE><LINK href="ozdoc.css" rel="stylesheet" type="text/css"></HEAD><BODY><TABLE align="center" border="0" cellpadding="6" cellspacing="6" class="nav"><TR bgcolor="#DDDDDD"><TD><A href="index.html">- Up -</A></TD><TD><A href="node56.html#chapter.os">Next >></A></TD></TR></TABLE><DIV id="chapter.open"><H1><A name="chapter.open">20 Files, Sockets, and Pipes: <CODE>Open</CODE></A></H1><P>This chapter gives reference documentation for the <CODE>Open</CODE> module. The module contains the following classes: </P><OL type="1"><LI><P><CODE>Open<SPAN class="keyword">.</SPAN>file</CODE> for reading and writing files.</P></LI><LI><P><CODE>Open<SPAN class="keyword">.</SPAN>socket</CODE> for Internet socket connections.</P></LI><LI><P><CODE>Open<SPAN class="keyword">.</SPAN>pipe</CODE> for creation of operating system processes.</P></LI><LI><P><CODE>Open<SPAN class="keyword">.</SPAN>text</CODE> for reading and writing text line by line and character by character. It is a mixin class that can be combined with any of the classes of the <CODE>Open</CODE> module.</P></LI></OL><P> </P><P>A tutorial account on open programming can be found in <A href="../op/index.html">``Open Programming in Mozart''</A>. </P><H2><A name="label623">20.1 Exceptions</A></H2><P>The methods of any of the <CODE>Open</CODE> module classes can raise different exceptions.</P><P></P><P class="margin">operating system</P><P>When an operating system exception occurs the Oz exception defined in the module <CODE>OS</CODE> is raised. </P><P class="margin">already initialized</P><P>An exception of the format </P><BLOCKQUOTE class="code"><CODE>system(open(alreadyInitialized </CODE><CODE><I>O</I></CODE><CODE> </CODE><CODE><I>M</I></CODE><CODE>) debug:</CODE><CODE><I>X</I></CODE><CODE>)</CODE></BLOCKQUOTE><P> is raised if an already initialized object <CODE><I>O</I></CODE> is initialized again by applying it to the message <CODE><I>M</I></CODE>. </P><P class="margin">already closed</P><P>An exception of the format </P><BLOCKQUOTE class="code"><CODE>system(open(alreadyClosed </CODE><CODE><I>O</I></CODE><CODE> </CODE><CODE><I>M</I></CODE><CODE>) debug:</CODE><CODE><I>X</I></CODE><CODE>)</CODE></BLOCKQUOTE><P> is raised if a method other than <CODE>close</CODE> of an already closed object <CODE><I>O</I></CODE> is applied. <CODE><I>M</I></CODE> is as above the message the object has been applied to. </P><P class="margin">illegal flags</P><P>An exception of the format </P><BLOCKQUOTE class="code"><CODE>system(open(illegalFlags </CODE><CODE><I>O</I></CODE><CODE> </CODE><CODE><I>M</I></CODE><CODE>) debug:</CODE><CODE><I>X</I></CODE><CODE>)</CODE></BLOCKQUOTE><P> is raised if an object <CODE><I>O</I></CODE> is initialized with an unknown flag. <CODE><I>M</I></CODE> is the initialization message. </P><P class="margin">ilegal modes</P><P>An exception of the format </P><BLOCKQUOTE class="code"><CODE>system(open(illegalModes </CODE><CODE><I>O</I></CODE><CODE> </CODE><CODE><I>M</I></CODE><CODE>) debug:</CODE><CODE><I>X</I></CODE><CODE>)</CODE></BLOCKQUOTE><P> is raised if an object <CODE><I>O</I></CODE> is initialized with an unknown mode. <CODE><I>M</I></CODE> is the initialization message. </P><P class="margin">name or URL</P><P>An exception of the format </P><BLOCKQUOTE class="code"><CODE>system(open(nameOrUrl </CODE><CODE><I>O</I></CODE><CODE> </CODE><CODE><I>M</I></CODE><CODE>) debug:</CODE><CODE><I>X</I></CODE><CODE>)</CODE></BLOCKQUOTE><P> is raised if an object <CODE><I>O</I></CODE> is initialized with both a name and an URL or with neither. <CODE><I>M</I></CODE> is the initialization message. </P><P class="margin">URL is read-only</P><P>An exception of the format </P><BLOCKQUOTE class="code"><CODE>system(open(urlIsReadOnly </CODE><CODE><I>O</I></CODE><CODE> </CODE><CODE><I>M</I></CODE><CODE>) debug:</CODE><CODE><I>X</I></CODE><CODE>)</CODE></BLOCKQUOTE><P> is raised if an object <CODE><I>O</I></CODE> is initialized with an URL and the <CODE>write</CODE> flag. <CODE><I>M</I></CODE> is the initialization message. </P><DIV id="section.file.obj"><H2><A name="section.file.obj">20.2 The Class <CODE>Open<SPAN class="keyword">.</SPAN>file</CODE></A></H2><P><A name="label625"></A> The class <CODE>Open<SPAN class="keyword">.</SPAN>file</CODE> has the following public methods. </P><DL><DT><CODE>init</CODE> </DT><DD><BLOCKQUOTE class="synopsis"><P></P><BLOCKQUOTE class="code"><CODE>init(name: </CODE><CODE>+<I>NameV</I></CODE><CODE> <BR> flags:</CODE><CODE>+<I>FlagsAs</I></CODE><CODE> <SPAN class="keyword"><=</SPAN> [read]<BR> mode: </CODE><CODE>+<I>ModeR</I></CODE><CODE> <SPAN class="keyword"><=</SPAN> mode(owner:[write] all:[read]))<BR>init(url: </CODE><CODE>+<I>UrlV</I></CODE><CODE> <BR> flags:</CODE><CODE>+<I>FlagsAs</I></CODE><CODE> <SPAN class="keyword"><=</SPAN> [read]<BR> mode: </CODE><CODE>+<I>ModeR</I></CODE><CODE> <SPAN class="keyword"><=</SPAN> mode(owner:[write] all:[read]))</CODE></BLOCKQUOTE><P></P></BLOCKQUOTE></DD><DD><P><A name="label627"></A> Initializes the file object and associates it with a Unix file.</P><P><A name="label628"></A><A name="label629"></A><A name="label630"></A> <CODE><I>NameV</I></CODE> is either a valid filename or one of the atoms <CODE>stdin</CODE>, <CODE>stdout</CODE>, and <CODE>stderr</CODE>. In this case, the standard input, standard output, or standard error stream is opened, respectively. </P><P>In addition to using a filename to open a file also a url <CODE><I>UrlV</I></CODE> can be used. Only one of the features <CODE>name</CODE> or <CODE>url</CODE> is allowed.</P><P>The value of <CODE><I>FlagsAs</I></CODE> must be a list, with its elements chosen from the following atoms:</P><P><CODE>read</CODE>, <CODE>write</CODE>, <CODE>append</CODE>, <CODE>create</CODE>, <CODE>truncate</CODE>, <CODE>exclude</CODE>, <CODE>text</CODE>, <CODE>binary</CODE></P><P>For reading a file, the atom <CODE>read</CODE> must be included in <CODE><I>FlagsAs</I></CODE>. Similarly, the atom <CODE>write</CODE> must be included for writing. It is possible to include both atoms, giving both read and write access to the file. For files attached to an url, only reading access is possible.</P><P>Atom <CODE>text</CODE> opens a file in text mode. This is important on platforms (e. g. Windows) where the line ends are represented on disk by <CODE>CRLF</CODE> rather than just <CODE>LF</CODE>. On such platforms, when a file is opened in text mode, the conversion from <CODE>CRLF</CODE> to <CODE>LF</CODE> on reading (and in the reverse direction on writing) happens automatically. Atom <CODE>binary</CODE> opens a file in binary mode, where no such translation happens. On other platforms (e. g. Linux), these flags have no effect.</P><P>When a file object is opened, the <A name="label631"></A><EM>seek pointer</EM><A name="label632"></A>, pointing to the current position in the file, is initialized to point to the start of the file. Any subsequent read or write takes place at the position given by this pointer.</P><P>The remaining atoms make sense only if the file is opened for writing. If the atom <CODE>append</CODE> is included, the seek pointer is moved to the end of the file prior to each attempt to write to the file.</P><P>If the file to be opened already exists, the presence of the atom <CODE>create</CODE> has no effect. Otherwise, the file is created. Including <CODE>truncate</CODE> resets the length of an existing file to zero and discards its previous content. </P><P>An attempt to open an existing file fails, if <CODE>exclude</CODE> is contained. Thus, this flag grants exclusive access of the file object to the operating system file. </P><P>If the file is opened for writing and the atom <CODE>create</CODE> is included, the access rights are set as specified by <CODE><I>ModeR</I></CODE>. This must be a record with fields drawn from <CODE>all</CODE>, <CODE>owner</CODE>, <CODE>group</CODE> and <CODE>others</CODE>. Its subterms must be lists of the atoms <CODE>read</CODE>, <CODE>write</CODE> and <CODE>execute</CODE>. </P><P>More detailed information can be found in <CODE>open(2)</CODE>, <CODE>chmod(2)</CODE>, and <CODE>umask(2)</CODE>. </P></DD><DT><CODE>read</CODE> </DT><DD><BLOCKQUOTE class="synopsis"><P></P><BLOCKQUOTE class="code"><CODE>read(list: </CODE><CODE>?<I>ListS</I></CODE><CODE> <BR> tail: </CODE><CODE><I>TailX</I></CODE><CODE> <SPAN class="keyword"><=</SPAN> nil <BR> size: </CODE><CODE>+<I>SizeAI</I></CODE><CODE> <SPAN class="keyword"><=</SPAN> 1024 <BR> len: </CODE><CODE>?<I>LenI</I></CODE><CODE> <SPAN class="keyword"><=</SPAN> _) </CODE></BLOCKQUOTE><P></P></BLOCKQUOTE></DD><DD><P><A name="label634"></A> Reads data from a file. <CODE><I>SizeAI</I></CODE> specifies how much data should be read from the file. If the field <CODE>len</CODE> is present, <CODE><I>LenI</I></CODE> is bound to the number of bytes actually read. <CODE><I>LenI</I></CODE> may be less than <CODE><I>SizeAI</I></CODE>. The atom <CODE>all</CODE> is also a legal value for <CODE><I>SizeAI</I></CODE>. In this case the entire file is read.</P><P>The data read binds <CODE><I>ListS</I></CODE> to a list of characters. The tail of the list can be given by <CODE><I>TailX</I></CODE>. The value for <CODE><I>TailX</I></CODE> defaults to <CODE>nil</CODE>, which means that in this case the list <CODE><I>ListS</I></CODE> is a string.</P><P>See also <CODE>read(2)</CODE>. </P></DD><DT><CODE>write</CODE> </DT><DD><BLOCKQUOTE class="synopsis"><P></P><BLOCKQUOTE class="code"><CODE>write(vs: </CODE><CODE>+<I>V</I></CODE><CODE> <BR> len: </CODE><CODE>?<I>I</I></CODE><CODE> <SPAN class="keyword"><=</SPAN> _)</CODE></BLOCKQUOTE><P></P></BLOCKQUOTE></DD><DD><P><A name="label636"></A> Writes the virtual string <CODE><I>V</I></CODE> to a file. </P><P>See <CODE>write(2)</CODE>. </P></DD><DT><CODE>seek</CODE> </DT><DD><BLOCKQUOTE class="synopsis"><P></P><BLOCKQUOTE class="code"><CODE>seek(whence: </CODE><CODE>+<I>WhenceA</I></CODE><CODE> <SPAN class="keyword"><=</SPAN> set <BR> offset: </CODE><CODE>+<I>OffsetI</I></CODE><CODE> <SPAN class="keyword"><=</SPAN> 0)</CODE></BLOCKQUOTE><P></P></BLOCKQUOTE></DD><DD><P><A name="label638"></A> Sets the file object's seek pointer</P><P>Allowed values for <CODE><I>WhenceA</I></CODE> are the atoms <CODE>set</CODE>, <CODE>current</CODE>, or <CODE><SPAN class="string">'end'</SPAN></CODE>.</P><P>In case of <CODE>set</CODE> the position of the seek pointer is moved to the absolute position from the beginning of the file given by the value of <CODE><I>OffsetI</I></CODE>. </P><P>In case of <CODE>current</CODE> the pointer is moved ahead by <CODE><I>OffsetI</I></CODE>. Notice, that the pointer can be moved backward by a negative <CODE><I>OffsetI</I></CODE>, and forward by a positive <CODE><I>OffsetI</I></CODE>.</P><P>If <CODE><SPAN class="string">'end'</SPAN></CODE> is given, the pointer is moved by <CODE><I>OffsetI</I></CODE> with respect to the current end of the file. </P><P>In particular, invoking <CODE>seek</CODE> with the default parameters moves the pointer to the beginning of the file.</P><P>See <CODE>lseek(2)</CODE>. </P></DD><DT><CODE>tell</CODE> </DT><DD><BLOCKQUOTE class="synopsis"><P></P><BLOCKQUOTE class="code"><CODE>tell(offset: </CODE><CODE>?<I>OffsetI</I></CODE><CODE>)</CODE></BLOCKQUOTE><P></P></BLOCKQUOTE></DD><DD><P><A name="label640"></A> Returns the current position of the seek pointer counting from the beginning of the file.</P><P>See <CODE>lseek(2)</CODE>. </P></DD><DT><CODE>close</CODE> </DT><DD><BLOCKQUOTE class="synopsis"><P></P><BLOCKQUOTE class="code"><CODE>close</CODE></BLOCKQUOTE><P></P></BLOCKQUOTE></DD><DD><P><A name="label642"></A> Closes the file object as well as the file.</P><P>See <CODE>close(2)</CODE>. </P></DD><DT><CODE>dOpen</CODE> </DT><DD><BLOCKQUOTE class="synopsis"><P></P><BLOCKQUOTE class="code"><CODE>dOpen(</CODE><CODE>+<I>ReadFileDescI</I></CODE><CODE> </CODE><CODE>+<I>WriteFileDescI</I></CODE><CODE>)</CODE></BLOCKQUOTE><P></P></BLOCKQUOTE></DD><DD><P><A name="label644"></A></P><DIV class="danger"><P class="margin"><IMG align="top" alt="Danger" src="danger.gif"></P><P>Initializes the object. <CODE><I>ReadFileDescI</I></CODE> and <CODE><I>WriteFileDescI</I></CODE> must be integers of already open file descriptors (in the usual operating system sense). Note that this method should only be used for advanced purposes. </P></DIV></DD><DT><CODE>getDesc</CODE> </DT><DD><BLOCKQUOTE class="synopsis"><P></P><BLOCKQUOTE class="code"><CODE>getDesc(</CODE><CODE>?<I>ReadFileDescIB</I></CODE><CODE> </CODE><CODE>?<I>WriteFileDescIB</I></CODE><CODE>)</CODE></BLOCKQUOTE><P></P></BLOCKQUOTE></DD><DD><P><A name="label646"></A></P><DIV class="danger"><P class="margin"><IMG align="top" alt="Danger" src="danger.gif"></P><P>Returns the internally used file descriptors.</P></DIV><P>If the object is not yet initialized, <CODE><I>ReadFileDescIB</I></CODE> and <CODE><I>WriteFileDescIB</I></CODE> are bound to <CODE><SPAN class="keyword">false</SPAN></CODE>, otherwise to the respective integers. Note, that this method is only for advanced purposes.</P></DD></DL><P></P></DIV><DIV id="sec-socket-obj"><H2><A name="sec-socket-obj">20.3 The Class <CODE>Open<SPAN class="keyword">.</SPAN>socket</CODE></A></H2><P>The class <CODE>Open<SPAN class="keyword">.</SPAN>socket</CODE> has the following public methods. <A name="label648"></A> </P><DL><DT><CODE>init</CODE> </DT><DD><BLOCKQUOTE class="synopsis"><P></P><BLOCKQUOTE class="code"><CODE>init(type: </CODE><CODE>+<I>TypeA</I></CODE><CODE> <SPAN class="keyword"><=</SPAN> stream<BR> protocol: </CODE><CODE>+<I>ProtoV</I></CODE><CODE> <SPAN class="keyword"><=</SPAN> <SPAN class="string">""</SPAN> <BR> time: </CODE><CODE>+<I>TimeI</I></CODE><CODE> <SPAN class="keyword"><=</SPAN> <SPAN class="keyword">~</SPAN>1) </CODE></BLOCKQUOTE><P></P></BLOCKQUOTE></DD><DD><P><A name="label650"></A> Initializes a socket object.</P><P>The type of the socket <CODE><I>TypeA</I></CODE> determines the type of the socket, which can be either <CODE>stream</CODE> or <CODE>datagram</CODE>.</P><P>The protocol is described by <CODE><I>ProtoV</I></CODE> where the empty string <CODE><SPAN class="string">""</SPAN></CODE> means to choose an appropriate protocol automatically. Other possible values are the TCP protocol <A name="label651"></A> (you have to give <CODE><SPAN class="string">"tcp"</SPAN></CODE>) for stream sockets, and UDP <A name="label652"></A> (you have to give <CODE><SPAN class="string">"udp"</SPAN></CODE>) for datagram sockets.</P><P>The integer <CODE><I>TimeI</I></CODE> specifys for how long a time (in milliseconds) the socket attempts to accept a connection. The value <CODE><SPAN class="keyword">~</SPAN>1</CODE> means infinite time. See the following description of the <CODE>accept</CODE> method for more details.</P><P>See also <CODE>socket(2)</CODE>. </P></DD><DT><CODE>bind</CODE> </DT><DD><BLOCKQUOTE class="synopsis"><P></P><BLOCKQUOTE class="code"><CODE>bind(takePort: </CODE><CODE>+<I>TakePortI</I></CODE><CODE> <SPAN class="keyword"><=</SPAN> _ <BR> port: </CODE><CODE>?<I>PortI</I></CODE><CODE> <SPAN class="keyword"><=</SPAN> _)</CODE></BLOCKQUOTE><P></P></BLOCKQUOTE></DD><DD><P><A name="label654"></A> Names a socket globally.</P><P>If the field <CODE>takePort</CODE> is present, its value is chosen for binding. Otherwise, a fresh port number value is generated by the object. This port number is accessible at the field <CODE>port</CODE>.</P><P>See also <CODE>bind(2)</CODE>. </P></DD><DT><CODE>listen</CODE> </DT><DD><BLOCKQUOTE class="synopsis"><P></P><BLOCKQUOTE class="code"><CODE>listen(backLog: </CODE><CODE>+<I>LogI</I></CODE><CODE> <SPAN class="keyword"><=</SPAN> 5)</CODE></BLOCKQUOTE><P></P></BLOCKQUOTE></DD><DD><P><A name="label656"></A> Signals that a socket is willing to accept connections.</P><P><CODE><I>LogI</I></CODE> describes the maximum number of pending connections to be buffered by the system.</P><P>See also <CODE>listen(2)</CODE>. </P></DD><DT><CODE>accept</CODE> </DT><DD><BLOCKQUOTE class="synopsis"><P></P><BLOCKQUOTE class="code"><CODE>accept(accepted: </CODE><CODE>?<I>Object</I></CODE><CODE> <SPAN class="keyword"><=</SPAN> _<BR> acceptClass: </CODE><CODE>+<I>Class</I></CODE><CODE> <SPAN class="keyword"><=</SPAN> _ <BR> host: </CODE><CODE>?<I>HostSB</I></CODE><CODE> <SPAN class="keyword"><=</SPAN> _ <BR> port: </CODE><CODE>?<I>PortIB</I></CODE><CODE> <SPAN class="keyword"><=</SPAN> _) </CODE></BLOCKQUOTE><P></P></BLOCKQUOTE></DD><DD><P><A name="label658"></A> Accepts a connection from another socket.</P><P>The method suspends until a connection has been accepted or the number of milliseconds as specified by the time value in the <CODE>init</CODE> method has elapsed. After this period, no connection will be accepted, and both <CODE><I>PortIB</I></CODE> and <CODE><I>HostSB</I></CODE> are bound to <CODE><SPAN class="keyword">false</SPAN></CODE>.</P><P>If a connection is accepted within the given time, the following happens: <CODE><I>HostSB</I></CODE> and <CODE><I>PortIB</I></CODE> are bound accordingly if their fields are present.</P><P>If the fields <CODE>accepted</CODE> and <CODE>acceptClass</CODE> are present, <CODE><I>Object</I></CODE> is bound to an object created from the class <CODE><I>Class</I></CODE>. <CODE><I>Class</I></CODE> must be a sub class of <CODE>Open<SPAN class="keyword">.</SPAN>socket</CODE>. Then the accepted connection is available with <CODE><I>Object</I></CODE>.</P><P>Otherwise, the access to the socket at which the connection was accepted, because any subsequent message will refer to the accepted socket connection.</P><P>See also <CODE>accept(2)</CODE>. </P></DD><DT><CODE>connect</CODE> </DT><DD><BLOCKQUOTE class="synopsis"><P></P><BLOCKQUOTE class="code"><CODE>connect(host: </CODE><CODE>+<I>HostV</I></CODE><CODE> <SPAN class="keyword"><=</SPAN> localhost<BR> port: </CODE><CODE>+<I>PortI</I></CODE><CODE>)</CODE></BLOCKQUOTE><P></P></BLOCKQUOTE></DD><DD><P><A name="label660"></A> Connects to another socket.</P><P>The address of the socket to connect to is given by <CODE><I>HostV</I></CODE> and <CODE><I>PortI</I></CODE>.</P><P></P><DIV class="danger"><P class="margin"><IMG align="top" alt="Danger" src="danger.gif"></P><P>Be very careful in using this method: it blocks the entire Oz system until it succeeds.</P></DIV><P>See <CODE>connect(2)</CODE>. </P></DD><DT><CODE>server</CODE> </DT><DD><BLOCKQUOTE class="synopsis"><P></P><BLOCKQUOTE class="code"><CODE>server(port: </CODE><CODE>?<I>PortI</I></CODE><CODE> <BR> host: </CODE><CODE>?<I>HostV</I></CODE><CODE> <SPAN class="keyword"><=</SPAN> localhost)</CODE></BLOCKQUOTE><P></P></BLOCKQUOTE></DD><DD><P><A name="label662"></A> Initializes a stream socket as a server. </P></DD><DT><CODE>client</CODE> </DT><DD><BLOCKQUOTE class="synopsis"><P></P><BLOCKQUOTE class="code"><CODE>client(port: </CODE><CODE>+<I>PortI</I></CODE><CODE> <BR> host: </CODE><CODE>+<I>HostV</I></CODE><CODE> <SPAN class="keyword"><=</SPAN> localhost)</CODE></BLOCKQUOTE><P></P></BLOCKQUOTE></DD><DD><P><A name="label664"></A> Initializes a stream socket as a client. </P></DD><DT><CODE>read</CODE> </DT><DD><BLOCKQUOTE class="synopsis"><P></P><BLOCKQUOTE class="code"><CODE>read(list: </CODE><CODE>?<I>ListS</I></CODE><CODE> <BR> tail: </CODE><CODE><I>TailX</I></CODE><CODE> <SPAN class="keyword"><=</SPAN> nil <BR> size: </CODE><CODE>+<I>SizeAI</I></CODE><CODE> <SPAN class="keyword"><=</SPAN> 1024 <BR> len: </CODE><CODE>?<I>LenI</I></CODE><CODE> <SPAN class="keyword"><=</SPAN> _)</CODE></BLOCKQUOTE><P></P></BLOCKQUOTE></DD><DD><P><A name="label666"></A> Receives data from a stream-connected socket or from a datagram socket with peer specified.</P><P>An attempt is made to read <CODE><I>SizeAI</I></CODE> bytes from the socket. <CODE><I>ListS</I></CODE> is constrained to the data while the tail of <CODE><I>ListS</I></CODE> is constrained to <CODE><I>TailX</I></CODE>. The atom <CODE>all</CODE> is also a legal value for <CODE><I>SizeAI</I></CODE>. In this case the entire input is read.</P><P><CODE><I>LenI</I></CODE> is bound to the number of bytes actually read. If the socket is of type stream and the other end of the connection has been closed <CODE><I>LenI</I></CODE> is bound to <CODE>0</CODE>.</P><P>See also <CODE>read(2)</CODE>. </P></DD><DT><CODE>receive</CODE> </DT><DD><BLOCKQUOTE class="synopsis"><P></P><BLOCKQUOTE class="code"><CODE>receive(list: </CODE><CODE>?<I>ListS</I></CODE><CODE> <BR> tail: </CODE><CODE><I>TailX</I></CODE><CODE> <SPAN class="keyword"><=</SPAN> nil <BR> len: </CODE><CODE>?<I>LenI</I></CODE><CODE> <SPAN class="keyword"><=</SPAN> _ <BR> size: </CODE><CODE>+<I>SizeI</I></CODE><CODE> <SPAN class="keyword"><=</SPAN> 1024 <BR> host: </CODE><CODE>?<I>HostS</I></CODE><CODE> <SPAN class="keyword"><=</SPAN> _ <BR> port: </CODE><CODE>?<I>PortI</I></CODE><CODE> <SPAN class="keyword"><=</SPAN> _)</CODE></BLOCKQUOTE><P></P></BLOCKQUOTE></DD><DD><P><A name="label668"></A> Receives data from a socket.</P><P>An attempt is made to read <CODE><I>SizeI</I></CODE> bytes from the socket. <CODE><I>ListS</I></CODE> is bound to the data while the tail of the list is bound to <CODE><I>TailX</I></CODE>.</P><P><CODE><I>LenI</I></CODE> is bound to the number of bytes actually read. If the socket is of type stream and the other end of the connection has been closed <CODE><I>LenI</I></CODE> is bound to <CODE>0</CODE>.</P><P>The source of the data is signaled by binding <CODE><I>HostS</I></CODE> and <CODE><I>PortI</I></CODE>.</P><P>See also <CODE>recvfrom(2)</CODE>. </P></DD><DT><CODE>write</CODE> </DT><DD><BLOCKQUOTE class="synopsis"><P></P><BLOCKQUOTE class="code"><CODE>write(vs: </CODE><CODE>+<I>V</I></CODE><CODE> <BR> len: </CODE><CODE>?<I>I</I></CODE><CODE> <SPAN class="keyword"><=</SPAN> _)</CODE></BLOCKQUOTE><P></P></BLOCKQUOTE></DD><DD><P><A name="label670"></A> Writes the virtual string <CODE><I>V</I></CODE> to a stream-connected socket or to a datagram socket with peer specified.</P><P><CODE><I>I</I></CODE> is bound to the number of characters written.</P><P>See also <CODE>write(2)</CODE>. </P></DD><DT><CODE>send</CODE> </DT><DD><BLOCKQUOTE class="synopsis"><P></P><BLOCKQUOTE class="code"><CODE>send(vs: </CODE><CODE>+<I>V</I></CODE><CODE> <BR> len: </CODE><CODE>?<I>I</I></CODE><CODE> <SPAN class="keyword"><=</SPAN> _)<BR>send(vs: </CODE><CODE>+<I>V</I></CODE><CODE> <BR> len: </CODE><CODE>?<I>I</I></CODE><CODE> <SPAN class="keyword"><=</SPAN> _<BR> port: </CODE><CODE>+<I>PortI</I></CODE><CODE> <BR> host: </CODE><CODE>+<I>HostV</I></CODE><CODE> <SPAN class="keyword"><=</SPAN> localhost)</CODE></BLOCKQUOTE><P></P></BLOCKQUOTE></DD><DD><P><A name="label672"></A> Sends data as specified by <CODE><I>V</I></CODE> to a socket.</P><P>The destination of the data may be given by <CODE><I>HostV</I></CODE> and <CODE><I>PortI</I></CODE>. If they are omitted, the data is sent to the peer of a datagram socket or to the other end of a connection in case of a stream socket. <CODE><I>I</I></CODE> is bound to the number of characters written.</P><P>See also <CODE>send(2)</CODE>. </P></DD><DT><CODE>shutDown</CODE> </DT><DD><BLOCKQUOTE class="synopsis"><P></P><BLOCKQUOTE class="code"><CODE>shutDown(how: </CODE><CODE>+<I>HowAs</I></CODE><CODE> <SPAN class="keyword"><=</SPAN> [receive send])</CODE></BLOCKQUOTE><P></P></BLOCKQUOTE></DD><DD><P><A name="label674"></A> Disallows further actions on the socket.</P><P><CODE><I>HowAs</I></CODE> has to be a non-empty list which must contain only the atoms <CODE>receive</CODE> and <CODE>send</CODE>. The atom <CODE>send</CODE> signals that no further data transmission is allowed, while <CODE>receive</CODE> signals that no further data reception is allowed.</P><P>See also <CODE>shutdown(2)</CODE>. </P></DD><DT><CODE>close</CODE> </DT><DD><BLOCKQUOTE class="synopsis"><P></P><BLOCKQUOTE class="code"><CODE>close</CODE></BLOCKQUOTE><P></P></BLOCKQUOTE></DD><DD><P><A name="label676"></A> Closes the socket.</P><P>See also <CODE>close(2)</CODE> </P></DD><DT><CODE>flush</CODE> </DT><DD><BLOCKQUOTE class="synopsis"><P></P><BLOCKQUOTE class="code"><CODE>flush(how: </CODE><CODE>+<I>HowAs</I></CODE><CODE> <SPAN class="keyword"><=</SPAN> [receive send])</CODE></BLOCKQUOTE><P></P></BLOCKQUOTE></DD><DD><P><A name="label678"></A> Blocks until all requests for reading, receiving, writing, and sending have been fulfilled.</P><P><CODE><I>HowAs</I></CODE> must be a non-empty list which may include the atoms <CODE>receive</CODE> and <CODE>send</CODE>. The atom <CODE>send</CODE> signals that the method should block until all send (or write) requests are fulfilled, while <CODE>receive</CODE> signals the same for receive (or read). </P></DD><DT><CODE>dOpen</CODE> </DT><DD><BLOCKQUOTE class="synopsis"><P></P><BLOCKQUOTE class="code"><CODE>dOpen(</CODE><CODE>+<I>ReadFileDescI</I></CODE><CODE> </CODE><CODE>+<I>WriteFileDescI</I></CODE><CODE>)</CODE></BLOCKQUOTE><P></P></BLOCKQUOTE></DD><DD><P><A name="label680"></A></P><DIV class="danger"><P class="margin"><IMG align="top" alt="Danger" src="danger.gif"></P><P>Initializes the object. <CODE><I>ReadFileDescI</I></CODE> and <CODE><I>WriteFileDescI</I></CODE> must be integers of already open file descriptors (in the usual operating system sense).</P></DIV><P>Note that this method should only be used for advanced purposes. </P></DD><DT><CODE>getDesc</CODE> </DT><DD><BLOCKQUOTE class="synopsis"><P></P><BLOCKQUOTE class="code"><CODE>getDesc(</CODE><CODE>?<I>ReadFileDescIB</I></CODE><CODE> </CODE><CODE>?<I>WriteFileDescIB</I></CODE><CODE>)</CODE></BLOCKQUOTE><P></P></BLOCKQUOTE></DD><DD><P><A name="label682"></A></P><DIV class="danger"><P class="margin"><IMG align="top" alt="Danger" src="danger.gif"></P><P>Returns the internally used file descriptors.</P></DIV><P>If the object is not yet initialized, <CODE><I>ReadFileDescIB</I></CODE> and <CODE><I>WriteFileDescIB</I></CODE> are bound to <CODE><SPAN class="keyword">false</SPAN></CODE>, otherwise to the respective integers.</P><P>Note, that this method is only for advanced purposes.</P></DD></DL><P></P></DIV><DIV id="open.pipe"><H2><A name="open.pipe">20.4 The Class <CODE>Open<SPAN class="keyword">.</SPAN>pipe</CODE></A></H2><P><A name="label683"></A> The class <CODE>Open<SPAN class="keyword">.</SPAN>pipe</CODE> has the following public methods. </P><DL><DT><CODE>init</CODE> </DT><DD><BLOCKQUOTE class="synopsis"><P></P><BLOCKQUOTE class="code"><CODE>init(cmd: </CODE><CODE>+<I>CmdV</I></CODE><CODE> <BR> args: </CODE><CODE>+<I>ArgsVs</I></CODE><CODE> <SPAN class="keyword"><=</SPAN> nil <BR> pid: </CODE><CODE>?<I>PidI</I></CODE><CODE> <SPAN class="keyword"><=</SPAN> _)</CODE></BLOCKQUOTE><P></P></BLOCKQUOTE></DD><DD><P><A name="label685"></A> Initilizes the object and forks a process with process identification <CODE><I>PidI</I></CODE> executing the command <CODE><I>CmdV</I></CODE> with arguments <CODE><I>ArgsVs</I></CODE>. </P><P>The environment of the forked process is inherited from the process which runs the Oz Emulator. The standard input of the forked process is connected to sending and writing data, the standard output and standard error to reading and receiving data. </P><P>See also <CODE>execv(3)</CODE>, <CODE>fork(2)</CODE>. </P></DD><DT><CODE>read</CODE> </DT><DD><BLOCKQUOTE class="synopsis"><P></P><BLOCKQUOTE class="code"><CODE>read(list: </CODE><CODE>?<I>ListS</I></CODE><CODE> <BR> tail: </CODE><CODE><I>TailX</I></CODE><CODE> <SPAN class="keyword"><=</SPAN> nil <BR> size: </CODE><CODE>+<I>SizeAI</I></CODE><CODE> <SPAN class="keyword"><=</SPAN> 1024 <BR> len: </CODE><CODE>?<I>LenI</I></CODE><CODE> <SPAN class="keyword"><=</SPAN> _)</CODE></BLOCKQUOTE><P></P></BLOCKQUOTE></DD><DD><P><A name="label687"></A> Reads data <I>ListS</I> from the standard output or standard error of the forked process.</P><P>An attempt is made to read <CODE><I>SizeI</I></CODE> bytes. <CODE><I>ListS</I></CODE> is bound to the data read while the tail of <CODE><I>ListS</I></CODE> is bound to <CODE><I>TailX</I></CODE>. The atom <CODE>all</CODE> is also a legal value for <CODE><I>SizeAI</I></CODE>. In this case the entire input is read.</P><P><CODE><I>LenI</I></CODE> is bound to the number of bytes actually read. If the socket is of type stream and the other end of the connection has been closed <CODE><I>LenI</I></CODE> is bound to <CODE>0</CODE>.</P><P>See also <CODE>read(2)</CODE>. </P></DD><DT><CODE>write</CODE> </DT><DD><BLOCKQUOTE class="synopsis"><P></P><BLOCKQUOTE class="code"><CODE>write(vs: </CODE><CODE>+<I>V</I></CODE><CODE> <BR> len: </CODE><CODE>?<I>I</I></CODE><CODE> <SPAN class="keyword"><=</SPAN> _)</CODE></BLOCKQUOTE><P></P></BLOCKQUOTE></DD><DD><P><A name="label689"></A> Writes the virtual string <CODE><I>V</I></CODE> to the standard input of the forked process.</P><P><CODE><I>I</I></CODE> is bound to the number of characters written.</P><P>See also <CODE>write(2)</CODE>. </P></DD><DT><CODE>flush</CODE> </DT><DD><BLOCKQUOTE class="synopsis"><P></P><BLOCKQUOTE class="code"><CODE>flush(how: </CODE><CODE>+<I>HowAs</I></CODE><CODE> <SPAN class="keyword"><=</SPAN> [receive send])</CODE></BLOCKQUOTE><P></P></BLOCKQUOTE></DD><DD><P><A name="label691"></A> Blocks until all requests for reading and writing have been performed.</P><P><CODE><I>HowAs</I></CODE> must be a non-empty list which may include the atoms <CODE>receive</CODE> and <CODE>send</CODE>. The atom <CODE>send</CODE> signals that the method should block until all write requests are fulfilled, while <CODE>receive</CODE> signals the same for read. </P></DD><DT><CODE>close</CODE> </DT><DD><BLOCKQUOTE class="synopsis"><P></P><BLOCKQUOTE class="code"><CODE>close(</CODE><CODE>+<I>KillB</I></CODE><CODE><SPAN class="keyword"><=false</SPAN>)</CODE></BLOCKQUOTE><P></P></BLOCKQUOTE></DD><DD><P><A name="label693"></A> Closes the object. </P><P>If <CODE><I>KillB</I></CODE> is <CODE><SPAN class="keyword">false</SPAN></CODE> (the default) the method blocks until all pending read and write requests have been executed. If the started process is still running, it is killed by sending the <CODE>SIGTERM</CODE><A name="label694"></A> signal. However, note that the inverse direction is not supported, which means the object is not automatically closed if the process terminates. </P><P> If <CODE><I>KillB</I></CODE> is <CODE><SPAN class="keyword">true</SPAN></CODE> the possibly running process is immediately terminated by sending the <CODE>SIGKILL</CODE><A name="label695"></A> signal. </P><P>See also <CODE>wait(2)</CODE> and <CODE>kill(1)</CODE>. </P></DD><DT><CODE>dOpen</CODE> </DT><DD><BLOCKQUOTE class="synopsis"><P></P><BLOCKQUOTE class="code"><CODE>dOpen(</CODE><CODE>+<I>ReadFileDescI</I></CODE><CODE> </CODE><CODE>+<I>WriteFileDescI</I></CODE><CODE>)</CODE></BLOCKQUOTE><P></P></BLOCKQUOTE></DD><DD><P><A name="label697"></A></P><DIV class="danger"><P class="margin"><IMG align="top" alt="Danger" src="danger.gif"></P><P>Initializes the object. <CODE><I>ReadFileDescI</I></CODE> and <CODE><I>WriteFileDescI</I></CODE> must be integers of already open file descriptors (in the usual operating system sense).</P></DIV><P>Note that this method should only be used for advanced purposes. </P></DD><DT><CODE>getDesc</CODE> </DT><DD><BLOCKQUOTE class="synopsis"><P></P><BLOCKQUOTE class="code"><CODE>getDesc(</CODE><CODE>?<I>ReadFileDescIB</I></CODE><CODE> </CODE><CODE>?<I>WriteFileDescIB</I></CODE><CODE>)</CODE></BLOCKQUOTE><P></P></BLOCKQUOTE></DD><DD><P><A name="label699"></A></P><DIV class="danger"><P class="margin"><IMG align="top" alt="Danger" src="danger.gif"></P><P>Returns the internally used file descriptors.</P></DIV><P>If the object is not yet initialized, <CODE><I>ReadFileDescIB</I></CODE> and <CODE><I>WriteFileDescIB</I></CODE> are bound to <CODE><SPAN class="keyword">false</SPAN></CODE>, otherwise to the respective integers.</P><P>Note that this method is only for advanced purposes.</P></DD></DL><P></P></DIV><DIV id="sec-text-obj"><H2><A name="sec-text-obj">20.5 The Class <CODE>Open<SPAN class="keyword">.</SPAN>text</CODE></A></H2><P>The mixin class <CODE>Open<SPAN class="keyword">.</SPAN>text</CODE> has the methods listed below. Note, however, that it does not automatically cause a file to be opened in <CODE>text</CODE> mode; that must be done explicitly in the <CODE>init</CODE> method by supplying <CODE>text</CODE> as one of the flags. <A name="label700"></A> </P><DL><DT><CODE>getC</CODE> </DT><DD><BLOCKQUOTE class="synopsis"><P></P><BLOCKQUOTE class="code"><CODE>getC(</CODE><CODE>?<I>I</I></CODE><CODE>)</CODE></BLOCKQUOTE><P></P></BLOCKQUOTE></DD><DD><P><A name="label702"></A> Returns the next character, or <CODE><SPAN class="keyword">false</SPAN></CODE> if the input is at the end.</P><P>Note that if an object is created that inherits from both <CODE>Open<SPAN class="keyword">.</SPAN>text</CODE> and <CODE>Open<SPAN class="keyword">.</SPAN>file</CODE>, the methods <CODE>read</CODE> and <CODE>seek</CODE> from the classes <CODE>Open<SPAN class="keyword">.</SPAN>file</CODE>, <CODE>Open<SPAN class="keyword">.</SPAN>socket</CODE>, and <CODE>Open<SPAN class="keyword">.</SPAN>pipe</CODE> and do not work together with this method. </P></DD><DT><CODE>putC</CODE> </DT><DD><BLOCKQUOTE class="synopsis"><P></P><BLOCKQUOTE class="code"><CODE>putC(</CODE><CODE>+<I>I</I></CODE><CODE>)</CODE></BLOCKQUOTE><P></P></BLOCKQUOTE></DD><DD><P><A name="label704"></A> Writes the character <CODE><I>I</I></CODE>. </P></DD><DT><CODE>unGetC</CODE> </DT><DD><BLOCKQUOTE class="synopsis"><P></P><BLOCKQUOTE class="code"><CODE>unGetC</CODE></BLOCKQUOTE><P></P></BLOCKQUOTE></DD><DD><P><A name="label706"></A> The last character read is written back to the input buffer and may be used again by <CODE>getC</CODE>. It is allowed only to unget one character. </P></DD><DT><CODE>getS</CODE> </DT><DD><BLOCKQUOTE class="synopsis"><P></P><BLOCKQUOTE class="code"><CODE>getS(</CODE><CODE>?<I>SB</I></CODE><CODE>)</CODE></BLOCKQUOTE><P></P></BLOCKQUOTE></DD><DD><P><A name="label708"></A> Returns the next line of the input as string, or <CODE><SPAN class="keyword">false</SPAN></CODE> if the input is at the end. <CODE><I>SB</I></CODE> does not contain the newline character. </P><P>Note that if an object is created that inherits from both <CODE>Open<SPAN class="keyword">.</SPAN>text</CODE> and <CODE>Open<SPAN class="keyword">.</SPAN>file</CODE>, the methods <CODE>read</CODE> and <CODE>seek</CODE> from the class <CODE>Open<SPAN class="keyword">.</SPAN>file</CODE>, <CODE>Open<SPAN class="keyword">.</SPAN>socket</CODE>, and <CODE>Open<SPAN class="keyword">.</SPAN>pipe</CODE> do not work together with this method. </P></DD><DT><CODE>putS</CODE> </DT><DD><BLOCKQUOTE class="synopsis"><P></P><BLOCKQUOTE class="code"><CODE>putS(</CODE><CODE>+<I>V</I></CODE><CODE>)</CODE></BLOCKQUOTE><P></P></BLOCKQUOTE></DD><DD><P><A name="label710"></A> Writes the virtual string <CODE><I>V</I></CODE>. Note that a newline character is appended. </P></DD><DT><CODE>atEnd</CODE> </DT><DD><BLOCKQUOTE class="synopsis"><P></P><BLOCKQUOTE class="code"><CODE>atEnd(</CODE><CODE>?<I>B</I></CODE><CODE>)</CODE></BLOCKQUOTE><P></P></BLOCKQUOTE></DD><DD><P><A name="label712"></A> Tests whether the end of input is reached. </P></DD><DT><CODE>dOpen</CODE> </DT><DD><BLOCKQUOTE class="synopsis"><P></P><BLOCKQUOTE class="code"><CODE>dOpen(</CODE><CODE>+<I>ReadFileDescI</I></CODE><CODE> </CODE><CODE>+<I>WriteFileDescI</I></CODE><CODE>)</CODE></BLOCKQUOTE><P></P></BLOCKQUOTE></DD><DD><P><A name="label714"></A> </P><DIV class="danger"><P class="margin"><IMG align="top" alt="Danger" src="danger.gif"></P><P>Initializes the object. <CODE><I>ReadFileDescI</I></CODE> and <CODE><I>WriteFileDescI</I></CODE> must be integers of already open file descriptors (in the usual operating system sense).</P></DIV><P>Note that this method should only be used for advanced purposes. </P></DD><DT><CODE>getDesc</CODE> </DT><DD><BLOCKQUOTE class="synopsis"><P></P><BLOCKQUOTE class="code"><CODE>getDesc(</CODE><CODE>?<I>ReadFileDescIB</I></CODE><CODE> </CODE><CODE>?<I>WriteFileDescIB</I></CODE><CODE>)</CODE></BLOCKQUOTE><P></P></BLOCKQUOTE></DD><DD><P><A name="label716"></A> </P><DIV class="danger"><P class="margin"><IMG align="top" alt="Danger" src="danger.gif"></P><P>Returns the internally used file descriptors.</P></DIV><P>If the object is not yet initialized, <CODE><I>ReadFileDescIB</I></CODE> and <CODE><I>WriteFileDescIB</I></CODE> are bound to <CODE><SPAN class="keyword">false</SPAN></CODE>, otherwise to the respective integers.</P><P>Note that this method is only for advanced purposes.</P></DD></DL><P></P></DIV></DIV><TABLE align="center" border="0" cellpadding="6" cellspacing="6" class="nav"><TR bgcolor="#DDDDDD"><TD><A href="index.html">- Up -</A></TD><TD><A href="node56.html#chapter.os">Next >></A></TD></TR></TABLE><HR><ADDRESS><A href="http://www.ps.uni-sb.de/~duchier/">Denys Duchier</A>, <A href="http://www.ps.uni-sb.de/~kornstae/">Leif Kornstaedt</A>, <A href="http://www.ps.uni-sb.de/~homik/">Martin Homik</A>, <A href="http://www.ps.uni-sb.de/~tmueller/">Tobias Müller</A>, <A href="http://www.ps.uni-sb.de/~schulte/">Christian Schulte</A> and <A href="http://www.info.ucl.ac.be/~pvr">Peter Van Roy</A><BR><SPAN class="version">Version 1.4.0 (20110908185330)</SPAN></ADDRESS></BODY></HTML>
|