# Module `proc` - Process library

Process library.

The process library provides facilities for running other OS programs and manipulating the environment.

Some `PROC`s are also provided in `ALT`able versions; for more information on how to use these, see the `sock` module documentation.

To use this library:

    #INCLUDE "proc.module"

## Index

- Record `ENVIRONMENT` - An environment variable
  - Variable `ident` - Variable name
  - Variable `ident.size` - Length of variable name
  - Variable `value` - Variable value
  - Variable `value.size` - Length of variable value
- Process `proc.altable.run` - ALT able version of
- Process `proc.altable.wrapper` - ALT able version of
- Process `proc.os.getenv` - Get an environment variable
- Process `proc.os.setenv` - Set an environment variable
- Process `proc.os.setenv.array` - Set several environment variables
- Process `proc.run` - Run an external program
- Process `proc.setenv` - Fill in an record
- Process `proc.wrapper` - Run an external program with FDs connected to channels

## Declarations

### `proclib.inc`:24Record `ENVIRONMENT`

`DATA TYPE ENVIRONMENT`

An environment variable

### `proclib.inc`:26Variable `ident`

`[128]BYTE`

Variable name

### `proclib.inc`:27Variable `ident.size`

`INT`

Length of variable name

### `proclib.inc`:28Variable `value`

`[128]BYTE`

Variable value

### `proclib.inc`:29Variable `value.size`

`INT`

Length of variable value

### `proclib.occ`:77Process `proc.run`

`PROC proc.run (VAL []ENVIRONMENT env, VAL [][]BYTE command, VAL INT kyb.fd, scr.fd, err.fd, INT result)`

Run an external program.

The `command` array specifies the program name (the first element) and arguments (the remaining elements). The child process is executed using `execvp`, so the system path will be searched if the program name is not an absolute path to an executable. Elements of `command` must be padded with `'*0'` characters.

If any of the file descriptors are specified as `-1`, that descriptor will be closed in the child process. Since many programs will behave unpredictably if the standard file descriptors are closed when they are invoked, making use of this feature is not recommended.

#### Parameters:

`VAL []ENVIRONMENT` | `env` | Additional environment variables
`VAL [][]BYTE` | `command` | The process name and arguments
`VAL INT` | `kyb.fd` | File descriptor to connect to the child process's standard input
`VAL INT` | `scr.fd` | File descriptor to connect to the child process's standard output
`VAL INT` | `err.fd` | File descriptor to connect to the child process's standard error
`INT` | `result` | `-1` if an error occurred, otherwise the exit status of the process

### `proclib.occ`:86Process `proc.altable.run`

`PROC proc.altable.run (CHAN OF BOOL kill, CHAN OF INT response, VAL []ENVIRONMENT env, VAL [][]BYTE command, VAL INT kyb.fd, scr.fd, err.fd, INT result)`

`ALT`able version of `proc.run`.

### `proclib.occ`:140Process `proc.wrapper`

`PROC proc.wrapper (VAL []ENVIRONMENT env, VAL [][]BYTE command, CHAN OF BYTE kyb.in, scr.out, err.out, INT result)`

Run an external program with FDs connected to channels. Like `proc.run`, but the child process's standard input, output and error file descriptors are connected to the given occam channels.

For example:

    PROC lsdemo (CHAN BYTE kyb?, scr!, err!)
       VAL [][]BYTE command IS ["/bin/ls", ['-', 'a', 'l', 0, 0, 0, 0]]:
       INT result:
       SEQ
         proc.wrapper ([], command, kyb, scr, err, result)
     :

#### Parameters:

`VAL []ENVIRONMENT` | `env` | Additional environment variables
`VAL [][]BYTE` | `command` | The process name and arguments
`CHAN OF BYTE` | `kyb.in` | Channel to connect to the child process's standard input
`CHAN OF BYTE` | `scr.out` | Channel to connect to the child process's standard output
`CHAN OF BYTE` | `err.out` | Channel to connect to the child process's standard error
`INT` | `result` | `-1` if an error occurred, otherwise the exit status of the process

### `proclib.occ`:230Process `proc.altable.wrapper`

`PROC proc.altable.wrapper (CHAN OF BOOL kill, CHAN OF INT response, VAL []ENVIRONMENT env, VAL [][]BYTE command, CHAN OF BYTE kyb.in, scr.out, err.out, INT result)`

`ALT`able version of `proc.wrapper`.

### `proclib.occ`:306Process `proc.setenv`

`PROC proc.setenv (ENVIRONMENT env, VAL []BYTE ident, value)`

Fill in an `ENVIRONMENT` record. This copies the given values into the record, and also sets the size fields correctly.

#### Parameters:

`ENVIRONMENT` | `env` | The `ENVIRONMENT` to set
`VAL []BYTE` | `ident` | The variable name
`VAL []BYTE` | `value` | The variable value

### `proclib.occ`:321Process `proc.os.getenv`

`PROC proc.os.getenv (ENVIRONMENT env, VAL []BYTE ident)`

Get an environment variable. This reads the environment of the occam program.

#### Parameters:

`ENVIRONMENT` | `env` | Environment variable returned
`VAL []BYTE` | `ident` | The variable name to look up

### `proclib.occ`:333Process `proc.os.setenv`

`PROC proc.os.setenv (VAL ENVIRONMENT env)`

Set an environment variable. This sets a variable in the environment of the occam program (and thus in the environment of any programs it runs in the future).

#### Parameters:

`VAL ENVIRONMENT` | `env` | Environment variable to set

### `proclib.occ`:345Process `proc.os.setenv.array`

`PROC proc.os.setenv.array (VAL []ENVIRONMENT env)`

Set several environment variables. This is semantically equivalent to calling `proc.os.setenv` several times, but may be more efficient if you're setting several variables.

#### Parameters:

`VAL []ENVIRONMENT` | `env` | Environment variables to set