/usr/share/mozart/doc/system/node56.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>21 Operating System Support: OS</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="node55.html#chapter.open"><< Prev</A></TD><TD><A href="index.html">- Up -</A></TD><TD><A href="node57.html#chapter.pickle">Next >></A></TD></TR></TABLE><DIV id="chapter.os"><H1><A name="chapter.os">21 Operating System Support: <CODE>OS</CODE></A></H1><P>This chapter describes the procedures contained in the module <CODE>OS</CODE> </P><H2><A name="label717">21.1 Conventions</A></H2><P>Most procedures can be seen as straightforward lifting of POSIX compatible operating system functions to Oz. Hence, our description consists mainly of a reference to the relevant Unix manual page. If you are running on a Windows based platform you should consult a POSIX documentation (e. g. <A href="bib.html#lewine.91">[Lew91]</A>).</P><P>A major convention is that most <CODE><SPAN class="type">int</SPAN></CODE> arguments in C are integers in Oz. Moreover <CODE><SPAN class="type">char</SPAN>*</CODE> arguments are virtual strings, if they are used as input in C. If they are used as output in C they are strings. An n-ary C-function returning a value is implemented as a n+1-ary Oz procedure where the last argument serves as output position.</P><P>Whenever one needs predefined POSIX constants, they can be used as Oz atoms. Wherever bitwise disjunction of predefined constants is used in C, a list of atoms (the constant names) is allowed, which is interpreted as bitwise disjunction of their respective values.</P><P>The functionality of the module <CODE>OS</CODE> can be classified as procedures which are useful in applications, or procedures needed for building high level functionality. The latter are only interesting for programmers who want to build abstractions similar to those provided by the <CODE>Open</CODE> module.</P><H2><A name="label718">21.2 Exceptions</A></H2><P>If the operating system returns an error, an Oz Exception is raised which looks as follows: </P><BLOCKQUOTE class="code"><CODE>system(os(</CODE><CODE><I>A</I></CODE><CODE> </CODE><CODE><I>S1</I></CODE><CODE> </CODE><CODE><I>I</I></CODE><CODE> </CODE><CODE><I>S2</I></CODE><CODE>) debug:</CODE><CODE><I>X</I></CODE><CODE>)</CODE></BLOCKQUOTE><P> where: </P><OL type="1"><LI><P>The atom <CODE><I>A</I></CODE> gives the category of the error (e. g. <CODE>os</CODE> for operating system or <CODE>net</CODE> for network layer).</P></LI><LI><P>The string <CODE><I>S1</I></CODE> describes the operating system routine that raised the exception.</P></LI><LI><P>The integer <CODE><I>I</I></CODE> gives an operating system dependent error number.</P></LI><LI><P>The string <CODE><I>S2</I></CODE> describes the exception by some text.</P></LI><LI><P>The value <CODE><I>X</I></CODE> might contain some additional debug information.</P></LI></OL><P></P><H2><A name="label719">21.3 Random Integers</A></H2><P></P><DL><DT><CODE>rand</CODE> <A name="label721"></A></DT><DD><BLOCKQUOTE class="synopsis"><P><CODE>{OS<SPAN class="keyword">.</SPAN>rand </CODE><CODE>?<I>I</I></CODE><CODE>}</CODE></P></BLOCKQUOTE></DD><DD><P>Returns a randomly generated integer.</P><P>See <CODE>rand(3)</CODE>. </P></DD><DT><CODE>srand</CODE> <A name="label723"></A> </DT><DD><BLOCKQUOTE class="synopsis"><P><CODE>{OS<SPAN class="keyword">.</SPAN>srand </CODE><CODE>+<I>I</I></CODE><CODE>}</CODE></P></BLOCKQUOTE></DD><DD><P>Sets the seed for the random number generator used by <CODE>OS<SPAN class="keyword">.</SPAN>rand</CODE>. If <CODE><I>I</I></CODE> is <CODE>0</CODE>, the seed will be generated from the current time.</P><P>See <CODE>srand(3)</CODE>. </P></DD><DT><CODE>randLimits</CODE> </DT><DD><BLOCKQUOTE class="synopsis"><P><CODE>{OS<SPAN class="keyword">.</SPAN>randLimits </CODE><CODE>?<I>MinI</I></CODE><CODE> </CODE><CODE>?<I>MaxI</I></CODE><CODE>}</CODE></P></BLOCKQUOTE></DD><DD><P><A name="label725"></A> Binds <CODE><I>MinI</I></CODE> and <CODE><I>MaxI</I></CODE> to the smallest and greatest possible random number obtainable by <CODE>OS<SPAN class="keyword">.</SPAN>rand</CODE>.</P><P>See <CODE>rand(3)</CODE>.</P></DD></DL><P></P><H2><A name="label726">21.4 Files</A></H2><P></P><DL><DT><CODE>tmpnam</CODE> </DT><DD><BLOCKQUOTE class="synopsis"><P><CODE>{OS<SPAN class="keyword">.</SPAN>tmpnam </CODE><CODE>?<I>FileNameS</I></CODE><CODE>}</CODE></P></BLOCKQUOTE></DD><DD><P><A name="label728"></A> Returns a freshly created full pathname.</P><P>See <CODE>tmpnam(2)</CODE>. </P></DD><DT><CODE>unlink</CODE> </DT><DD><BLOCKQUOTE class="synopsis"><P><CODE>{OS<SPAN class="keyword">.</SPAN>unlink </CODE><CODE>+<I>PathV</I></CODE><CODE>}</CODE> <A name="label730"></A></P></BLOCKQUOTE></DD><DD><P>Removes the file with name <CODE><I>PathV</I></CODE>.</P><P>See <CODE>link(2)</CODE>.</P></DD></DL><P></P><H2><A name="label731">21.5 Directories</A></H2><P></P><DL><DT><CODE>getDir</CODE> </DT><DD><BLOCKQUOTE class="synopsis"><P><CODE>{OS<SPAN class="keyword">.</SPAN>getDir </CODE><CODE>+<I>PathV</I></CODE><CODE> </CODE><CODE>?<I>FileNameSs</I></CODE><CODE>}</CODE> <A name="label733"></A></P></BLOCKQUOTE></DD><DD><P>Returns a list of strings giving the files in the directory <CODE><I>PathV</I></CODE>.</P><P>See <CODE>opendir(3)</CODE> and <CODE>readdir(3)</CODE>. </P></DD><DT><CODE>getCWD</CODE> </DT><DD><BLOCKQUOTE class="synopsis"><P><CODE>{OS<SPAN class="keyword">.</SPAN>getCWD </CODE><CODE>?<I>FileNameS</I></CODE><CODE>}</CODE> <A name="label735"></A></P></BLOCKQUOTE></DD><DD><P>Returns in <CODE><I>FileNameS</I></CODE> the path of the current working directory.</P><P>See <CODE>getcwd(3)</CODE>. </P></DD><DT><CODE>stat</CODE> </DT><DD><BLOCKQUOTE class="synopsis"><P><CODE>{OS<SPAN class="keyword">.</SPAN>stat </CODE><CODE>+<I>PathV</I></CODE><CODE> </CODE><CODE>?<I>StatR</I></CODE><CODE>}</CODE> <A name="label737"></A></P></BLOCKQUOTE></DD><DD><P>Returns a record describing the status of the file <CODE><I>PathV</I></CODE>.</P><P><CODE><I>StatR</I></CODE> has features <CODE>size</CODE>, <CODE>type</CODE>, and <CODE>mtime</CODE>. The subtree at the feature <CODE>size</CODE> is an integer that gives the size of the file <CODE><I>PathV</I></CODE>. The subtree at the feature <CODE>type</CODE> is one of the following atoms: <CODE>reg</CODE> (regular file), <CODE>dir</CODE> (directory), <CODE>chr</CODE> (character special file), <CODE>blk</CODE> (block special file), <CODE>fifo</CODE> (pipe or FIFO special file), <CODE>unknown</CODE> (something else). <CODE>mtime</CODE> is the time of last modification measured in seconds since the dawn of the world, which, as we all know, was January 1, 1970.</P><P>See <CODE>stat(2)</CODE>. </P></DD><DT><CODE>chDir</CODE> </DT><DD><BLOCKQUOTE class="synopsis"><P><CODE>{OS<SPAN class="keyword">.</SPAN>chDir </CODE><CODE>+<I>PathV</I></CODE><CODE>}</CODE> <A name="label739"></A></P></BLOCKQUOTE></DD><DD><P>Changes the current working directory to <CODE><I>PathV</I></CODE>.</P><P>See <CODE>chdir(2)</CODE>. </P></DD><DT><CODE>mkDir</CODE> </DT><DD><BLOCKQUOTE class="synopsis"><P><CODE>{OS<SPAN class="keyword">.</SPAN>mkDir </CODE><CODE>+<I>PathV</I></CODE><CODE> </CODE><CODE>+<I>ModeAs</I></CODE><CODE>}</CODE> <A name="label741"></A></P></BLOCKQUOTE></DD><DD><P>Creates a directory <CODE><I>PathV</I></CODE>. Access modes are specified by <CODE><I>ModeAs</I></CODE>, similar to <CODE>OS<SPAN class="keyword">.</SPAN>open</CODE>.</P><P>See <CODE>mkdir(2)</CODE>. </P></DD></DL><P></P><DIV id="sec-opprog-os-file"><H2><A name="sec-opprog-os-file">21.6 Sockets</A></H2><P></P><DL><DT><CODE>getServByName</CODE> </DT><DD><BLOCKQUOTE class="synopsis"><P><CODE>{OS<SPAN class="keyword">.</SPAN>getServByName </CODE><CODE>+<I>NameV</I></CODE><CODE> </CODE><CODE>+<I>ProtoV</I></CODE><CODE> </CODE><CODE>?<I>PortIB</I></CODE><CODE>}</CODE> <A name="label743"></A></P></BLOCKQUOTE></DD><DD><P>Returns the port number <CODE><I>PortI</I></CODE> of a service <CODE><I>NameV</I></CODE> reachable in the Internet domain with the specified protocol <CODE><I>ProtoV</I></CODE>. </P><P>If the service is unknown, <CODE><SPAN class="keyword">false</SPAN></CODE> is returned.</P><P>As an example, the application </P><BLOCKQUOTE class="code"><CODE>{OS<SPAN class="keyword">.</SPAN>getServByName <SPAN class="string">"finger"</SPAN> <SPAN class="string">"tcp"</SPAN> Port}</CODE></BLOCKQUOTE><P> binds <CODE>Port</CODE> to the number, where you can connect to your local finger server.</P><P>See <CODE>getservbyname(3)</CODE>. </P></DD><DT><CODE>getHostByName</CODE> </DT><DD><BLOCKQUOTE class="synopsis"><P><CODE>{OS<SPAN class="keyword">.</SPAN>getHostByName </CODE><CODE>+<I>NameV</I></CODE><CODE> </CODE><CODE>?<I>HostentR</I></CODE><CODE>}</CODE> <A name="label745"></A></P></BLOCKQUOTE></DD><DD><P>Returns name information for the host <CODE><I>NameV</I></CODE>.</P><P>The record <I>HostentR</I> has the following features: </P><TABLE align="center" class="dyptic"><TR valign="top"><TD><P><CODE>name</CODE> </P></TD><TD><P>official host-name </P></TD><TD><P>string</P></TD></TR><TR valign="top"><TD><P><CODE>aliases</CODE> </P></TD><TD><P>alternative host-names </P></TD><TD><P>list of strings </P></TD></TR><TR valign="top"><TD><P><CODE>addrList</CODE> </P></TD><TD><P>Internet addresses </P></TD><TD><P>list of strings </P></TD></TR></TABLE><P></P><P>See <CODE>gethostbyname(3)</CODE>.</P></DD></DL><P></P></DIV><H2><A name="label746">21.7 Time</A></H2><P></P><DL><DT><CODE>time</CODE> </DT><DD><BLOCKQUOTE class="synopsis"><P><CODE>{OS<SPAN class="keyword">.</SPAN>time </CODE><CODE>?<I>TimeI</I></CODE><CODE>}</CODE> <A name="label748"></A></P></BLOCKQUOTE></DD><DD><P>Returns the time since 00:00:00 GMT, Jan. 1, 1970 in seconds.</P><P>See <CODE>time(2)</CODE>. </P></DD><DT><CODE>gmTime</CODE> </DT><DD><BLOCKQUOTE class="synopsis"><P><CODE>{OS<SPAN class="keyword">.</SPAN>gmTime </CODE><CODE>?<I>GmTimeR</I></CODE><CODE>}</CODE></P></BLOCKQUOTE></DD><DT><CODE>localTime</CODE> </DT><DD><BLOCKQUOTE class="synopsis"><P><CODE>{OS<SPAN class="keyword">.</SPAN>localTime </CODE><CODE>?<I>LocalTimeR</I></CODE><CODE>}</CODE> <A name="label750"></A> <A name="label752"></A></P></BLOCKQUOTE></DD><DD><P>Returns a description of the Coordinated Universal Time (UTC), respectively a description of the local time.</P><P>The records <CODE><I>GmTimeR</I></CODE> and <CODE><I>LocalTimeR</I></CODE> have the following features, where the fields are all integers: </P><TABLE align="center" class="dyptic"><TR valign="top"><TD><P><CODE>sec</CODE> </P></TD><TD><P>seconds </P></TD><TD><P>0 - 61 </P></TD></TR><TR valign="top"><TD><P><CODE>min</CODE> </P></TD><TD><P>minutes </P></TD><TD><P>0 - 59 </P></TD></TR><TR valign="top"><TD><P><CODE>hour</CODE> </P></TD><TD><P>hours </P></TD><TD><P>0 - 23 </P></TD></TR><TR valign="top"><TD><P><CODE>mDay</CODE> </P></TD><TD><P>day of month </P></TD><TD><P>1 - 31 </P></TD></TR><TR valign="top"><TD><P><CODE>mon</CODE> </P></TD><TD><P>month of year </P></TD><TD><P>0 - 11 </P></TD></TR><TR valign="top"><TD><P><CODE>year</CODE> </P></TD><TD><P>years since 1900 </P></TD><TD><P></P></TD></TR><TR valign="top"><TD><P><CODE>wDay</CODE> </P></TD><TD><P>days since Sunday </P></TD><TD><P>0 - 6 </P></TD></TR><TR valign="top"><TD><P><CODE>yDay</CODE> </P></TD><TD><P>day of year </P></TD><TD><P>0 - 365 </P></TD></TR><TR valign="top"><TD><P><CODE>isDst</CODE> </P></TD><TD><P>1 if daylight savings time in effect (DST) </P></TD><TD><P></P></TD></TR></TABLE><P></P><P>See <CODE>gmtime(3)</CODE>, <CODE>localtime(3)</CODE>, and <CODE>time(2)</CODE>.</P></DD></DL><P></P><H2><A name="label753">21.8 Environment Variables</A></H2><P></P><DL><DT><CODE>getEnv</CODE> </DT><DD><BLOCKQUOTE class="synopsis"><P><CODE>{OS<SPAN class="keyword">.</SPAN>getEnv </CODE><CODE>+<I>NameV</I></CODE><CODE> </CODE><CODE>?<I>ValueSB</I></CODE><CODE>}</CODE> <A name="label755"></A></P></BLOCKQUOTE></DD><DD><P>Returns the value of the environment variable <CODE><I>NameV</I></CODE>.</P><P>If a variable with the given name does not exist, the procedure returns <CODE><SPAN class="keyword">false</SPAN></CODE>.</P><P>As an example, consider: </P><BLOCKQUOTE class="code"><CODE>{OS<SPAN class="keyword">.</SPAN>getEnv <SPAN class="string">'OZHOME'</SPAN>}</CODE></BLOCKQUOTE><P> returns where the Oz system has been installed. This information is also available via <CODE>{System<SPAN class="keyword">.</SPAN>get home}</CODE> <A name="label756"></A> </P><P>See <CODE>getenv(3)</CODE>. </P></DD><DT><CODE>putEnv</CODE> </DT><DD><BLOCKQUOTE class="synopsis"><P><CODE>{OS<SPAN class="keyword">.</SPAN>putEnv </CODE><CODE>+<I>NameV</I></CODE><CODE> </CODE><CODE>+<I>ValueV</I></CODE><CODE>}</CODE> <A name="label758"></A></P></BLOCKQUOTE></DD><DD><P>Sets the value of the environment variable <CODE><I>NameV</I></CODE> to <CODE><I>ValueV</I></CODE>.</P><P>See <CODE>putenv(3)</CODE>. </P></DD></DL><P></P><DIV id="os-use-misc"><H2><A name="os-use-misc">21.9 Miscellaneous</A></H2><P></P><DL><DT><CODE>uName</CODE> </DT><DD><BLOCKQUOTE class="synopsis"><P><CODE>{OS<SPAN class="keyword">.</SPAN>uName </CODE><CODE>?<I>UtsnameR</I></CODE><CODE>}</CODE> <A name="label760"></A></P></BLOCKQUOTE></DD><DD><P>Returns system information.</P><P>The record <CODE><I>UtsnameR</I></CODE> has at least the following features, where all fields are strings: </P><TABLE align="center" class="dyptic"><TR valign="top"><TD><P><CODE>sysname</CODE> </P></TD><TD><P>operating system name </P></TD></TR><TR valign="top"><TD><P><CODE>nodename</CODE> </P></TD><TD><P>computer name</P></TD></TR><TR valign="top"><TD><P><CODE>release</CODE> </P></TD><TD><P>operating system release</P></TD></TR><TR valign="top"><TD><P><CODE>version</CODE> </P></TD><TD><P>operating system version</P></TD></TR><TR valign="top"><TD><P><CODE>machine</CODE> </P></TD><TD><P>machine architecture </P></TD></TR></TABLE><P></P><P>See <CODE>uname(2)</CODE>. </P></DD><DT><CODE>system</CODE> </DT><DD><BLOCKQUOTE class="synopsis"><P><CODE>{OS<SPAN class="keyword">.</SPAN>system </CODE><CODE>+<I>CmdV</I></CODE><CODE> </CODE><CODE>?<I>StatusI</I></CODE><CODE>}</CODE> <A name="label762"></A></P></BLOCKQUOTE></DD><DD><P>Starts a new operating system shell in which the OS command <CODE><I>CmdV</I></CODE> is executed. The status of the command is reported by <CODE><I>StatusI</I></CODE>.</P><P>See <CODE>system(3)</CODE>.</P></DD></DL><P></P></DIV><H2><A name="label763">21.10 Low Level Procedures</A></H2><P></P><H3><A name="label764">21.10.1 Basic Input and Output</A></H3><P></P><DL><DT><CODE>open</CODE> </DT><DD><BLOCKQUOTE class="synopsis"><P><CODE>{OS<SPAN class="keyword">.</SPAN>open </CODE><CODE>+<I>FileNameV</I></CODE><CODE> </CODE><CODE>+<I>FlagsAs</I></CODE><CODE> </CODE><CODE>+<I>ModeAs</I></CODE><CODE> </CODE><CODE>?<I>DescI</I></CODE><CODE>}</CODE> <A name="label766"></A></P></BLOCKQUOTE></DD><DD><P>Opens a file for reading and/or writing. </P><P><CODE><I>FlagsAs</I></CODE> must be a list with some of the following atoms as elements: </P><TABLE align="center" class="dyptic"><TR valign="top"><TD><P><CODE><SPAN class="string">'O_RDONLY'</SPAN></CODE> </P></TD><TD><P><CODE><SPAN class="string">'O_WRONLY'</SPAN></CODE> </P></TD><TD><P><CODE><SPAN class="string">'O_RDWR'</SPAN></CODE> </P></TD></TR><TR valign="top"><TD><P><CODE><SPAN class="string">'O_APPEND'</SPAN></CODE> </P></TD><TD><P><CODE><SPAN class="string">'O_CREAT'</SPAN></CODE> </P></TD><TD><P><CODE><SPAN class="string">'O_EXCL'</SPAN></CODE> </P></TD></TR><TR valign="top"><TD><P><CODE><SPAN class="string">'O_TRUNC'</SPAN></CODE> </P></TD><TD><P><CODE><SPAN class="string">'O_NOCCTY'</SPAN></CODE> </P></TD><TD><P><CODE><SPAN class="string">'O_NONBLOCK'</SPAN></CODE> </P></TD></TR><TR valign="top"><TD><P><CODE><SPAN class="string">'O_SYNC'</SPAN></CODE> </P></TD><TD><P></P></TD><TD><P></P></TD></TR></TABLE><P> Their meanings coincide with their usual POSIX meanings.</P><P>In the same manner <CODE><I>ModeAs</I></CODE> must be a list with elements drawn from: </P><TABLE align="center" class="dyptic"><TR valign="top"><TD><P><CODE><SPAN class="string">'S_IRUSR'</SPAN></CODE> </P></TD><TD><P><CODE><SPAN class="string">'S_IWUSR'</SPAN></CODE> </P></TD><TD><P><CODE><SPAN class="string">'S_IXUSR'</SPAN></CODE> </P></TD></TR><TR valign="top"><TD><P><CODE><SPAN class="string">'S_IRGRP'</SPAN></CODE> </P></TD><TD><P><CODE><SPAN class="string">'S_IWGRP'</SPAN></CODE> </P></TD><TD><P><CODE><SPAN class="string">'S_IXGRP'</SPAN></CODE> </P></TD></TR><TR valign="top"><TD><P><CODE><SPAN class="string">'S_IROTH'</SPAN></CODE> </P></TD><TD><P><CODE><SPAN class="string">'S_IWOTH'</SPAN></CODE> </P></TD><TD><P><CODE><SPAN class="string">'S_IXOTH'</SPAN></CODE> </P></TD></TR></TABLE><P></P><P>See <CODE>open(2)</CODE> and <CODE>chmod(2)</CODE>. </P></DD><DT><CODE>fileDesc</CODE> </DT><DD><BLOCKQUOTE class="synopsis"><P><CODE>{OS<SPAN class="keyword">.</SPAN>fileDesc </CODE><CODE>+<I>FileDescA</I></CODE><CODE> </CODE><CODE>?<I>FileDescIB</I></CODE><CODE>}</CODE> <A name="label768"></A></P></BLOCKQUOTE></DD><DD><P>Maps the atoms </P><TABLE align="center" class="dyptic"><TR valign="top"><TD><P><CODE><SPAN class="string">'STDIN_FILENO'</SPAN></CODE> </P></TD></TR><TR valign="top"><TD><P><CODE><SPAN class="string">'STDOUT_FILENO'</SPAN></CODE></P></TD></TR><TR valign="top"><TD><P><CODE><SPAN class="string">'STDERR_FILENO'</SPAN></CODE> </P></TD></TR></TABLE><P> to integers, giving their respective file descriptor. Note that these descriptors will be duplicated.</P><P>See <CODE>open(2)</CODE> and <CODE>dup(2)</CODE>. </P></DD><DT><CODE>read</CODE> </DT><DD><BLOCKQUOTE class="synopsis"><P><CODE>{OS<SPAN class="keyword">.</SPAN>read </CODE><CODE>+<I>DescI</I></CODE><CODE> </CODE><CODE>+<I>MaxI</I></CODE><CODE> </CODE><CODE>?<I>ListS</I></CODE><CODE> </CODE><CODE><I>TailX</I></CODE><CODE> </CODE><CODE>?<I>ReadI</I></CODE><CODE>}</CODE> <A name="label770"></A></P></BLOCKQUOTE></DD><DD><P>Reads data from a file or socket. Yields a list of characters in <CODE><I>ListS</I></CODE>, where the tail of the list is constrained to <CODE><I>TailX</I></CODE>.</P><P> Implements the <CODE>read(2)</CODE> system call. </P></DD><DT><CODE>write</CODE> </DT><DD><BLOCKQUOTE class="synopsis"><P><CODE>{OS<SPAN class="keyword">.</SPAN>write </CODE><CODE>+<I>DescI</I></CODE><CODE> </CODE><CODE>+<I>V</I></CODE><CODE> </CODE><CODE>?<I>StatusTI</I></CODE><CODE>}</CODE> <A name="label772"></A></P></BLOCKQUOTE></DD><DD><P>Writes the virtual string <CODE><I>V</I></CODE> to a file or a socket by using the function <CODE>write(2)</CODE>.</P><P>Illegal parts of the virtual string <CODE><I>V</I></CODE> are simply ignored, and the legal parts are written. </P><P>If <CODE><I>V</I></CODE> contains an undetermined variable, <CODE><I>StatusTI</I></CODE> is bound to a ternary tuple with label <CODE>suspend</CODE>. The first argument is an integer describing the portion already written, the second the undetermined variable, and the last to the not yet written part of <CODE><I>V</I></CODE>.</P><P>Otherwise <CODE><I>StatusTI</I></CODE> is bound to the number of characters written. </P></DD><DT><CODE>lSeek</CODE> </DT><DD><BLOCKQUOTE class="synopsis"><P><CODE>{OS<SPAN class="keyword">.</SPAN>lSeek </CODE><CODE>+<I>DescI</I></CODE><CODE> </CODE><CODE>+<I>WhenceA</I></CODE><CODE> </CODE><CODE>+<I>OffsetI</I></CODE><CODE> </CODE><CODE>?<I>WhereI</I></CODE><CODE>}</CODE> <A name="label774"></A></P></BLOCKQUOTE></DD><DD><P>Positions the seek pointer of a file. This procedure is implemented by the <CODE>lseek(2)</CODE> function. <CODE><I>WhenceA</I></CODE> must be one of the atoms <CODE><SPAN class="string">'SEEK_SET'</SPAN></CODE>, <CODE><SPAN class="string">'SEEK_CUR'</SPAN></CODE>, and <CODE><SPAN class="string">'SEEK_END'</SPAN></CODE>. </P></DD><DT><CODE>close</CODE> </DT><DD><BLOCKQUOTE class="synopsis"><P><CODE>{OS<SPAN class="keyword">.</SPAN>close </CODE><CODE>+<I>DescI</I></CODE><CODE>}</CODE> <A name="label776"></A></P></BLOCKQUOTE></DD><DD><P>Closes a file or socket by using the <CODE>close(2)</CODE> function.</P></DD></DL><P></P><DIV id="sec-opprog-select"><H3><A name="sec-opprog-select">21.10.2 From Blocking to Suspension</A></H3><P></P><DIV class="danger"><P class="margin"><IMG align="top" alt="Danger" src="danger.gif"></P><P>If reading from a file or a socket via an operating system function, it is possible that no information is available for reading. Furthermore, an attempt to write something to a file or to a socket might not be possible at a certain point in time. In this case the OS function blocks, i. e. the whole Oz Emulator process will stop doing any work.</P></DIV><P>To overcome this problem, we provide three procedures. These procedures will suspend rather than block.</P><P></P><DL><DT><CODE>acceptSelect</CODE> </DT><DD><BLOCKQUOTE class="synopsis"><P><CODE>{OS<SPAN class="keyword">.</SPAN>acceptSelect </CODE><CODE>+<I>DescI</I></CODE><CODE>}</CODE></P></BLOCKQUOTE></DD><DT><CODE>readSelect</CODE> </DT><DD><BLOCKQUOTE class="synopsis"><P><CODE>{OS<SPAN class="keyword">.</SPAN>readSelect </CODE><CODE>+<I>DescI</I></CODE><CODE>}</CODE></P></BLOCKQUOTE></DD><DT><CODE>writeSelect</CODE></DT><DD><BLOCKQUOTE class="synopsis"><P><CODE>{OS<SPAN class="keyword">.</SPAN>writeSelect </CODE><CODE>+<I>DescI</I></CODE><CODE>}</CODE> <A name="label778"></A> <A name="label780"></A> <A name="label782"></A></P></BLOCKQUOTE></DD><DD><P>Blocks until a socket connection can be accepted (data is present to be read, and writing of data is possible, respectively) at the file or socket with descriptor <CODE><I>DescI</I></CODE></P><P>For example the following case statement (we assume that <CODE>Desc</CODE> is bound to a descriptor of a socket): </P><BLOCKQUOTE class="code"><CODE>{OS<SPAN class="keyword">.</SPAN>readSelect Desc}<BR><SPAN class="keyword">case</SPAN> {OS<SPAN class="keyword">.</SPAN>read Desc 1024 ?S nil}<BR><SPAN class="keyword">of</SPAN> </CODE>...<CODE> <SPAN class="keyword">then</SPAN></CODE>...<CODE> <BR><SPAN class="keyword">end</SPAN></CODE></BLOCKQUOTE><P> blocks the current thread until data for reading is available. </P><P>This functionality is implemented by the <CODE>select(2)</CODE> system call.</P><P>Before actually closing a file descriptor, the following procedure needs to be called. </P></DD><DT><CODE>deSelect</CODE> </DT><DD><BLOCKQUOTE class="synopsis"><P><CODE>{OS<SPAN class="keyword">.</SPAN>deSelect </CODE><CODE>+<I>DescI</I></CODE><CODE>}</CODE> <A name="label784"></A></P></BLOCKQUOTE></DD><DD><P>Discards all threads depending on the file descriptor <CODE><I>DescI</I></CODE>.</P></DD></DL><P></P></DIV><H3><A name="label785">21.10.3 Sockets</A></H3><P></P><DL><DT><CODE>socket</CODE> </DT><DD><BLOCKQUOTE class="synopsis"><P><CODE>{OS<SPAN class="keyword">.</SPAN>socket </CODE><CODE>+<I>DomainA</I></CODE><CODE> </CODE><CODE>+<I>TypeA</I></CODE><CODE> </CODE><CODE>+<I>ProtoV</I></CODE><CODE> </CODE><CODE>?<I>DescI</I></CODE><CODE>}</CODE> <A name="label787"></A></P></BLOCKQUOTE></DD><DD><P>Creates a socket. Is implemented by the function <CODE>socket(2)</CODE>. </P><P><CODE><I>DomainA</I></CODE> must be either the atom <CODE><SPAN class="string">'PF_INET'</SPAN></CODE> or <CODE><SPAN class="string">'PF_UNIX'</SPAN></CODE>, whereas <CODE><I>TypeA</I></CODE> must be either <CODE><SPAN class="string">'SOCK_STREAM'</SPAN></CODE>, or <CODE><SPAN class="string">'SOCK_DGRAM'</SPAN></CODE>. </P><P><CODE><I>ProtoV</I></CODE> must be a virtual string. If it denotes the empty string, an appropriate protocol is chosen automatically, otherwise it must denote a valid protocol name like <CODE><SPAN class="string">"tcp"</SPAN></CODE> or <CODE><SPAN class="string">"udp"</SPAN></CODE>. </P></DD><DT><CODE>bind</CODE> </DT><DD><BLOCKQUOTE class="synopsis"><P><CODE>{OS<SPAN class="keyword">.</SPAN>bind </CODE><CODE>+<I>SockI</I></CODE><CODE> </CODE><CODE>+<I>PortI</I></CODE><CODE>}</CODE> <A name="label789"></A></P></BLOCKQUOTE></DD><DD><P>Binds a socket to its global name.</P><P>See <CODE>bind(2)</CODE>. </P></DD><DT><CODE>listen</CODE> </DT><DD><BLOCKQUOTE class="synopsis"><P><CODE>{OS<SPAN class="keyword">.</SPAN>listen </CODE><CODE>+<I>SockI</I></CODE><CODE> </CODE><CODE>+<I>BackLogI</I></CODE><CODE>}</CODE> <A name="label791"></A></P></BLOCKQUOTE></DD><DD><P>Indicates that a socket is willing to receive connections. </P><P>See <CODE>listen(2)</CODE>. </P></DD><DT><CODE>accept</CODE> </DT><DD><BLOCKQUOTE class="synopsis"><P><CODE>{OS<SPAN class="keyword">.</SPAN>accept </CODE><CODE>+<I>SockI</I></CODE><CODE> </CODE><CODE>?<I>HostS</I></CODE><CODE> </CODE><CODE>?<I>PortI</I></CODE><CODE> </CODE><CODE>?<I>DescI</I></CODE><CODE>}</CODE> <A name="label793"></A></P></BLOCKQUOTE></DD><DD><P>Accepts a connect request on a socket.</P><P><CODE><I>HostS</I></CODE> is bound to a string describing the host name. <A name="label795"></A> It is possible to use <CODE>OS<SPAN class="keyword">.</SPAN>acceptSelect</CODE> to block a thread until a connect attempt on this socket is made. </P><P>See <CODE>accept(2)</CODE> and <CODE>gethostbyaddr(3)</CODE>. </P></DD><DT><CODE>connect</CODE> </DT><DD><BLOCKQUOTE class="synopsis"><P><CODE>{OS<SPAN class="keyword">.</SPAN>connect </CODE><CODE>+<I>SockI</I></CODE><CODE> </CODE><CODE>+<I>HostV</I></CODE><CODE> </CODE><CODE>+<I>PortI</I></CODE><CODE>}</CODE> <A name="label797"></A></P></BLOCKQUOTE></DD><DD><P>Connects to a socket.</P><P>See <CODE>connect(2)</CODE> and <CODE>gethostbyaddr(3)</CODE>. </P></DD><DT><CODE>shutDown</CODE> </DT><DD><BLOCKQUOTE class="synopsis"><P><CODE>{OS<SPAN class="keyword">.</SPAN>shutDown </CODE><CODE>+<I>SockI</I></CODE><CODE> </CODE><CODE>+<I>HowI</I></CODE><CODE>}</CODE> <A name="label799"></A></P></BLOCKQUOTE></DD><DD><P>Signals that a socket is not longer interested in sending or receiving data. </P><P>See <CODE>shutdown(2)</CODE>. </P></DD><DT><CODE>getSockName</CODE> </DT><DD><BLOCKQUOTE class="synopsis"><P><CODE>{OS<SPAN class="keyword">.</SPAN>getSockName </CODE><CODE>+<I>SockI</I></CODE><CODE> </CODE><CODE>?<I>PortI</I></CODE><CODE>}</CODE> <A name="label801"></A></P></BLOCKQUOTE></DD><DD><P>Gets the name of a socket.</P><P>See <CODE>getsockname(3)</CODE>. </P></DD><DT><CODE>send</CODE> </DT><DD><BLOCKQUOTE class="synopsis"><P><CODE>{OS<SPAN class="keyword">.</SPAN>send </CODE><CODE>+<I>SockI</I></CODE><CODE> </CODE><CODE>+<I>MsgV</I></CODE><CODE> </CODE><CODE>+<I>FlagsAs</I></CODE><CODE> </CODE><CODE>?<I>LenI</I></CODE><CODE>}</CODE></P></BLOCKQUOTE></DD><DT><CODE>sendTo</CODE> </DT><DD><BLOCKQUOTE class="synopsis"><P><CODE>{OS<SPAN class="keyword">.</SPAN>sendTo </CODE><CODE>+<I>SockI</I></CODE><CODE> </CODE><CODE>+<I>MsgV</I></CODE><CODE> </CODE><CODE>+<I>FlagsAs</I></CODE><CODE> </CODE><CODE>+<I>HostV</I></CODE><CODE> </CODE><CODE>+<I>PortI</I></CODE><CODE>} </CODE><CODE>?<I>LenI</I></CODE><CODE>}</CODE> <A name="label803"></A> <A name="label805"></A></P></BLOCKQUOTE></DD><DD><P>Sends data from a socket.</P><P><CODE><I>FlagsAs</I></CODE> must be a list of atoms; its elements must be either <CODE><SPAN class="string">'MSG_OOB'</SPAN></CODE> or <CODE><SPAN class="string">'MSG_DONTROUTE'</SPAN></CODE>.</P><P>See <CODE>send(2)</CODE> and <CODE>gethostbyname(3)</CODE>. </P></DD><DT><CODE>receiveFrom</CODE> </DT><DD><BLOCKQUOTE class="synopsis"><P></P><BLOCKQUOTE class="code"><CODE>{OS<SPAN class="keyword">.</SPAN>receiveFrom </CODE><CODE>+<I>SockI</I></CODE><CODE> </CODE><CODE>+<I>MaxI</I></CODE><CODE> </CODE><CODE>+<I>FlagsAs</I></CODE><CODE> </CODE><CODE>?<I>MsgS</I></CODE><CODE> <BR> </CODE><CODE>+<I>TailX</I></CODE><CODE> </CODE><CODE>?<I>HostS</I></CODE><CODE> </CODE><CODE>?<I>PortI</I></CODE><CODE> </CODE><CODE>?<I>LenI</I></CODE><CODE>}</CODE></BLOCKQUOTE><P> <A name="label807"></A></P></BLOCKQUOTE></DD><DD><P>Receives data at a socket.</P><P><CODE><I>FlagsAs</I></CODE> must be a list of atoms; its elements must be either <CODE><SPAN class="string">'MSG_OOB'</SPAN></CODE> or <CODE><SPAN class="string">'MSG_PEEK'</SPAN></CODE>.</P><P>See <CODE>recvfrom(2)</CODE> and <CODE>gethostbyaddr(3)</CODE>.</P></DD></DL><P></P><H3><A name="label808">21.10.4 Process Control</A></H3><P></P><DL><DT><CODE>kill</CODE> </DT><DD><BLOCKQUOTE class="synopsis"><P><CODE>{OS<SPAN class="keyword">.</SPAN>kill </CODE><CODE>+<I>PidI</I></CODE><CODE> </CODE><CODE>+<I>SigA</I></CODE><CODE> </CODE><CODE>?<I>StatusI</I></CODE><CODE>}</CODE> <A name="label810"></A></P></BLOCKQUOTE></DD><DD><P>Implements the <CODE>kill(2)</CODE> function. <CODE><I>PidI</I></CODE> is the process identifier, <CODE><I>SigA</I></CODE> is an atom describing the signal to be sent: depending on the platform different signals are supported; at least the following signals are supported on all platforms: <CODE><SPAN class="string">'SIGTERM'</SPAN></CODE>, <CODE><SPAN class="string">'SIGINT'</SPAN></CODE>. </P></DD><DT><CODE>pipe</CODE> </DT><DD><BLOCKQUOTE class="synopsis"><P><CODE>{OS<SPAN class="keyword">.</SPAN>pipe </CODE><CODE>+<I>CmdV</I></CODE><CODE> </CODE><CODE>+<I>ArgsVs</I></CODE><CODE> </CODE><CODE>?<I>PidI</I></CODE><CODE> </CODE><CODE>?<I>StatusT</I></CODE><CODE>}</CODE> <A name="label812"></A></P></BLOCKQUOTE></DD><DD><P>Forks a OS process which executes the command <CODE><I>CmdV</I></CODE> with arguments <CODE><I>ArgsVs</I></CODE>. </P><P><CODE><I>PidI</I></CODE> is bound to the process identifier. <CODE><I>StatusT</I></CODE> is bound to a pair of socket or file descriptors where the standard input, the standard output and the standard error is redirected to. The first field of the pair is the descriptor for reading whereas the second field is the descriptor for writing.</P><P>See <CODE>socketpair(2)</CODE>, <CODE>fork(2)</CODE>, <CODE>execvp(2)</CODE>, and <CODE>execve(2)</CODE>. </P></DD><DT><CODE>wait</CODE> </DT><DD><BLOCKQUOTE class="synopsis"><P><CODE>{OS<SPAN class="keyword">.</SPAN>wait </CODE><CODE>?<I>PidI</I></CODE><CODE> </CODE><CODE>?<I>StatI</I></CODE><CODE>}</CODE> <A name="label814"></A></P></BLOCKQUOTE></DD><DD><P>Implements the <CODE>wait(2)</CODE> function. </P></DD><DT><CODE>getPID</CODE> </DT><DD><BLOCKQUOTE class="synopsis"><P><CODE>{OS<SPAN class="keyword">.</SPAN>getPID </CODE><CODE>?<I>PidI</I></CODE><CODE>}</CODE> <A name="label816"></A></P></BLOCKQUOTE></DD><DD><P>Returns the current process identifier as integer. See <CODE>getpid(2)</CODE>. </P></DD></DL><P></P></DIV><TABLE align="center" border="0" cellpadding="6" cellspacing="6" class="nav"><TR bgcolor="#DDDDDD"><TD><A href="node55.html#chapter.open"><< Prev</A></TD><TD><A href="index.html">- Up -</A></TD><TD><A href="node57.html#chapter.pickle">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>
|