FMLI Commands coproc(1F)
NAME
coproc, cocreate, cosend, cocheck, coreceive, codestroy -
communicate with a process
SYNOPSIS
cocreate [-r rpath] [-w wpath] [-i id] [-R refname]
[-s sendstring] [-e expectstring] command
cosend [-n] procid string
cocheck procid
coreceive procid
codestroy [-R refname] procid [string]
DESCRIPTION
These co-processing functions provide a flexible means of
interaction between FMLI and an independent process; espe-
cially, they enable FMLI to be responsive to asynchronous
activity.
The cocreate function starts command as a co-process and
initializes communications by setting up pipes between FMLI
and the standard input and standard output of command. The
argument command must be an executable and its arguments (if
any). This means that command expects strings on its input
(supplied by cosend) and sends information on its output
that can be handled in various ways by FMLI.
The cosend function sends string to the co-process identi-
fied by procid via the pipe set up by cocreate (optionally
wpath), where procid can be either the command or id speci-
fied in cocreate. By default, cosend blocks, waiting for a
response from the co-process. Also by default, FMLI does
not send a sendstring and does not expect an expectstring
(except a newline). That is, it reads only one line of out-
put from the co-process. If -e expectstring was not defined
when the pipe was created, then the output of the co-process
is any single string followed by a newline: any other lines
of output remain on the pipe. If the -e option was specified
when the pipe was created, cosend reads lines from the pipe
until it reads a line starting with expectstring. All lines
except the line starting with expectstring become the out-
put of cosend.
SunOS 5.11 Last change: 5 Jul 1990 1
FMLI Commands coproc(1F)
The cocheck function determines if input is available from
the process identified by procid, where procid can be
either the command or id specified in cocreate. It returns a
Boolean value, which makes cocheck useful in if statements
and in other backquoted expressions in Boolean descriptors.
cocheck receives no input from the co-process; it simply
indicates if input is available from the co-process. You
must use coreceive to actually accept the input. The cocheck
function can be called from a reread descriptor to force a
frame to update when new data is available. This is useful
when the default value of a field in a form includes core-
ceive.
The coreceive function is used to read input from the co-
process identified by procid, where procid can be either
the command or id specified in cocreate. It should only be
used when it has been determined, using cocheck, that input
is actually available. If the -e option was used when the
co-process was created, coreceive will continue to return
lines of input until expectstring is read. At this point,
coreceive will terminate. The output of coreceive is all the
lines that were read excluding the line starting with
expectstring . If the -e option was not used in the
cocreate, each invocation of coreceive will return exactly
one line from the co-process. If no input is available when
coreceive is invoked, it will simply terminate without pro-
ducing output.
The codestroy function terminates the read/write pipes to
proc-id, where procid can be either the command or id
specified in cocreate. It generates a SIGPIPE signal to the
(child) co-process. This kills the co-process, unless the
co-process ignores the SIGPIPE signal. If the co-process
ignores the SIGPIPE, it will not die, even after the FMLI
process terminates (the parent process id of the co-process
will be 1).
The optional argument string is sent to the co-process
before the co-process dies. If string is not supplied, a
NUL string is passed, followed by the normal sendstring
(newline by default). That is, codestroy will call cosend
procid string: this implies that codestroy will write any
output generated by the co-process to stdout. For example,
if an interactive co-process is written to expect a "quit"
string when the communication is over, the close descriptor
could be defined; close=`codestroy ID 'quit' message`
and any output generated by the co-process when the string
quit is sent to it via codestroy (using cosend) would be
redirected to the message line.
SunOS 5.11 Last change: 5 Jul 1990 2
FMLI Commands coproc(1F)
The codestroy function should usually be given the -R
option, since you may have more than one process with the
same name, and you do not want to kill the wrong one. codes-
troy keeps track of the number of refnames you have assigned
to a process with cocreate, and when the last instance is
killed, it kills the process (id) for you. codestroy is typ-
ically called as part of a close descriptor because close is
evaluated when a frame is closed. This is important because
the co-process will continue to run if codestroy is not
issued.
When writing programs to use as co-processes, the following
tips may be useful. If the co-process program is written in
C language, be sure to flush output after writing to the
pipe. (Currently, awk(1) and sed(1) cannot be used in a co-
process program because they do not flush after lines of
output.) Shell scripts are well-mannered, but slow. C
language is recommended. If possible, use the default
sendstring, rpath and wpath. In most cases, expectstring
will have to be specified. This, of course, depends on the
co-process.
In the case where asynchronous communication from a co-
process is desired, a co-process program should use vsig to
force strings into the pipe and then signal FMLI that out-
put from the co-process is available. This causes the reread
descriptor of all frames to be evaluated immediately.
OPTIONS
cocreate options are:
-r rpath If -r is specified, rpath is the path-
name from which FMLI reads information.
This option is usually used to set up
communication with processes that natur-
ally write to a certain path. If -r is
not specified, cocreate will choose a
unique path in /var/tmp.
-w wpath If -w is specified, wpath is the path-
name to which cosend writes information.
This option is usually used so that one
process can talk to many different FMLI
processes through the same pipe. If -w
is not specified, cocreate will choose a
unique path in /var/tmp.
SunOS 5.11 Last change: 5 Jul 1990 3
FMLI Commands coproc(1F)
-i id If -i is specified, id is an alternative
name for the co-processinitialized by
this cocreate. If -i is not specified,
id defaults to command. The argument id
can later be used with the other co-
processing functions rather than com-
mand. This option is typically used,
since it facilitates the creation of two
or more co-processes generated from the
same command. (For example, cocreate -i
ID1 program args and cocreate -i ID2
program differentargs).
-R refname If -R is specified, refname is a local
name for the co-process. Since the
cocreate function can be issued more
than once, a refname is useful when the
same co-process is referenced a second
or subsequent time. With the -R option,
if the co-process already exists a new
one will not be created: the same pipes
will be shared. Then, refname can be
used as an argument to the -R option to
codestroy when you want to end a partic-
ular connection to a co-process and
leave other connections undisturbed.
(The co-process is only killed after
codestroy -R has been called as many
times as cocreate -R was called.)
-s sendstring The -s option specifies sendstring as a
string that will be appended to all out-
put sent to the co-process using cosend.
This option allows a co-process to know
when input from FMLI has completed. The
default sendstring is a newline if -s
is not specified.
-e expectstring The -e option specifies expectstring as
a string that identifies the end of all
output returned by the co-process.
(Note: expectstring need only be the
initial part of a line, and there must
be a newline at the end of the co-
process output.) This option allows
FMLI to know when output from the co-
process has completed. The default
expectstring is a newline if -e is not
specified.
SunOS 5.11 Last change: 5 Jul 1990 4
FMLI Commands coproc(1F)
cosend options are:
-n If the -n option is specified, cosend will not wait
for a response from the co-process. It simply returns,
providing no output. If the -n option is not used, a
co-process that does not answer will cause FMLI to
permanently hang, waiting for input from the co-
process.
EXAMPLES
Example 1 Sample commands
.
.
.
init=`cocreate -i BIGPROCES initialize`
close=`codestroy BIGPROCES`
.
.
.
reread=`cocheck BIGPROCES`
name=`cosend -n BIGPROCES field1`
.
.
.
name="Receive field"
inactive=TRUE
value=`coreceive BIGPROCES`
ATRIBUTES
See attributes(5) for descriptions of the following attri-
butes:
ATRIBUTE TYPE ATRIBUTE VALUE
Availability SUNWcsu
SEE ALSO
awk(1), cat(1), sed(1), vsig(1F), attributes(5)
NOTES
If cosend is used without the -n option, a co-process that
does not answer will cause FMLI to permanently hang.
SunOS 5.11 Last change: 5 Jul 1990 5
FMLI Commands coproc(1F)
The use of non-alphabetic characters in input and output
strings to a co-process should be avoided because they may
not get transferred correctly.
SunOS 5.11 Last change: 5 Jul 1990 6
|
