COSHELL(3)

NAME
coshell - shell coprocess support

SYNOPSIS

DESCRIPTION
The coshell routines support the shell as a coprocess. This coprocess may be either ksh(1) or sh(1) executing on the local host, or it may be coshell(1) with access to shells on hosts throughout the local network.

The coshell inherits the environment of the calling process. Signals sent to the calling process are passed to the coshell.

Returns a pointer to a new coshell. is returned on error. If is then the coshell executable is determined by doing the usual path search, in order, on the value of the environment variable COSHELL and the commands ksh and sh. is the inclusive-or of the following:

Return a pointer to a previously opened coshell if possible, otherwise
    open a new coshell.

Enable library debug tracing.

Ignore any command errors.
    By default any command error that is not tested by a condtional causes the job to terminate.

Commands are to be executed on the local host only.

Don't trace commands.
    By default commands are traced using the shell -x option.

Normally
    blocks when the job queue is full and waits until a job completes. causes to return when the job queue is full.

is a string that is interpreted by the coshell. If is then the value of the environment variable COATTRIBUTES is used if defined. ksh and sh ignore this string. The return value points to a structure with the following readonly elements:

The default flags.

The number of jobs that have not been waited for.

The number of jobs still running.

The total number of jobs sent to the coshell.

The total user time of all completed jobs in
    second increments.

The total system time of all completed jobs in
    second increments.

Close an open coshell pointed to by The coshell exit status is returned.

Sends the shell command line to the open coshell pointed to by for execution. are the same as in the call, and are used to augment the default settings from is the standard output file name and defaults to stdout if is the standard error file name and defaults to stderr if if contains job attributes that are appended to the attributes from before being sent to the coshell. The return value points to a structure with the following elements:

A number that uniquely identifies the job within the coshell.

The job exit status, valid only for job pointers returned by

The flags enabled for this job.

A user reserved pointer, initially set to
    on return from This is the only job field that may be modified by the user. The user defined value is preserved until after the call that returns the job pointer.

The user time of this job in
    second increments, valid only for job pointers returned by

The system time of this job in
    second increments, valid only for job pointers returned by

Returns the job pointer in the coshell pointed to by for the job pointed to by If is then a pointer to any completed job is returned. blocks until the specified job(s) complete. is returned if all jobs have completed. is the number of jobs that may be waited for without blocking. The return value and job fields are set to their final values. The return value is valid until the next or call.

The signal
    is sent to the job pointed to by running in the coshell pointed to by If is then the signal is sent to all jobs in the coshell. If both and are then the signal is sent to all jobs in all coshells. is returned on error, otherwise.

Sync all outstanding file operations for either the file
    or the file descriptor after its shell action has completed in If is then is used. If and then is opened using This is an unfortunate workaround for NFS and remote coshells, and is a no-op for all real file systems. It should be called after to ensure that all file system cache info has been flushed. sync(2) or fsync(2) must still be called to schedule file data to be written to disk.

Returns the shell initialization commands for the next job.
    These commands represent process state changes that may have occurred since the last call to e.g., current working directory or umask. If is local (a child of the calling process) may return the empty string; if is remote then considerably more information may be returned. This routine is used by remote coshell implementations and is not normally called from user code.

Applies shell single quoting to
    and copies the result into the sfio stream If then any occurence of /hosttype/ is translated to /$HOSTTYPE/, where hosttype is the current value of the environment variable. This routine is used by remote coshell implementations and is not normally called from user code.

CAVEATS
is a hack workaround, but we do have to work in the real world.

A bug in bsh(1) and ksh(1) implementations up to and including ksh88e causes some interrupted jobs to return 0 exit status. This should be fixed in later shell releases.

is reserved by at the outermost scope. To use use to force a subshell.

SEE ALSO
coshell(1), ksh(1), nmake(1), sh(1), cs(3), libast(3)