Oberon || Library || Module Index || Search Engine || Definition || Module

Ulm's Oberon Library:
UnixPipes

NAME

UnixPipes - initiate I/O to/from a process

SYNOPSIS

CONST read = UnixFiles.read; write = UnixFiles.write;



TYPE Mode = UnixFiles.Mode;
TYPE Pipe = POINTER TO PipeRec;
TYPE PipeRec = 
   RECORD
      (Streams.StreamRec)
      (* read-only components *)
      pid: SysProcess.ProcessId; (* process id of shell *)
      status: SysProcess.Status; (* set after close *)
      interrupted: BOOLEAN; (* EINTR occurred? *)
      (* read/write component *)
      retry: BOOLEAN; (* retry on interrupts? *)
   END;



TYPE Child = POINTER TO ChildRec;
TYPE ChildRec = RECORD (Disciplines.DisciplineRec) END;



PROCEDURE Open(VAR pipe: Streams.Stream;
               command: ARRAY OF CHAR; mode: Mode; bufmode: Streams.BufMode;
               errors: RelatedEvents.Object) : BOOLEAN;



PROCEDURE Spawn(VAR pipe: Streams.Stream;
                readfd, writefd, childfd: SysIO.File;
                pathname: ARRAY OF CHAR;
                argv: SysArgs.Arguments;
                mode: Mode; bufmode: Streams.BufMode;
                errors: RelatedEvents.Object) : BOOLEAN;



PROCEDURE Spawn3(command: ARRAY OF CHAR;
                 bufmode: Streams.BufMode; (* of stdin *)
                 VAR stdin, stdout, stderr: Streams.Stream;
                 errors: RelatedEvents.Object) : BOOLEAN;



PROCEDURE CreateChild(VAR child: Child);
PROCEDURE AddPipeline(child: Child;
                      readfd, writefd, childfd: SysIO.File;
                      mode: Mode; bufmode: Streams.BufMode;
                      VAR pipe: Streams.Stream);
PROCEDURE SpawnChild(child: Child;
                     pathname: ARRAY OF CHAR;
                     argv: SysArgs.Arguments;
                     errors: RelatedEvents.Object) : BOOLEAN;

DESCRIPTION

Open creates a pipe between the calling process and the command to be executed. command is a 0X-terminated string containing a shell command line. mode specifies the I/O mode, either read for reading or write for writing. The buffering mode (see Streams) is given by bufmode; Streams.onebuf should be taken for pipes opened in read mode and by default for write modes, Streams.linebuf may be appropriate for logs and other line-oriented pipes in write mode. The resulting stream pointer will be returned in pipe. The command interpreter is the system's default shell, which on UNIX systems most likely will be "/bin/sh".

Spawn offers a more flexible interface that requires the caller to setup the pipe (using, for example, SysIO.Pipe). childfd will be setup (using SysIO.Dup2) by the child as the file descriptor that is connected to the pipe. This is usually 0 or 1 (depending on mode) but sometimes other file descriptors are to be used (3 for the checkpassword interface by Dan J. Bernstein, for example). pathname and argv will be passed to SysProcess.Exec. UnixArgs is recommended to build an argument list. This allows to circumvent the interpretation of a command line by the shell and thereby avoiding the security threat of malicious shell meta characters.

An even more general interface is provided by CreateChild, AddPipeline, and SpawnChild as these procedures allow to set up an arbitrary number of pipelines between the parent process and the to be created child process. CreateChild simply creates a child reference. AddPipeline adds another pipeline with parameters that are similar to those of Spawn. AddPipeline must be called at least once. SpawnChild actually forks off the child. All pipelines returned by AddPipeline are of type Pipe and hence allow to retrieve the termination status of the child after the stream is closed.

Spawn3 invokes command and sets up three pipelines for standard input, standard output, and standard error of the child process. Note that just stdin will be of type Pipe as stdout and stderr come from PipeReaders to avoid deadlocks.

Note that UnixPipes defines an empty handler for SysSignals.PIPE.

DIAGNOSTICS

Open, Spawn, Spawn3, and SpawnChild return FALSE and relate their error events to errors in case of failures.

Errors during the access of the stream are converted into events of RelatedEvents. By default, these events are being queued.

UnixPipes uses some interruptible system calls. By default, operations are tried again in case of interruptions. Optionally, the retry field may be set to FALSE. In this case interruptions may lead to error events. The interrupt field indicates whether the last operation was interrupted or not.

SEE ALSO

PipeReaders, Process, RelatedEvents, Streams, SysIO, SysSignals, UnixArgs
Edited by: borchert, last change: 2005/02/04, revision: 1.14, converted to HTML: 2005/02/04

Oberon || Library || Module Index || Search Engine || Definition || Module