HELP PIPEUTILS (Unix(TM) only) A.Sloman Jul 1990
LIB PIPEIN
(And associated utilities)
LIB PIPEOUT
This file describes:
(1) a collection of utilities to run a Unix command and read in input,
e.g. into a VED buffer, including commands on remote machines. The
procedures are all defined in terms of -pipein-.
(2) PIPEOUT, a procedure that spawns a sub-process and feeds it
characters generated by a user-supplied character repeater.
It is possible that some of the facilities described below will not work
on all Unix systems, especially the network facilities. There should be
no problems with networks linked via NFS or those supporting the 'rsh'
or 'remsh' commands for remote execution, although their use will
require a login account on the remote machine along with a mechanism to
enable remote commands to be given without a password, for instance a
.rhosts file (see MAN * RHOSTS).
CONTENTS - (Use <ENTER> g to access required sections)
-- Introduction
-- The mechanisms used
-- pipeout(R, C, A, B)
-- pipein(C, A, B) -> R
-- vedpipein(C,A,F,P,B,H)
-- vedgenshell(C,H)
-- <ENTER> sh <command>
-- <ENTER> csh <command>
-- <ENTER> rsh <machine> <command>
-- <ENTER> remsh <machine> <command>
-- <ENTER> rved <machine> <file>
-- Compiling and running C or Fortran programs
-- Defining new commands, e.g. <ENTER> who
-- See also-- Introduction -------------------------------------------------------
The low level POPLOG Unix facilities like -sysfork-, -syspipe-, and
-sysexecute- are quite tricky to use directly. Special cases are
packaged in a variety of system and library procedures, e.g. -sysobey-,
-ved_imcsh- and others.
In addition two further mechanisms -pipein- and -pipeout- are described
below. Despite their names they are not really symmetrical, the reason
being that -pipeout- was implemented first, and when -pipein- was added
a more general mechanism was used.
LIB PIPEOUT is concerned with a class of problems where you want to
start up a sub-process and send characters from a character repeater
(see REF * CHARIO) to it. It takes a character repeater, a unix command
pathname, a list of arguments for the command, and a boolean specifying
whether the Poplog process should wait for the Unix process to finish
or not. It creates a sub-process to run the unix command, linked by
a pipe to the parent Poplog process, and then sends the characters
from the repeater down the pipe.
LIB PIPEIN is used to run a sub-process and then read in the output of
that process through a pipe. The characters read in may be inserted into
a VED file, or consumed by a user program, for example. -pipein- takes
a unix command pathname, a list of arguments for the command, and a
boolean to say whether a character repeater or a device record should
be returned. It creates a subprocess to run command, creates a pipe
through which output from the process can be read, and the repeater
or device returned represents that pipe.
-pipein- is used to define a more specialised procedure, -vedpipein- to
read characters from a sub-process into a specified VED buffer. A still
more specialised facility, built on that, is -vedgenshell- for running
shell-like processes and reading their output into VED.
Finally a collection of VED <ENTER> commands is defined in terms of
these facilities. Users can easily extend this collection by copying
and modifying the files supplied.
Both -pipein- and -pipeout- are defined in terms of the
following Poplog facilities:
sysvfork (see REF *SYSUTIL),
sysexecute (see REF * SYSUTIL),
syspipe (see REF * SYSIO),
along with other reading and writing facilities described in REF SYSIO.
-- The mechanisms used ------------------------------------------------
The lowest level facility, pipein, is defined in terms of
-syspipe- to make the pipe between processes
-sysvfork- to spawn a sub-process (sysvfork in Berkeley Unix)
-sysexecute- to run a unix command in the sub-process
Two of the arguments required by -sysexecute- are also required by
-pipeout-, -pipein- and -vedpipein-, namely
a string which is the path name of a unix command (e.g.
'/usr/ucb/rsh), and
a list of arguments to be passed to that command, of which according
to the normal unix conventions the first argument is the name of
the command.
So, for example, the first two arguments to -pipein- could be
'/bin/sh' and ['/bin/sh' '-ce' 'ls']
to list the files in the current working directory. These arguments are
also required by -vedpipein-. The second and third arguments of
-pipeout- are of similar form.
However the remaining procedures such as -vedgenshell-, -ved_sh-,
-ved_rved- etc. create the arguments for -sysexecute- themselves, so
they provide a simpler user interface.
-- pipeout(R, C, A, B) ------------------------------------------------
pipeout(<charrep:R>, <string:C>, <list:A>, <boolean:B>);
This takes a character repeater R (or a file or device record from which
a character repeater can be made), a string C specifying an executable
command file, a list A of argument strings and a boolean B specifying
whether -pipeout- should wait for the command to finish before returning
control to the user.
If the final argument (B) is false then PIPEOUT does a second SYSVFORK
in order to prevent the creation of a zombie process.
Examples of use:
pipeout('file', '/bin/csh', ['csh' '-c' 'nroff | lpr'], false);
This sends the file through the nroff procedure and thence to the
printer.
pipeout(vedrepeater, '/bin/csh', ['csh' '-c' 'nroff | more'], true);
This sends characters in the VED buffer from the current location to the
end of the file through the nroff process and then via a further pipe to
the "more" process. NB if used in a VED command this should be preceded
by a command to turn off raw mode and cause output to occur at the
bottom of the screen, e.g. the following will do:
pr(newline);
In the second case pipeout only returns after the "more" command has
finished, so input to, and output from more will not get confused with
any other i/o taking place.
(N.B. The R argument may also be a reference containing a procedure,
i.e. consref(P). In this case, the procedure P is applied directly to
the output pipe device, i.e. P(DEV), and should write the data to it.
For example,
pipeout(consref(vedwriterange(% vvedmarklo, vvedmarkhi %)),
'/bin/csh', ['csh' '-c' 'nroff | more'], true);
would do the same as the above for the VED marked range.)
-- pipein(C, A, B) -> R -----------------------------------------------
pipein(<string:C>,<list:A>,<boolean:B>) -> <device|repeater:R>
Uses the command name C and list of argument strings A to generate a
sub-process, and returns either a device record for a pipe from that
process (if B is false), or a character repeater from the pipe (if B is
not false).
Example
pipein('/bin/csh', ['/bin/csh' '-ce' 'who'], true) -> charrep;
Runs the command 'who' in a subshell, and returns a character repeater
for the ouput, as does
pipein('/bin/who', ['/bin/who' ], true) -> charrep;
Whereas the following returns an input pipe:
pipein('/bin/who', ['/bin/who' ], false) -> device;
-sysvfork- is used to spawn the sub-process then -sysexecute- runs the
command, using the arguments given.
NOTE: if the final argument is false, the device returned is created
with mode "line", i.e. using the command syspipe("line"). So -sysread-
when applied to that device will return (at most) a line of output at a
time (terminated with newline character).
For details SHOWLIB * PIPEIN
See HELP * SYSPIPE-- vedpipein(C,A,F,P,B,H) ---------------------------------------------
vedpipein(<string:C>,<list:A>,<string|vector|false:F>,<proc:P>,<boole:B>
<boole|string:H>);
C is a command path name and A a list of argument strings, as
required for -sysexecute- and -pipein-. The command is run and any
output received is put into a VED file defined by F (which can
be either a file name or a VED file structure). P is a procedure to
be executed in the environment of the VED file as soon as it is
opened, e.g. to set defaults. If B is true the output from the
command is displayed as a VED window on the screen, or, if there
is enough space and show_output_on_status is non-false,
on the status line.
If H is a string then if an output file is created, the string is
inserted as a header.
If F is -false- then instead of going into a new file the output
from the command is read into the current file immediately after
the current line. (This is used for one of the options in
ved_dired, for example. See HELP * DIRED.)
For more details SHOWLIB * VEDPIPEIN-- vedgenshell(C,H) ---------------------------------------------------
vedgenshell(<false|string:C>,<false|string:H>);
C is either false or the pathname of a shell, e.g. '/bin/sh' or
'/bin/csh'. If it is false then the shell defaults to the result of
systranslate('SHELL').
If H is a string then it is inserted as a header in the output
file.
This is used to define a collection of VED <ENTER> commands.
-vedargument- is used to define the arguments to be given to the
shell, e.g. a command to be run.
If there are no arguments then an interactive sub-shell is spawned,
otherwise -vedpipein- is used to run the shell, and any output is
read back into a temporary ved file.
NB
The VED <ENTER> commands defined below using this facility all give the
command on the status line as the header H. So the output file has that
command as its first line.
For more details SHOWLIB * VEDGENSHELL-- <ENTER> sh <command> -----------------------------------------------
Runs /bin/sh with the <command> as argument and reads any output
into a VED file.
If there is no argument then this spawns an interactive sub-shell.
For more details SHOWLIB * VED_SH-- <ENTER> csh <command> -----------------------------------------------
Runs /bin/csh with the <command> as argument and reads any output
into a temporary VED file.
If there is no argument then this spawns an interactive sub-shell.
For more details SHOWLIB * VED_CSH-- <ENTER> rsh <machine> <command> -------------------------------------- <ENTER> remsh <machine> <command>
Obey the command on the machine specified, and read the result into a
temporary VED file. These use the 'rsh' or 'remsh' commands for remote
execution, as appropriate.
WARNING any environment variables in <command> will be interpreted
on the remote machine. If you want them interpreted before rsh (or
remsh) is invoked use
<ENTER> sh rsh <machine> <command>
or
<ENTER> sh remsh <machine> <command>
You could define a procedure to do this, e.g. as follows
define ved_Rsh;
veddo('sh rsh ' sys_>< vedargument);
enddefine;
For more details see -vedpipein-, including the effect of the global flag
-show_output_on_status-.
For more details SHOWLIB * VED_RSH, including the effect of the variable
ved_rsh_indentstep
which defaults to 8, but is set to the same as -vedindentstep- in
-ved_rved-.
-- <ENTER> rved <machine> <file> --------------------------------------
This is simply for reading into VED a file on another machine. There is
no provision for writing the file back to the other machine after any
changes. Strictly this is redundant. It could be defined in terms of a
call of -ved_rsh-, using -veddo- thus:
define ved_rved;
lvars args=sysparse_string(vedargument);
vars ved_rsh_indentstep = vedindentstep;
veddo('rsh ' sys_>< args(1) sys_>< ' cat ' sys_>< args(2))
enddefine;
Because it is defined in terms of ved_rsh the warning about environment
variables being interpreted on the remote machine applies. So if you
have an environment variable $foo defined locally then
<ENTER> rved machine $foo
won't work. Instead do
<ENTER> sh rsh machine cat $foo
You could define a variant of ved_rved to do this. E.g.
define ved_Rved;
lvars args=sysparse_string(vedargument);
veddo('sh rsh ' sys_>< args(1) sys_>< ' cat ' sys_>< args(2))
enddefine;
This will be slightly slower though.
For more details SHOWLIB * VED_RVED-- Compiling and running C or Fortran programs ------------------------
<ENTER> ccomp <argument list>
A utility defined in terms of -vedpipein- for writing, compiling,
and running a C program from the VED buffer, and reading back output
into a temporary VED file. Details are described in HELP * CCOMP
<ENTER> fcomp <argument list>
A similar utility for fortran.
-- Defining new commands, e.g. <ENTER> who ----------------------------
In terms of ved_sh (or ved_csh) it is easy to define a VED command
<ENTER> who
to print out the list of users of the current machine. E.g. if could
be done thus.
define ved_who;
vars vedargument = 'who';
ved_sh()
enddefine;
Similar methods can be used to define other VED versions of Unix
commands.
However, it is actually more efficient to define them directly, if you
know enough about where the executable files are. E.g. ved_who is more
efficiently defined as follows.
define ved_who;
vedpipein(
'/bin/who', ;;; first arg for sysexecute
['who' ], ;;; second arg for sysexecute
systmpfile(false,'rsh',nullstring),
procedure;
false ->> vedcompileable ->> vedwriteable
->> vedbreak -> vednotabs;
8 -> vedindentstep; ;;; keep formatting right
endprocedure,
true, ;;; i.e. display the file
'/bin/who' ;;; header for output file
)
enddefine;
-- See also -----------------------------------------------------------
REF * SYSUTIL /sysexecute
for the specification of the command and arglist arguments.
REF * SYSIO/syspipe
REF * SYSIO/sysread
REF * SYSUTIL/sysexecute
REF * SYSUTIL/sysfork
REF * SYSUTIL/sysvfork
REF * CHARIO
HELP * CCOMP
HELP * FCOMP
HELP * INPUT
HELP * OUTPUT
--- C.unix/help/pipeutils
--- Copyright University of Sussex 1994. All rights reserved. ----------