========================================================
(C)1994 Institute for New Generation Computer Technology
(Read COPYRIGHT for detailed information.)
========================================================

Unix Interface
==============
February 8, 1994
Takashi Chikayama (ICOT)

This document describes the module "unix".

The "unix" module is for making interface with various features of the
UNIX operating system from within KL1 programs running on KLIC.


1. Obtaining UNIX Streams

The module "unix" interfaces other programs through message streams.
The stream can be obtained by calling the following predicate.

 unix:unix(S)
	A message stream corresponding to the UNIX interface is
	returned to S.

Most of the features of the UNIX interface are _not_ provided as
predicates, because no ordering is guaranteed between predicate calls
(Exceptions are explained in section 4).  For example:

	unix:cd(string#"a", 0),
	unix:cd(string#"b", 0),
	unix:system(string#"mkdir tmpdir", 0)

may list the directory "a" but may possibly list "b" or even some
other directory before doing any "cd", depending on the execution
order.  On the other hand:

	unix:unix([cd(string#"a", 0),
		   cd(string#"b", 0),
		   system(string#"ls", 0)])

will surely try two "cd" and "ls" in this order.

On parallel implementations, the process in which the unix stream is
obtained will be "the" process where all the messages are handled.
For example, "cd(Path)" message will change working directory of that
single process and that of no others.

Note: If you obtain two or more message streams, there will be no
automatic synchronization between messages sent to different streams.


2. Messages to the UNIX Streams

For the messages listed below, character string arguments should be
byte strings, rather than symbolic atoms.


2.1 Opening UNIX I/O Streams

The following messages open a UNIX I/O stream.  Messages to be sent to
UNIX I/O streams will be described in section 3.

 stdin(Result)
	Opens an input stream associated with process's standard
	input file, and returns "normal(Stream)" to Result.

 stdout(Result)
	Opens an output stream associated with process's standard
	output file, and returns "normal(Stream)" to Result.

 stderr(Result)
	Opens an output stream associated with process's standard
	error file, and returns "normal(Stream)" to Result.

 read_open(Path, Result)
	Opens an input stream from the file named by the string Path,
	and resturns "normal(Stream)" to Result.  If opening the file
	failed, "abnormal" is returned instead.

 write_open(Path, Result)
	Opens an output stream to the file named by the string Path,
	and resturns "normal(Stream)" to Result.  If opening the file
	failed, "abnormal" is returned instead.

 append_open(Path, Result)
	Opens an output stream to be appended to the file named by the
	string Path, and resturns "normal(Stream)" to Result.  If
	opening the file failed, "abnormal" is returned instead.

 update_open(Path, Result)
	Opens an input/output stream from/to the file named by the
	string Path, and resturns "normal(Stream)" to Result.  If
	opening the file failed, "abnormal" is returned instead.


2.2 Manipulation of Files and Directories

 cd(Path, Result)
	Changes the working directory to Path.  If successful, 0 is
	retuned to Result; otherwise, -1 is returned.  Corresponds to
	"chdir" system call.

 mktemp(Template, Filename)
	Makes a unique file name from the given Template and returns
	it to Filename.  Corresponds to the C library routine
	"mktemp".  Unlike the library routine, the template does *not*
	have to have six trailing Xs.  If a unique file name cannot be
	created somehow, a null string is returned to Filename.

 access(Path, Mode, Result)
	Checks accessibility of the file with pathname Path with the
	mode Mode is validate, and returns the result to Result.
	Corresponds to the C library routine "access".  If the file is
	accessible, 0 is returned; otherwise, -1 is returned.  Mode is
	an integer, with the bits of the following meaning.

		4	read permission
		2	write permission
		1	execute permission
		0	test existence

 chmod(Path, Mode, Result)
	Changes the permission mode of the file with pathname Path to
	Mode.  Corresponds to the system call "chmod".  If changing
	the mode is successful, 0 is returned to Result; otherwise, -1
	is returned.  Mode is an integer with standard UNIX permission
	bits.

 umask(CurrentMask)
	Returns the current file creation mask to CurrentMask.
	Corresponds to the "umask" system call.

 umask(OldMask, NewMask)
	Sets the file creation mask to NewMask and returns its
	original value to OldMask. Corresponds to the "umask" system
	call.


2.3 Miscellaneous

 system(Command, Result)
	Executes Command (a string) in a newly created subshell, and
	returns its exit code to Result.  Corresponds to the "system"
	system call.

 getenv(Name, Value)
	Returns the value of the environment variable with the name
	Name to Value.  Corresponds to the library routine "getenv".
	If such a environment variable does not exist, integer 0 is
	returned to Value.

 putenv(String, Result)
	String should be have form "Name=Value".  Adds or updates the
	environment variable Name with the value Value.  Corresponds
	to the library routine "putenv".  If addition or updating is
	successful, 0 is returned to Result.  Otherwise, non-zero
	integer value is returned.

 fork(Pid)
	Forks a new process which is a copy of the current process.
	Corresponds to the "fork" system call.  If a child process is
	succsessfully created, the process ID of the child process is
	returned to Pid in the parent process, and 0 is returned in
	the child process.

 fork_with_pipes(Result)
	Creates pipes and fork a new process.  The new process is a
	copy of the current process.  In the parent process, Result is
	unified with "parent(PID,In,Out)", where PID is the process ID
	of the newly created process.  In the newly create child
	process, Result is unified with "child(In,Out)".  In and Out
	are UNIX I/O streams to pipes; parent's Out is an output
	stream connected to child's In, which is an input stream;
	child's Out is connected to parent's In.


3. Messages to UNIX I/O Streams

3.1 Common Messages

The following messages are handled by all UNIX I/O streams.

 feof(Result)
	Returns 1 to Result if the stream is at the end of the file;
	otherwise 0.  Corresponds to the library routine "feof".

 fseek(Offset,Ptrname,Result)
	Changes the position of the stream according to the offset and
	pointer name given as Offset and Ptrname, respectively.  If
	successful, 0 is returned Result; otherwise -1.

 ftell(Result)
	Returns the offset of the current byte position to Result.

 fflush(Result)
	Flushes any output remaining on the stream.  Returns 0 to
	Result if successful; -1 otherwise.

 fclose(Result)
	Closes the stream.  Returns 0 to Result if successful; -1
	otherwise.  No messages except for sync/1 should be sent to a
	stream after closing.

 sync(Result)
	Returns 0 to Result.  Useful in making sure that all the
	preceding messages has already been processed.


3.2 Input Stream Messages

The following messages are handled by input streams and input/output
streams obtained by the above-described messages.

 getc(C)
	Reads one byte from the stream and returns it to C.  At EOF,
	-1 is returned.

 ungetc(C)
	Pushes back one byte C to the stream.

 fread(Max, String)
	Reads in up to Max bytes from the stream and returns the data
	as a byte string to String.  Only up to 4096 bytes can be
	handled in the current imlementation.  Note that the length of
	the resultant string may be smaller than given maximum.  This
	may happend on EOF for normal files and at any time for pipes
	or sockets (sockets are not provided yet).


3.3 Output Stream Messages

The following messages are handled by output streams and input/output
streams obtained by the above-described messages.

 putc(C)
	Put one byte C to the stream.

 fwrite(String, Result)
	Writes out the contents of the byte string String to the
	stream and returns number of bytes actually written to Result.
	Note that the number of bytes actually written may be smaller
	than the length of String.


4. Predicate Interface

The module also have the following predicate interfaces.

 unix:argc(Argc)
	Number of command line arguments not used by the KLIC system
	is returned to Argc.  Such arguments starts from the first
	argument not beginning with '-' or after "--" in the command
	line.

 unix:argv(L)
	Command line arguments nod used by the KLIC system is returned
	to L as a list of strings.

 unix:exit(N)
	Terminates the process immediately with the exit code N.

5. Bugs

- More system calls and library routines should be supported.

- Different specification may be needed for parallel implementations.
