RingoJS

Module ringo/subprocess

A module for spawning processes, connecting to their input/output/errput and returning their response codes. It uses the current JVM's runtime provided by java.lang.Runtime.getRuntime(). The exact behavior of this module is highly system-dependent.

Functions

Properties

Class Process

Instance Methods

Instance Properties


Process

The Process object can be used to control and obtain information about a subprocess started using createProcess().


Process.prototype. connect (input, output, errput)

Connects the process's steams to the argument streams and starts threads to copy the data asynchronously.

Parameters

Stream input

output stream to connect to the process's input stream

Stream output

input stream to connect to the process's output stream

Stream errput

input stream to connect to the process's error stream


Process.prototype. kill ()

Kills the subprocess.


Process.prototype. stderr

The process's error stream.


Process.prototype. stdin

The process's input stream.


Process.prototype. stdout

The process's output stream.


Process.prototype. wait ()

Wait for the process to terminate and return its exit status.


command (command, [arguments...], [options])

Executes a given command and returns the standard output. If the exit status is non-zero, throws an Error. Examples:

const {command} = require("ringo/subprocess");
// get PATH environment variable on Unix-like systems const path = command("/bin/bash", "-c", "echo $PATH");
// a simple ping const result = command("ping", "-c 1", "ringojs.org");

Parameters

String command

command to call in the runtime environment

String [arguments...]

optional arguments as single or multiple string parameters. Each argument is analogous to a quoted argument on the command line.

Object [options]

options object. This may contain a dir string property specifying the directory to run the process in and a env object property specifying additional environment variable mappings.

Returns

String

the standard output of the command


createProcess (args)

Low-level function to spawn a new process. The function takes an object argument containing the following properties where all properties except command are optional:

  • command a string or array of strings containing the command to execute. Which string lists represent a valid operating system command is system-dependent.
  • dir the directory to run the process in
  • env alternative environment variables. If null the process inherits the environment of the current process.
  • binary a boolean flag that uses raw binary streams instead of text streams
  • encoding the character encoding to use for text streams

Parameters

Object args

an object containing the process command and options.

Returns

Process

a Process object

See


status (command, [arguments...], [options])

Executes a given command quietly and returns the exit status.

Parameters

String command

command to call in the runtime environment

String [arguments...]

optional arguments as single or multiple string parameters. Each argument is analogous to a quoted argument on the command line.

Object [options]

options object. This may contain a dir string property specifying the directory to run the process in and a env object property specifying additional environment variable mappings.

Returns

Number

exit status








system (command, [arguments...], [options])

Executes a given command, attached to the JVM process's output and error streams System.stdout and System.stderr, and returns the exit status.

Parameters

String command

command to call in the runtime environment

String [arguments...]

optional arguments as single or multiple string parameters. Each argument is analogous to a quoted argument on the command line.

Object [options]

options object. This may contain a dir string property specifying the directory to run the process in and a env object property specifying additional environment variable mappings.

Returns

Number

exit status