HELP PIPEUTILS

(Unix(TM) only) A.Sloman Jul 1990


Contents

Select headings to return to index

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 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. ----------