Running a Process

The following sections describe the EEL primitives for running a program. Here's a summary of the key differences among them.

   shell   concur_shell   pipe_text   winexec   run_viewer

Windows   •   •   •   •   •

Mac/Unix   •   •   •      •

Can wait   •      •   •

Searches path   •   •   •      •

Opens docs   Win   Win   Win      •

Captures output   •   •   •

Provides input      •   •

Interactive      •

Cmd line flags   •   •   •   •

Hide/max/min   •         •

Key:

Windows: Supported under Windows. Mac/Unix: Supported under macOS, Linux, and FreeBSD. Can wait: Primitive can be set to wait until subprocess has terminated before returning. Searches path: Primitive looks for executable along PATH environment variable, so executable's full path may be omitted.

Opens docs: You can provide the full path of a non-executable file instead of a program, and the appropriate program to open or display it will be run, per system settings. (Win indicates this only works under Windows.)

Captures output: Can retrieve text sent by a command-line program to its standard output into a buffer. Provides input: Can send a block of text from a buffer to a command-line program's standard input. Interactive: Can send text to a command-line program as it runs, interspersed with retrieving its output, allowing programmatic interaction.

Cmd line flags: Can run program and pass it parameters on its command line. Hide/max/min: Can set the GUI process's window hidden, or maximize or minimize it.

int shell(char *program, char *cline, char *buf, ?int flags)
The shell( ) primitive takes the name of an executable file (a program) and a command line, pushes to the program, and gives it that command line. The primitive returns the result code of the wait() system call, or -1 if an error occurred. In the latter case, the error number is in errno.

The first argument to shell( ) is the name of the actual file a program is in, including any directory prefix. The second argument to shell( ) is the command line to pass to the program.

If the first argument to shell( ) is an empty string "", Epsilon behaves differently. In this case, Epsilon runs the appropriate shell command processor. (Note that "" is not the same as NULL, a pointer whose value is 0.) If the second argument is also "", Epsilon runs the shell interactively, so that it prompts for commands. Otherwise, Epsilon makes the shell run only the command line specified in the second argument. Epsilon knows what flags to provide to the various standard shells to make them run interactively, or execute a single command and return, but you can set these if necessary. You can also set the command processor Epsilon should use. See Running Other Programs.

Under Windows, when you provide a nonempty first argument, Epsilon won't search the path for the specified file. To run a file on the path, put its name as the second argument and leave the first as "". This technique is also necessary to execute batch files, use internal commands like "dir", or do command-line redirection.

The third argument to shell( ) controls whether the output of the program is to be captured. If "", no capturing takes place. Otherwise the output is inserted in the specified buffer, replacing its previous contents.

In the Windows GUI version, and when Epsilon for Unix runs as an X11 program, Epsilon starts the program and then immediately continues without waiting for it to finish, whenever the first three arguments to shell( ) are "". Otherwise, Epsilon waits for the program to finish. The SHELL_SYNCH flag forces Epsilon to wait; the SHELL_NO_SYNCH flag tells Epsilon not to wait for the program. Under Unix, the SHELL_COPY_OUTPUT flag tells Epsilon that output captured to a buffer should also be displayed onscreen in the terminal.

The remaining flags for shell( ) only apply to the Windows version. SHELL_HIDE makes the resulting program's main window hidden; SHELL_MINIMIZED minimizes it, and SHELL_MAXIMIZED maximizes it. Normally Epsilon inserts an EPSRUNS=Y setting into the environment passed to the child process, in case some program wants to know if Epsilon invoked it. The SHELL_KEEP_ENV flag prevents that.

int do_push(char *cmdline, int cap, int show)
The do_push( ) subroutine is a convenient way to call shell( ). It uses the command processor to execute a command line (so the command line may contain redirection characters and the like). If cap is nonzero, the subroutine will capture the output of the command to the process buffer. If show is nonzero, the subroutine will arrange to show the output to the user. How it does this depends on cap. To show captured output, Epsilon displays the process buffer after the program finishes. To show non-captured output, Epsilon (non-GUI versions only) waits for the user to press a key after the program finishes, before restoring Epsilon's screen. If show is -1, Epsilon skips this step.

This subroutine interprets the variable start-process-in-buffer-directory and takes care of displaying an error to the user if the process couldn't be run.

Previous Up Next
Calling Windows DLLs Primitives and EEL Subroutines Concurrent Process Primitives