-
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.
Coshell_t* coopen(const char* shell, int flags, const char* attributes)
Returns a pointer to a new coshell.
NULL
is returned on error.
If
shell
is
NULL
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.
flags
is the inclusive-or of the following:
- CO_ANY
-
Return a pointer to a previously opened coshell if possible, otherwise
open a new coshell.
- CO_DEBUG
-
Enable library debug tracing.
- CO_IGNORE
-
Ignore any command errors.
By default any command error that is not tested by a condtional causes
the job to terminate.
- CO_LOCAL
-
Commands are to be executed on the local host only.
- CO_SILENT
-
Don't trace commands.
By default commands are traced using the shell
-x
option.
- CO_NONBLOCK
-
Normally
coexec()
blocks when the job queue is full and waits until a job completes.
CO_NONBLOCK
causes
coexec()
to return
NULL
when the job queue is full.
attributes
is a string that is interpreted by the coshell.
If
attributes
is
NULL
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:
- int flags
-
The default flags.
- int outstanding
-
The number of jobs that have not been waited for.
- int running
-
The number of jobs still running.
- int total
-
The total number of jobs sent to the coshell.
- unsigned long user
-
The total user time of all completed jobs in
1/CO_QUANT
second increments.
- unsigned long sys
-
The total system time of all completed jobs in
1/CO_QUANT
second increments.
int coclose(Coshell_t* sh)
Close an open coshell pointed to by
sh.
The coshell exit status is returned.
Cojob_t* coexec(Coshell_t* sh, const char* cmd, int flags, const char* out, const char* err, const char* att)
Sends the shell command line
cmd
to the open coshell pointed to by
sh
for execution.
flags
are the same as in the
coopen()
call, and are used to augment the default settings from
coopen().
out
is the standard output file name and defaults to
stdout
if
NULL.
err
is the standard error file name and defaults to
stderr
if
NULL.
att,
if
non-NULL,
contains job attributes that are appended to the attributes from
coopen()
before being sent to the coshell.
The return value points to a structure with the following elements:
- int id
-
A number that uniquely identifies the job within the coshell.
- int status
-
The job exit status, valid only for job pointers returned by
cowait().
- int flags
-
The flags enabled for this job.
- void* local
-
A user reserved pointer, initially set to
NULL
on return from
coexec().
This is the only job field that may be modified by the user.
The user defined value is preserved until after the
cowait()
call that returns the job pointer.
- unsigned long user
-
The user time of this job in
1/CO_QUANT
second increments, valid only for job pointers returned by
cowait().
- unsigned long sys
-
The system time of this job in
1/CO_QUANT
second increments, valid only for job pointers returned by
cowait().
Cojob_t* cowait(Coshell_t* sh, Cojob_t* job)
Returns the job pointer in the coshell pointed to by
sh
for the job pointed to by
job.
If
job
is
NULL
then a pointer to any completed job is returned.
cowait()
blocks until the specified job(s) complete.
NULL
is returned if all jobs have completed.
(sh->outstanding - sh->running)
is the number of jobs that may be waited for without blocking.
The return value
status,
user
and
sys
job fields are set to their final values.
The return value is valid until the next
coexec(),
cowait()
or
coclose()
call.
- int cokill(Coshell_t* sh, Cojob_t* job, int sig)
-
The signal
sig
is sent to the job pointed to by
job
running in the coshell pointed to by
sh.
If
job
is
NULL
then the signal is sent to all jobs in the coshell.
If both
sh
and
job
are
NULL
then the signal is sent to all jobs in all coshells.
-1
is returned on error,
0
otherwise.
- int cosync(Coshell_t* sh, const char* path, int fd, int mode)
-
Sync all outstanding file operations for either the file
path
or the file descriptor
fd
after its shell action has completed in
sh.
If
path
is
NULL
then
fd
is used.
If
fd<0
and
mode>=0
then
path
is opened using
mode.
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
cowait()
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.
- char* coinit(Coshell_t* sh)
-
Returns the shell initialization commands for the next job.
These commands represent process state changes that may have occurred
since the last call to
coinit(),
e.g., current working directory or umask.
If
sh
is local (a child of the calling process)
coinit()
may return the empty string;
if
sh
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.
- void coquote(Sfio_T* sp, const char* string, int type)
-
Applies shell single quoting to
string
and copies the result into the sfio stream
sp.
If
type!=0
then any occurence of /hosttype/ is translated to
/$HOSTTYPE/, where
hosttype
is the current value of the
HOSTTYPE
environment variable.
This routine is used by remote coshell implementations and is
not normally called from user code.