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.

More than one coshell may be open in the current process. If the argument to the or calls below is then the call is applied to all open 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.

The caller is
    sh(1): internal file descriptors are moved to 10 or above; SIGSTOP and SIGCONT handlers are not installed.

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 on error or if all jobs have completed and is set to EINVAL for coshell communication errors, ECHILD if is and there are no children, and ESRCH if is not and not an active job. 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. is the maximum time in milliseconds that wait will block. If the wait times out then 0 is returned. A negative waits until a job completes or a signal is received.

Returns the number of outstanding jobs that are children of the caller.
    (Remote jobs or jobs executed by a separate daemon are not counted here.)

Returns the number of pending jobs; this is the number of
    calls required to reap all running jobs.

Returns the number of jobs that have completed but have not been
    for.

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)