mod_proc

Name

mod_proc – Process control module for Lite / W3-mSQL

Synopsis

modload "mod_proc";

Caveats

It is assumed that the reader is familiar with both programming in the Lite / W3-mSQL language and with the concepts of basic process control under the UNIX operating system.

Details

mod_proc extends Lite by adding several functions related to the simple handling of UNIX processes. It is in now way a complete interface to all process related functions and system calls provided by UNIX. The functionality provided allows for the basic creation of processes, inter process communication, and management of process termination. The functions provided by this module are

fork( ) - create a new process

The fork() function creates a new process that is identical to the currently running process in all all aspects except the reutn value of the fork() function itself. The return value provided to the original process is the process ID (PID) of the new child process. The new child process will be returned a value of 0. In the event of an error, the original process will be returned a value of -1 and the $ERRMSG variable will be set with a textual explanation of the error. This function does not require or accept any parameters.

exec( char $path, array $args ) - execute a new program in the current process

The exec() function executes a new program within the current process and destroys the original contents of the process. If this function returns then the execution of the new program has failed and $ERRMSG will contain a textual explanation of the failure. The function requires two parameters, the path of the program to be executed and an array of parameters to be passed to the new program as command line arguments, the new program's argument vector. As expected, element zero of the parameter array will be passed as argv[0] to the new program etc.

pipe( ) - create a pipe that may be used for inter process communication

The pipe() function creates a standard UNIX pipe. The function returns an array of two integer values that reflect the read and write descriptors for the pipe respectively. The descriptors are retained during calls to fork() so they may be used to send data from one process to another. Care should be taken to close the unwanted end of the pipe in each process to ensure that end-of-file conditions are generated properly. If the creation of the pipe failed, an empty array will be returned and $ERRMSG will be contain an explanation of the failure. This condition may be checked using the count operator ( # ) on the return value. A value of " if ( # $result == 0 ) " will indicate an error.

dup2( int $fd1, int $fd2 ) - duplicate a file descriptor

The dup2() function duplicates the descriptor associated with $fd1 and allows it to be referenced using the value of $fd2 (see the UNIX man page for dup2 for further details). If the duplication failed, the function will return a value of -1 and the contents of $ERRMSG will be set to an explanation of the failure.

wait( int $pid ) - wait for a child process to terminate

The wait() function will wait for and clean up after the termination of a child process. If a value of zero is passed to the function it behaves as the UNIX wait() function would. If a non-zero value is passed, it behaves like the UNIX waitpid() function. In the former case it will return after the termination of any child process (or immediately if a child has already terminated and has not been cleaned up). In the latter case, it will wait specifically for the identified process to terminate. In either case, a return value of -1 indicates an error condition and $ERRMSG will be set to an explanation of the error.

Function List

Create a new process	int fork();
Execute a new program image	int exec($path, $args) char $path; array $args;
Create an IPC pipe	array pipe();
Duplicate a file descriptor	int dup2($fd1, $fd2) int $fd1, $fd2;
Wait for a child process	int wait($pid) int $pid;

Example

Author