1% BEGIN LICENSE BLOCK 2% Version: CMPL 1.1 3% 4% The contents of this file are subject to the Cisco-style Mozilla Public 5% License Version 1.1 (the "License"); you may not use this file except 6% in compliance with the License. You may obtain a copy of the License 7% at www.eclipse-clp.org/license. 8% 9% Software distributed under the License is distributed on an "AS IS" 10% basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See 11% the License for the specific language governing rights and limitations 12% under the License. 13% 14% The Original Code is The ECLiPSe Constraint Logic Programming System. 15% The Initial Developer of the Original Code is Cisco Systems, Inc. 16% Portions created by the Initial Developer are 17% Copyright (C) 1994 - 2006 Cisco Systems, Inc. All Rights Reserved. 18% 19% Contributor(s): 20% 21% END LICENSE BLOCK 22% 23% @(#)umsopsys.tex 1.5 94/07/15 24% 25% 26% umsopsys.tex 27% 28% REL DATE AUTHOR DESCRIPTION 29% 29.5.90 Joachim Schimpf 30% 31\chapter{Operating System Interface} 32%HEVEA\cutdef[1]{section} 33\label{chapopsys} 34 35\section{Introduction} 36 37{\eclipse}'s operating system interface consists of a collection of built-in 38predicates and some global flags that are accessed with 39\bipref{set_flag/2}{../bips/kernel/env/set_flag-2.html}, 40\bipref{get_flag/2}{../bips/kernel/env/get_flag-2.html} and 41\bipref{env/0}{../bips/kernel/env/env-0.html}. They are described in the 42following sections. 43The interface is mostly compatible across Unix and Windows operating systems. 44 45\section{Environment Access} 46A number of predicates and global flags is provided to get more or less 47useful information from the operating system environment. 48\subsection{Command Line Arguments} 49Arguments provided on the UNIX (or DOS) command line are accessed by the 50built-ins 51\index{command line options} 52\indextt{argc/1} 53\indextt{argv/2} 54\bipref{argc/1}{../bips/kernel/opsys/argc-1.html} which gives the number of 55command line arguments (including 56the command name itself) and \bipref{argv/2}{../bips/kernel/opsys/argv-2.html} 57which returns a requested positional 58argument in string form. If the first argument of \predspec{argv/2} is the atom 59all, then a list of all command line arguments is returned. 60 61\subsection{Environment Variables} 62On UNIX, environment variables are another way to pass information to the 63{\eclipse} process. Their string value can be read using 64\bipref{getenv/2}{../bips/kernel/opsys/getenv-2.html}: 65\begin{quote} 66\begin{verbatim} 67[eclipse 1]: getenv('HOME', Home). 68 69Home = "/usr/octopus" 70yes. 71\end{verbatim} 72\end{quote} 73 74The environment variables available on Window is version dependent, and is 75not a recommended method of passing information. 76 77\subsection{Exiting {\eclipse}} 78When {\eclipse} is exited, it can give a return code to the operating system. 79This is done by using \bipref{exit/1}{../bips/kernel/opsys/exit-1.html}. It 80exits {\eclipse} and returns its integer 81argument to the operating system. 82\indextt{exit/1} 83\indextt{halt/0} 84\begin{quote} 85\begin{verbatim} 86[eclipse 1]: exit(99). 87csh% echo $status 8899 89\end{verbatim} 90\end{quote} 91Note that \notation{halt} is equivalent to \notation{exit(0)}. 92 93\subsection{Time and Date} 94The current date can be obtained in the form of a UNIX date string: 95\begin{quote} 96\begin{verbatim} 97[eclipse 1]: date(Today). 98 99Today = "Tue May 29 20:49:39 1990\n" 100yes. 101\end{verbatim} 102\end{quote} 103The library \libspec{calendar} contains a utility predicate to convert 104this string into a Prolog structure. 105Another way to access the current time and date is the global flag 106\notation{unix_time}. It returns the current time in the traditional UNIX 107measure, i.e., in seconds since 00:00:00 GMT Jan 1, 1970: 108\begin{quote} 109\begin{verbatim} 110[eclipse 1]: get_flag(unix_time, Now). 111 112Now = 644008011 113yes. 114\end{verbatim} 115\end{quote} 116Other interesting timings concern the resource usage of the running {\eclipse}. 117The \bipref{statistics/2}{../bips/kernel/env/statistics-2.html} built-in gives 118three different times, the user 119cpu time, the system cpu time and the elapsed real time since 120the process was started (all in seconds): 121\begin{quote} 122\begin{verbatim} 123[eclipse 1]: statistics(times, Used). 124 125Used = [0.916667, 1.61667, 2458.88] 126yes. 127\end{verbatim}\end{quote} 128The first figure (user cpu time) is the same as given by 129\bipref{cputime/1}{../bips/kernel/opsys/cputime-1.html}. 130 131\subsection{Host Computer} 132Access to the name and unique identification of the host computer where 133the system is running can be obtained by the two global flags 134\notationidx{hostname} and \notationidx{hostid}, accessed via 135\bipref{get_flag/2}{../bips/kernel/env/get_flag-2.html} or 136\bipref{env/0}{../bips/kernel/env/env-0.html}. These flags might not be 137available on all machines, 138\bipref{get_flag/2}{../bips/kernel/env/get_flag-2.html} fails in these cases. 139 140\subsection{Calling C Functions} 141Other data may be obtained with the predicate 142\bipref{call_c/2}{../bips/kernel/externals/call_c-2.html} 143which allows to call directly any C function which is 144linked to the Prolog system. 145Functions which are not linked can be loaded dynamically with the 146\bipref{load/1}{../bips/kernel/externals/load-1.html} predicate. 147 148 149\section{File System} 150A number of built-in predicates is provided for dealing with files and 151directories. 152Here we consider only the file as a whole, for opening files and accessing 153their contents refer to chapter \ref{chapio}. 154 155\subsection{Current Directory} 156The current working directory is an important notion in UNIX. 157It can be read and changed within the {\eclipse} system by using 158\bipref{getcwd/1}{../bips/kernel/opsys/getcwd-1.html} and 159\bipref{cd/1}{../bips/kernel/opsys/cd-1.html} respectively. 160The current working directory is accessible as a global flag as well. 161Reading and writing this flag is equivalent to the use of 162\bipref{getcwd/1}{../bips/kernel/opsys/getcwd-1.html} and 163\bipref{cd/1}{../bips/kernel/opsys/cd-1.html}: 164\begin{quote} 165\begin{verbatim} 166[eclipse 1]: getcwd(Where). 167 168Where = "/usr/name/prolog" 169yes. 170[eclipse 2]: cd(..). 171 172yes. 173[eclipse 3]: get_flag(cwd, Where) 174 175Where = "/usr/name" 176yes. 177\end{verbatim} 178\end{quote} 179All {\eclipse} built-ins that take file names as arguments accept absolute 180pathnames as well as relative pathnames starting at the current directory. 181 182\subsection{Looking at Directories} 183To look at the contents of a directory, 184\bipref{read_directory/4}{../bips/kernel/opsys/read_directory-4.html} is 185available. 186It takes a directory pathname and a file name pattern and returns a list 187of subdirectories and a list of files matching the pattern. 188The following metacharacters are recognised in the pattern: 189\notation{*} matches an arbitrary sequence of characters, 190\notation{?} matches any single character, \notation{[]} matches one of the 191characters inside the brackets unless the first one is a \verb:^:, 192in which case it matches any character but those inside the brackets. 193\begin{quote} 194\begin{verbatim} 195[eclipse 1]: read_directory("/usr/john", "*", Dirlist, Filelist). 196Dirlist = ["subdir1", "subdir2"] 197Filelist = ["one.c", "two.c", "three.pl", "four.pl"] 198yes. 199\end{verbatim} 200\end{quote} 201 202\subsection{Checking Files} 203For checking the existence of files, 204\bipref{exists/1}{../bips/kernel/opsys/exists-1.html} or the more powerful 205\bipref{existing_file/4}{../bips/kernel/opsys/existing_file-4.html} is used. 206For accessing any file properties there is 207\bipref{get_file_info/3}{../bips/kernel/opsys/get_file_info-3.html}. 208It can return file permissions, type, owner, size, inode, number of 209links as well as creation, access and modification times 210(as defined by the UNIX system call \notation{stat(2)}; not all entries are 211meaningful under Windows), and accessibility 212information. 213It fails when the specified file does not exist. 214Refer to the reference manual or \bipref{help/1}{../bips/kernel/env/help-1.html} 215for details. 216 217\subsection{Renaming and Removing Files} 218For these basic operations with files, 219\bipref{rename/2}{../bips/kernel/opsys/rename-2.html} and 220\bipref{delete/1}{../bips/kernel/opsys/delete-1.html} 221are provided. 222 223\subsection{File names} 224The file names used by {\eclipse} is in the Unix format, including on Window 225platforms, with the addition that the disk such as \notation{C:} is 226indicated by \notation{//C/}, so a Windows file name such as 227\verb+"C:\my\path\name.ecl"+ should be writen as 228\verb+"//C/my/path/name.pl"+. The utility predicate 229\bipref{os_file_name/2}{../bips/kernel/opsys/os_file_name-2.html} provides for 230the conversion between the format used in {\eclipse} and the Operating 231Systems' format. 232 233The utility \bipref{pathname/4}{../bips/kernel/opsys/pathname-4.html} 234is provided to ease the handling of file names. 235It takes a full pathname and cuts it into the directory 236pathname, the file name proper and a suffix ( 237the part beginning with the last dot in the string). 238It also expands symbolic pathnames, starting with \verb:~:, 239\verb:~:\notation{\pattern{user}} or \notation{\$var}. 240\begin{quote} 241\begin{verbatim} 242[eclipse 1]: Name = "~octopus/prolog/file.pl", 243 pathname(Name, Path, File, Suffix). 244 245Path = "/usr/octopus/prolog/" 246File = "file.pl" 247Name = "~octopus/prolog/file.pl" 248Suffix = ".pl" 249yes. 250\end{verbatim} 251\end{quote} 252 253 254\section{Creating Communicating Processes} 255{\eclipse} provides all the necessary built-ins needed to create UNIX processes 256and establish communication between them. 257A {\eclipse} process can communicate with other processes via streams and by 258sending and receiving signals. 259 260\subsection{Process creation} 261 262The built-ins of the \predspec{exec} group and 263\bipref{sh/1}{../bips/kernel/opsys/sh-1.html} 264fork a new process and execute the command given as the first argument. 265Sorted by their versatility, there are: 266\begin{itemize} 267\item \preddef{sh(\pattern{Command})}\indextt{sh/1} 268\item \preddef{exec(\pattern{Command},~\pattern{Streams})}\indextt{exec/2} 269\item \preddef{exec(\pattern{Command},~\pattern{Streams},~\pattern{ProcessId})}% 270\indextt{exec/3} 271\item \preddef{% 272exec_group(\pattern{Command},~\pattern{Streams},~\pattern{ProcessId})}% 273\indextt{exec_group/3} 274\end{itemize} 275With \bipref{sh/1}{../bips/kernel/opsys/sh-1.html} (or its synonym 276\bipref{system/1}{../bips/kernel/opsys/system-1.html}) it is possible to 277call and execute any UNIX command from withing {\eclipse}. 278However it is not possible to communicate with the process. 279Moreover, the {\eclipse} process just waits until the command has been executed. 280 281The \predspec{exec} group makes it possible to set up communication links 282with the child process by specifying the \about{Streams} argument. 283It is a list of the form 284\begin{quote} 285\begin{verbatim} 286[Stdin, Stdout, Stderr] 287\end{verbatim} 288\end{quote} 289and specifies which {\eclipse} stream should be connected to the 290\notation{stdin}, \notation{stdout} or \notation{stderr} streams of the child 291respectively. 292Unless \notation{null} is specified, this will establish pipes to be 293created between the {\eclipse} process and the child. 294On Berkeley UNIX systems the streams can be specified as 295\notation{sigio(Stream)} 296which will setup the pipe such that the signal \notation{sigio} is issued 297every time new data appears on the pipe. 298Thus, by defining a suitable interrupt handler, it is possible to service this 299stream in a completely asynchronous way. 300 301\subsection{Process control} 302The \bipref{sh/1}{../bips/kernel/opsys/sh-1.html} and 303\bipref{exec/2}{../bips/kernel/opsys/exec-2.html} built-ins both block the 304{\eclipse} process until 305the child has finished. 306For more sophisticated applications, the processes have to run in parallel 307and be synchronised explicitly. 308This can be achieved with \bipref{exec/3}{../bips/kernel/opsys/exec-3.html} or 309\bipref{exec_group/3}{../bips/kernel/opsys/exec_group-3.html}. 310These return immediately after having created the child process and 311unify its process identifier (\about{Pid}) with the their argument. 312The \about{Pid} can be used to 313\begin{itemize} 314\item send signals to the process, using the built-in 315 \preddef{kill(\pattern{Pid},~\pattern{Signal})};\indextt{kill/2} 316\item wait for the process to terminate and obtain its return status: 317 \preddef{wait(\pattern{Pid},~\pattern{Status})}.\indextt{wait/2} 318\end{itemize} 319The difference between \bipref{exec/3}{../bips/kernel/opsys/exec-3.html} and 320\bipref{exec_group/3}{../bips/kernel/opsys/exec_group-3.html} is 321that the latter creates a 322new process group for the child, such that the child does not get the 323interrupt, hangup and kill signals that are sent to the parent. 324 325The process identifier of the running {\eclipse} and of its parent process are 326available as the global flags 327\notation{pid}\index{pid@\notation{pid} (global flag)} 328and 329\notation{ppid}\index{ppid@\notation{ppid} (global flag)} 330respectively. 331They can be accessed using 332\bipref{get_flag/2}{../bips/kernel/env/get_flag-2.html} or 333\bipref{env/0}{../bips/kernel/env/env-0.html}. 334 335Here is an example of how to connect the UNIX utility \notation{bc} (the 336arbitrary-precision arithmetic language) to a {\eclipse} process. 337We first create the process with two pipes for the child's standard input 338and output. 339Then, by writing and reading these streams, the processes can communicate in 340a straightforward way. Note that it is usually necessary to flush the 341output after writing into a pipe: 342\begin{quote} 343\begin{verbatim} 344[eclipse 1]: exec(bc, [in,out], P). 345 346P = 9759 347yes. 348[eclipse 2]: writeln(in, "12345678902321 * 2132"), flush(in). 349 350yes. 351[eclipse 3]: read_string(out, end_of_line, "", _, Result). 352 353Result = "26320987419748372" 354yes. 355\end{verbatim} 356\end{quote} 357In this example the child process can be terminated by closing its standard 358input (in other cases it may be necessary to send a signal). 359The built-in \bipref{wait/2}{../bips/kernel/opsys/wait-2.html} is then used to 360wait for the process to terminate 361and to obtain its exit status. 362Don't forget to close the {\eclipse} streams that were opend by 363\bipref{exec/3}{../bips/kernel/opsys/exec-3.html}: 364\begin{quote} 365\begin{verbatim} 366[eclipse 4]: close(in), wait(P,S). 367 368P = 9759 369S = 0 More? (;) 370yes. 371[eclipse 5]: at_eof(out), close(out). 372 373yes. 374\end{verbatim} 375\end{quote} 376 377\subsection{Interprocess Signals} 378The UNIX (or the appropriate Windows) signals are all mapped to {\eclipse} 379interrupts. 380Their names and numbers may vary on different machines. 381Refer to the operating system documentation for details. 382 383The way to deal with incoming signals is to define a Prolog or external 384predicate and declare it as the interrupt handler for this interrupt 385(using 386\bipref{set_interrupt_handler/2}{../bips/kernel/event/set_interrupt_handler-2.html}). 387Interrupt handlers can be established for all signals except those that are 388not allowed to be caught by the process (like e.g., the \notation{kill} signal 3899). 390For a description of event handling in general see chapter \ref{chapexcept}. 391 392For explicitly sending signals to other processes 393\bipref{kill/2}{../bips/kernel/opsys/kill-2.html} is provided, 394which is a direct interface to the UNIX system call \notation{kill(2)}. 395Note that some signals can be set up to be raised automatically, 396e.g., \notation{sigio} can be raised when data arrives on a pipe. 397 398 399%HEVEA\cutend 400