coshell.3 revision 3f54fd611f536639ec30dd53c48e5ec1897cc7d9
7abd0c58a5ce51db13f93de82407b2188d55d298Christian Maeder.de L \" literal font
75a6279dbae159d018ef812185416cf6df386c10Till Mossakowski.if !\\$1 \&\\$1 \\$2 \\$3 \\$4 \\$5 \\$6 \f1
7abd0c58a5ce51db13f93de82407b2188d55d298Christian Maeder.}S 5 1 \& "\\$1" "\\$2" "\\$3" "\\$4" "\\$5" "\\$6"
c18e9c3c6d5039618f1f2c05526ece84c7794ea3Christian Maeder.}S 1 5 \& "\\$1" "\\$2" "\\$3" "\\$4" "\\$5" "\\$6"
c00adad2e9459b422dee09e3a2bddba66b433bb7Christian Maeder.de EX \" start example
e8ffec0fa3d3061061bdc16e44247b9cf96b050fChristian Maeder.ta 1i 2i 3i 4i 5i 6i
3a9dafc31d54a6bdac1acda72bb15aceffb0240fChristian Maeder.de EE \" end example
c18e9c3c6d5039618f1f2c05526ece84c7794ea3Christian Maeder.SH NAME \" @(#)coshell.3 (gsf@research.att.com) 10/11/90
c1124c6303c288db3fcb40518d38169cd7baaa4cChristian Maedercoshell \- shell coprocess support
c1124c6303c288db3fcb40518d38169cd7baaa4cChristian Maeder.L "\-lcoshell \-last"
64f7c2188d578b920d8e5513a423449af633e9bcChristian Maeder.SH DESCRIPTION
64f7c2188d578b920d8e5513a423449af633e9bcChristian Maederroutines support the shell as a coprocess.
c1124c6303c288db3fcb40518d38169cd7baaa4cChristian MaederThis coprocess may be either
aff01ee50b66032469c232e00c945d1fd4f57d1bChristian Maederexecuting on the local host, or it may be
aff01ee50b66032469c232e00c945d1fd4f57d1bChristian Maeder.IR coshell (1)
aff01ee50b66032469c232e00c945d1fd4f57d1bChristian Maederwith access to shells on hosts throughout the local network.
aff01ee50b66032469c232e00c945d1fd4f57d1bChristian MaederThe coshell inherits the environment of the calling process.
aff01ee50b66032469c232e00c945d1fd4f57d1bChristian MaederSignals sent to the calling process are passed to the coshell.
c1124c6303c288db3fcb40518d38169cd7baaa4cChristian MaederMore than one coshell may be open in the current process.
c1124c6303c288db3fcb40518d38169cd7baaa4cChristian Maederargument to the
aff01ee50b66032469c232e00c945d1fd4f57d1bChristian Maeder.LR cowait() ,
bbae6e6ca0de7f2ffbb44d2c8da179f2b717237fChristian Maeder.LR cokill() ,
e289294500ad68fa0706b09521af340bbb356a69Christian Maeder.LR copending() ,
e289294500ad68fa0706b09521af340bbb356a69Christian Maeder.LR cozombie() ,
c1124c6303c288db3fcb40518d38169cd7baaa4cChristian Maedercalls below is
aff01ee50b66032469c232e00c945d1fd4f57d1bChristian Maederthen the call is applied to all open coshell.
c1124c6303c288db3fcb40518d38169cd7baaa4cChristian Maeder.L "Coshell_t* coopen(const char* shell, int flags, const char* attributes)"
c1124c6303c288db3fcb40518d38169cd7baaa4cChristian MaederReturns a pointer to a new coshell.
c1124c6303c288db3fcb40518d38169cd7baaa4cChristian Maederis returned on error.
c1124c6303c288db3fcb40518d38169cd7baaa4cChristian Maederthen the coshell executable is determined by doing the usual path search,
c1124c6303c288db3fcb40518d38169cd7baaa4cChristian Maederin order, on the value of the environment variable
aff01ee50b66032469c232e00c945d1fd4f57d1bChristian Maederand the commands
aff01ee50b66032469c232e00c945d1fd4f57d1bChristian Maederis the inclusive-or of the following:
aff01ee50b66032469c232e00c945d1fd4f57d1bChristian MaederReturn a pointer to a previously opened coshell if possible, otherwise
aff01ee50b66032469c232e00c945d1fd4f57d1bChristian Maederopen a new coshell.
c1124c6303c288db3fcb40518d38169cd7baaa4cChristian MaederEnable library debug tracing.
c1124c6303c288db3fcb40518d38169cd7baaa4cChristian MaederIgnore any command errors.
c1124c6303c288db3fcb40518d38169cd7baaa4cChristian MaederBy default any command error that is not tested by a condtional causes
c1124c6303c288db3fcb40518d38169cd7baaa4cChristian Maederthe job to terminate.
c1124c6303c288db3fcb40518d38169cd7baaa4cChristian MaederCommands are to be executed on the local host only.
c1124c6303c288db3fcb40518d38169cd7baaa4cChristian Maederinternal file descriptors are moved to 10 or above;
c1124c6303c288db3fcb40518d38169cd7baaa4cChristian MaederSIGSTOP and SIGCONT handlers are not installed.
c1124c6303c288db3fcb40518d38169cd7baaa4cChristian MaederDon't trace commands.
c1124c6303c288db3fcb40518d38169cd7baaa4cChristian MaederBy default commands are traced using the shell
c1124c6303c288db3fcb40518d38169cd7baaa4cChristian Maeder.L CO_NONBLOCK
c1124c6303c288db3fcb40518d38169cd7baaa4cChristian Maederblocks when the job queue is full and waits until a job completes.
aff01ee50b66032469c232e00c945d1fd4f57d1bChristian Maeder.L CO_NONBLOCK
aff01ee50b66032469c232e00c945d1fd4f57d1bChristian Maederwhen the job queue is full.
aff01ee50b66032469c232e00c945d1fd4f57d1bChristian Maederis a string that is interpreted by the coshell.
aff01ee50b66032469c232e00c945d1fd4f57d1bChristian Maederthen the value of the environment variable
c1124c6303c288db3fcb40518d38169cd7baaa4cChristian Maeder.B COATTRIBUTES
aff01ee50b66032469c232e00c945d1fd4f57d1bChristian Maederis used if defined.
c1124c6303c288db3fcb40518d38169cd7baaa4cChristian Maederignore this string.
c1124c6303c288db3fcb40518d38169cd7baaa4cChristian MaederThe return value points to a structure with the following readonly elements:
c1124c6303c288db3fcb40518d38169cd7baaa4cChristian Maeder.L "int flags"
c1124c6303c288db3fcb40518d38169cd7baaa4cChristian MaederThe default flags.
c1124c6303c288db3fcb40518d38169cd7baaa4cChristian Maeder.L "int outstanding"
c1124c6303c288db3fcb40518d38169cd7baaa4cChristian MaederThe number of jobs that have not been waited for.
c1124c6303c288db3fcb40518d38169cd7baaa4cChristian Maeder.L "int running"
c1124c6303c288db3fcb40518d38169cd7baaa4cChristian MaederThe number of jobs still running.
aff01ee50b66032469c232e00c945d1fd4f57d1bChristian Maeder.L "int total"
c1124c6303c288db3fcb40518d38169cd7baaa4cChristian MaederThe total number of jobs sent to the coshell.
c1124c6303c288db3fcb40518d38169cd7baaa4cChristian Maeder.L "unsigned long user"
c1124c6303c288db3fcb40518d38169cd7baaa4cChristian MaederThe total user time of all completed jobs in
c1124c6303c288db3fcb40518d38169cd7baaa4cChristian Maedersecond increments.
c1124c6303c288db3fcb40518d38169cd7baaa4cChristian Maeder.L "unsigned long sys"
aff01ee50b66032469c232e00c945d1fd4f57d1bChristian MaederThe total system time of all completed jobs in
9b3bf7c6cf82dc11478bbac3414fe657b9bca327Christian Maedersecond increments.
dc4bfcb8a5092af158e8a5691c8de8d6bc8b8724Christian Maeder.L "int coclose(Coshell_t* sh)"
dc4bfcb8a5092af158e8a5691c8de8d6bc8b8724Christian MaederClose an open coshell pointed to by
dc4bfcb8a5092af158e8a5691c8de8d6bc8b8724Christian MaederThe coshell exit status is returned.
dc4bfcb8a5092af158e8a5691c8de8d6bc8b8724Christian Maeder.L "Cojob_t* coexec(Coshell_t* sh, const char* cmd, int flags, const char* out, const char* err, const char* att)"
dc4bfcb8a5092af158e8a5691c8de8d6bc8b8724Christian MaederSends the shell command line
dc4bfcb8a5092af158e8a5691c8de8d6bc8b8724Christian Maederto the open coshell pointed to by
dc4bfcb8a5092af158e8a5691c8de8d6bc8b8724Christian Maederfor execution.
dc4bfcb8a5092af158e8a5691c8de8d6bc8b8724Christian Maederare the same as in the
dc4bfcb8a5092af158e8a5691c8de8d6bc8b8724Christian Maedercall, and are used to augment the default settings from
dc4bfcb8a5092af158e8a5691c8de8d6bc8b8724Christian Maeder.LR coopen() .
aff01ee50b66032469c232e00c945d1fd4f57d1bChristian Maederis the standard output file name and defaults to
aff01ee50b66032469c232e00c945d1fd4f57d1bChristian Maederis the standard error file name and defaults to
aff01ee50b66032469c232e00c945d1fd4f57d1bChristian Maeder.RL non- NULL ,
aff01ee50b66032469c232e00c945d1fd4f57d1bChristian Maedercontains job attributes that are appended to the attributes from
aff01ee50b66032469c232e00c945d1fd4f57d1bChristian Maederbefore being sent to the coshell.
aff01ee50b66032469c232e00c945d1fd4f57d1bChristian MaederThe return value points to a structure with the following elements:
aff01ee50b66032469c232e00c945d1fd4f57d1bChristian MaederA number that uniquely identifies the job within the coshell.
aff01ee50b66032469c232e00c945d1fd4f57d1bChristian Maeder.L "int status"
aff01ee50b66032469c232e00c945d1fd4f57d1bChristian MaederThe job exit status, valid only for job pointers returned by
dc4bfcb8a5092af158e8a5691c8de8d6bc8b8724Christian Maeder.LR cowait() .
dc4bfcb8a5092af158e8a5691c8de8d6bc8b8724Christian Maeder.L "int flags"
dc4bfcb8a5092af158e8a5691c8de8d6bc8b8724Christian MaederThe flags enabled for this job.
3a9dafc31d54a6bdac1acda72bb15aceffb0240fChristian Maeder.L "void* local"
3a9dafc31d54a6bdac1acda72bb15aceffb0240fChristian MaederA user reserved pointer, initially set to
dc4bfcb8a5092af158e8a5691c8de8d6bc8b8724Christian Maederon return from
3a9dafc31d54a6bdac1acda72bb15aceffb0240fChristian Maeder.LR coexec() .
3a9dafc31d54a6bdac1acda72bb15aceffb0240fChristian MaederThis is the only job field that may be modified by the user.
3a9dafc31d54a6bdac1acda72bb15aceffb0240fChristian MaederThe user defined value is preserved until after the
3a9dafc31d54a6bdac1acda72bb15aceffb0240fChristian Maedercall that returns the job pointer.
3a9dafc31d54a6bdac1acda72bb15aceffb0240fChristian Maeder.L "unsigned long user"
3a9dafc31d54a6bdac1acda72bb15aceffb0240fChristian MaederThe user time of this job in
3a9dafc31d54a6bdac1acda72bb15aceffb0240fChristian Maedersecond increments, valid only for job pointers returned by
3a9dafc31d54a6bdac1acda72bb15aceffb0240fChristian Maeder.LR cowait() .
3a9dafc31d54a6bdac1acda72bb15aceffb0240fChristian Maeder.L "unsigned long sys"
3a9dafc31d54a6bdac1acda72bb15aceffb0240fChristian MaederThe system time of this job in
3a9dafc31d54a6bdac1acda72bb15aceffb0240fChristian Maedersecond increments, valid only for job pointers returned by
3a9dafc31d54a6bdac1acda72bb15aceffb0240fChristian Maeder.LR cowait() .
3a9dafc31d54a6bdac1acda72bb15aceffb0240fChristian Maeder.L "Cojob_t* cowait(Coshell_t* sh, Cojob_t* job, int timeout)"
dc4bfcb8a5092af158e8a5691c8de8d6bc8b8724Christian MaederReturns the job pointer in the coshell pointed to by
dc4bfcb8a5092af158e8a5691c8de8d6bc8b8724Christian Maederfor the job pointed to by
3a9dafc31d54a6bdac1acda72bb15aceffb0240fChristian Maederthen a pointer to any completed job is returned.
dc4bfcb8a5092af158e8a5691c8de8d6bc8b8724Christian Maederblocks until the specified job(s) complete.
dc4bfcb8a5092af158e8a5691c8de8d6bc8b8724Christian Maederis returned on error or if all jobs have completed and
dc4bfcb8a5092af158e8a5691c8de8d6bc8b8724Christian Maederis set to EINVAL for coshell communication errors,
dc4bfcb8a5092af158e8a5691c8de8d6bc8b8724Christian Maederand there are no children, and ESRCH if
dc4bfcb8a5092af158e8a5691c8de8d6bc8b8724Christian Maederand not an active job.
dc4bfcb8a5092af158e8a5691c8de8d6bc8b8724Christian Maeder.L "cozombie(sh)"
dc4bfcb8a5092af158e8a5691c8de8d6bc8b8724Christian Maederis the number of jobs that may be waited for without blocking.
dc4bfcb8a5092af158e8a5691c8de8d6bc8b8724Christian MaederThe return value
c18e9c3c6d5039618f1f2c05526ece84c7794ea3Christian Maederjob fields are set to their final values.
c18e9c3c6d5039618f1f2c05526ece84c7794ea3Christian MaederThe return value is valid until the next
dc4bfcb8a5092af158e8a5691c8de8d6bc8b8724Christian Maeder.LR coexec() ,
dc4bfcb8a5092af158e8a5691c8de8d6bc8b8724Christian Maederis the maximum time in milliseconds that wait will block.
c18e9c3c6d5039618f1f2c05526ece84c7794ea3Christian MaederIf the wait times out then 0 is returned.
0f67ca7b0c738a28f6688ba6e96d44d7c14af611Christian Maederwaits until a job completes or a signal is received.
0f67ca7b0c738a28f6688ba6e96d44d7c14af611Christian Maeder.L "int cojobs(Coshell_t* sh)"
dc4bfcb8a5092af158e8a5691c8de8d6bc8b8724Christian MaederReturns the number of outstanding jobs that are children of the caller.
dc4bfcb8a5092af158e8a5691c8de8d6bc8b8724Christian Maeder(Remote jobs or jobs executed by a separate daemon are not counted here.)
dc4bfcb8a5092af158e8a5691c8de8d6bc8b8724Christian Maeder.L "int copending(Coshell_t* sh)"
dc4bfcb8a5092af158e8a5691c8de8d6bc8b8724Christian MaederReturns the number of pending jobs; this is the number of
aff01ee50b66032469c232e00c945d1fd4f57d1bChristian Maedercalls required to reap all running jobs.
c18e9c3c6d5039618f1f2c05526ece84c7794ea3Christian Maeder.L "int cozombie(Coshell_t* sh)"
c18e9c3c6d5039618f1f2c05526ece84c7794ea3Christian MaederReturns the number of jobs that have completed but have not been
c18e9c3c6d5039618f1f2c05526ece84c7794ea3Christian Maeder.L "int cokill(Coshell_t* sh, Cojob_t* job, int sig)"
dc4bfcb8a5092af158e8a5691c8de8d6bc8b8724Christian Maederis sent to the job pointed to by
c1124c6303c288db3fcb40518d38169cd7baaa4cChristian Maederrunning in the coshell pointed to by
c1124c6303c288db3fcb40518d38169cd7baaa4cChristian Maederthen the signal is sent to all jobs in the coshell.
aff01ee50b66032469c232e00c945d1fd4f57d1bChristian Maederthen the signal is sent to all jobs in all coshells.
aff01ee50b66032469c232e00c945d1fd4f57d1bChristian Maederis returned on error,
c1124c6303c288db3fcb40518d38169cd7baaa4cChristian Maeder.L "int cosync(Coshell_t* sh, const char* path, int fd, int mode)"
c1124c6303c288db3fcb40518d38169cd7baaa4cChristian MaederSync all outstanding file operations for either the file
c1124c6303c288db3fcb40518d38169cd7baaa4cChristian Maederor the file descriptor
c1124c6303c288db3fcb40518d38169cd7baaa4cChristian Maederafter its shell action has completed in
c1124c6303c288db3fcb40518d38169cd7baaa4cChristian Maederis opened using
c1124c6303c288db3fcb40518d38169cd7baaa4cChristian MaederThis is an unfortunate workaround for NFS and remote coshells, and is a
c1124c6303c288db3fcb40518d38169cd7baaa4cChristian Maederno-op for all real file systems.
dc4bfcb8a5092af158e8a5691c8de8d6bc8b8724Christian MaederIt should be called after
c18e9c3c6d5039618f1f2c05526ece84c7794ea3Christian Maederto ensure that all file system cache info has been flushed.
0f67ca7b0c738a28f6688ba6e96d44d7c14af611Christian Maedermust still be called to schedule file data to be written to disk.
aff01ee50b66032469c232e00c945d1fd4f57d1bChristian Maeder.L "char* coinit(Coshell_t* sh)"
b49276c9f50038e0bd499ad49f7bd6444566a834Christian MaederReturns the shell initialization commands for the next job.
c18e9c3c6d5039618f1f2c05526ece84c7794ea3Christian MaederThese commands represent process state changes that may have occurred
c1124c6303c288db3fcb40518d38169cd7baaa4cChristian Maedersince the last call to
c1124c6303c288db3fcb40518d38169cd7baaa4cChristian Maedere.g., current working directory or umask.
0f67ca7b0c738a28f6688ba6e96d44d7c14af611Christian Maederis local (a child of the calling process)
aff01ee50b66032469c232e00c945d1fd4f57d1bChristian Maedermay return the empty string;
7dec34aee2b609b9535c48d060e0f7baf3536457Christian Maederis remote then considerably more information may be returned.
7dec34aee2b609b9535c48d060e0f7baf3536457Christian MaederThis routine is used by remote coshell implementations and is
7dec34aee2b609b9535c48d060e0f7baf3536457Christian Maedernot normally called from user code.
aff01ee50b66032469c232e00c945d1fd4f57d1bChristian Maeder.L "void coquote(Sfio_T* sp, const char* string, int type)"
7dec34aee2b609b9535c48d060e0f7baf3536457Christian MaederApplies shell single quoting to
2a598ff0c1b7b51c33aee7029b43bc5cfcbea6b8Christian Maederand copies the result into the sfio stream
2a598ff0c1b7b51c33aee7029b43bc5cfcbea6b8Christian Maederthen any occurence of \f5/\fP\fIhosttype\fP\f5/\fP is translated to
aff01ee50b66032469c232e00c945d1fd4f57d1bChristian Maeder\f5/$HOSTTYPE/\fP, where
aff01ee50b66032469c232e00c945d1fd4f57d1bChristian Maederis the current value of the
aff01ee50b66032469c232e00c945d1fd4f57d1bChristian Maederenvironment variable.
2a598ff0c1b7b51c33aee7029b43bc5cfcbea6b8Christian MaederThis routine is used by remote coshell implementations and is
a2149e576afc5770597d033a1884da0627df0a4eChristian Maedernot normally called from user code.
469af98c69977faf5666e689eae863c1606ce269Christian Maederis a hack workaround, but we do have to work in the real world.