# Jaxer.Process : Object
Return to: Jaxer Framework index

Used to execute operating system processes

## Platform Support

Jaxer Server Framework | Jaxer Client Framework
--- | ---
1.0 | no

## Constructors

Constructor | Action | Jaxer Server Framework | Jaxer Client Framework
--- | --- | --- | ---
Jaxer.Process Constructor([String path,] [Boolean async]) : Jaxer.Process The constructor for an object that wraps an operating system process. This also provides static functions for more easily executing operating system processes. | Show Details | 1.0 | no

### Jaxer.Process([String path,] [Boolean async]) : Jaxer.Process

The constructor for an object that wraps an operating system process. This also provides static functions for more easily executing operating system processes.

Parameters

String | path | (optional)The absolute path to the executable file to execute. This must be specified before execution begins.
Boolean | async | (optional)By default, the process executes synchronously: it blocks until complete. If async is true, it will execute asynchronously, not blocking before completion. This can be specified at any time until execution begins.

Returns

Jaxer.Process | The wrapper around the operating system process

## Properties

Property | Action | Jaxer Server Framework | Jaxer Client Framework
--- | --- | --- | ---
_proc : Object The internal process handle (Advanced) | No Details | 1.0 | no

Visibility
  advanced

_status : Number The internal status (state) of the process: one of Jaxer.Process.CREATED, Jaxer.Process.EXEC_BEGUN, Jaxer.Process.WRITE_ENED, and Jaxer.Process.EXEC_ENDED. (Advanced) | No Details | 1.0 | no

Visibility
  advanced

readBufferSize : Number The size in bytes of the buffer to use when reading from STDOUT and STDERR. By default this is 1024 bytes. (Advanced) | No Details | 1.0 | no

Visibility
  advanced

args : Array The array of arguments to this process. | No Details | 1.0 | no

async : Boolean If true, the process will be executed asynchronously (without blocking) | No Details | 1.0 | no

autoDetachIfAsync : String Whether to detach the process (if it's asynchronous) after any writing to STDIN is complete. This is true by default Note that this property is only used by methods like exec and execAsync; you can always just explicitly detach by calling endExec. | No Details | 1.0 | no

exitStatus : Number The exit status (i.e. return code) of the process, if any. For an async process this is null. | No Details | 1.0 | no

path : String The absolute path to the executable file to execute | No Details | 1.0 | no

stderr : String How to handle the standard error stream (STDERR) from the process. If this is a string, it read from STDERR as a character stream; otherwise no reading from STDERR is performed. Note that this property is only used by methods like exec and execAsync; you can always just explicitly read from STDERR using readErrString. | No Details | 1.0 | no

stdin : String
How to handle the standard input stream (STDIN) to the process. If this is a string, it is written to STDIN as a character stream; if this is an array, it is written to STDIN as a binary (byte array) stream; otherwise no writing to STDIN is performed. Note that this property is only used by methods like exec and execAsync; you can always just explicitly write to STDIN using writeString or writeBinary.

No Details

1.0

no

stdout : String
How to handle the standard output stream (STDOUT) from the process. If this is a string, it read from STDOUT as a character stream; if this is an array, it is read from STDOUT as a binary (byte array) stream; otherwise no reading from STDOUT is performed. Note that this property is only used by methods like exec and execAsync; you can always just explicitly read from STDOUT using readString or readBinary.

No Details

1.0

no

static CREATED : Number The internal status indicating the process wrapper has been created but no execution has begun | No Details | 1.0 | no

static EXEC_BEGUN : Number The internal status indicating the process has begun executing, but any writing to STDIN is not necessarily finished | No Details | 1.0 | no

static EXEC_ENDED : Number The internal status indicating the process has finished executing or has been detached (if async) | No Details | 1.0 | no

static WRITE_ENDED : Number The internal status indicating the process has begun executing and any writing to STDIN is finished | No Details | 1.0 | no

## Functions

Method | Action | Jaxer Server Framework | Jaxer Client Framework
--- | --- | --- | ---
beginExec() : void Begins execution of the process. Any arguments to this method are treated as arguments to the process; if no arguments are given, and this.args has been set, it will be used instead. You can start to write to STDIN and read from STDOUT and STDERR after you call this method. | No Details | 1.0 | no

endExec() : Number Completes the execution of the process (if synchronous) or detaches it (if asynchronous). A running process may be stopped via kill() anytime before endExec() is called. | Show Details | 1.0 | no

Returns

Number | If the process is synchronous, its exit status (i.e. return code) is returned.

endWrite() : void Closes STDIN for further writing, which may be needed by the process before it can proceed. This is automatically called by reading anything from STDOUT and STDERR and by endExec. | No Details | 1.0 | no

exec() : Number
Executes the process. The path to the executable file should already have been set when creating the Process or via the path property. The arguments to this method are used as the arguments to the process. By default, the process is executed synchronously (i.e. it blocks), and nothing is written to STDIN nor read from STDOUT or STDERR. To override these defaults, set any of the following properties before calling this: async, stdin, stdout, stderr, and autoDetachIfAsync. If any of these are set they will be used; for stdout and stderr they will be used only if the process is synchronous, in which case they'll be set to STDOUT/STDERR. If the process is asycnhronous and autoDetachIfAsync is false, it will not be detached until it falls out of scope, so you can still read STDOUT or STDERR and kill it until it falls out of scope, at which point it will be detached; otherwise it will be detached immediately (or after any STDIN is written).

Show Details

1.0

no

Returns

Number | If the process is synchronous, its exit status (i.e. return code) is returned.

execAsync() : void
Executes the process asynchronously (i.e. without blocking). The path to the executable file should already have been set when creating the Process or via the path property. The arguments to this method are used as the arguments to the process. By default, nothing is written to STDIN, and the process is immediately detached after it is launched. To override these defaults, set stdin and/or autoDetachIfAsync on the process before calling this. If stdin is set, it will be used. If autoDetachIfAsync is not set (or set to the default value of true), the process will be detached immediately after any STDIN is written. If autoDetachIfAsync is set to false, the process will not be detached, so you can still read STDOUT or STDERR and kill it until it falls out of scope, at which point it will be detached.

No Details

1.0

no

kill() : void Kills a running process. This can only be called before endExec() has been called. | No Details | 1.0 | no

readBinary([Number maxLength]) : Array<Number> Reads the process's STDOUT stream as a byte array. | Show Details | 1.0 | no

Parameters

Number | maxLength | (optional)If specified, limits reading of STDOUT to maxLength bytes

Returns

Array<Number> | The binary value of STDOUT as an array of integers

readErrString([Number maxLength]) : String Reads the process's STDERR stream as a character string. | Show Details | 1.0 | no

Parameters

Number | maxLength | (optional)If specified, limits reading of STDERR to maxLength characters

Returns

String | The string value of STDERR

readString([Number maxLength]) : String Reads the process's STDOUT stream as a character string. | Show Details | 1.0 | no

Parameters

Number | maxLength | (optional)If specified, limits reading of STDOUT to maxLength characters

Returns

String | The string value of STDOUT

writeBinary(Array<Number> data) : void Writes the given byte array as a binary stream to the process's STDIN | Show Details | 1.0 | no

Parameters

Array<Number> | data | The byte array (array of integers)

writeString(String str) : void Writes the given string as a character stream to the process's STDIN. | Show Details | 1.0 | no

Parameters

String | str | The string to write

static exec(String path) : String
Executes the process specified by the given absolute path. Any remaining arguments to this function are used as the arguments to the process, except possibly for the last argument if it is an object, in which case it's removed and used to set options. By default, the process is executed synchronously (i.e. it blocks), and nothing is written to STDIN. To override these defaults, pass as a final argument an object containing the properties to be overridden: async, stdin, stdout, stderr, autoDetachIfAsync. If any of these are set they will be used; for stdout and stderr they will be used only if the process is synchronous, in which case their values in your object will be set to STDOUT/STDERR. For a synchronous process, the return value will be the STDOUT of the process, unless you specify stdout in your options object, in which case the return value is the exitStatus; and unless you specify stderr, an error will be thrown if the process's exitStatus is non-zero or if it writes to STDERR. If the process is executed asynchronously and autoDetachIfAsync is false, it will not be detached until it falls out of scope; otherwise it will be detached immediately (or after any STDIN is written).

Show Details

1.0

no

Parameters

String | path | The absolute path of the executable file to execute

Returns

String | For a synchronous process (without having a stdout property in an options object), returns the STDOUT of the process; otherwise does not return anything.

Examples

       document.write("The folder contains:\n" + Jaxer.Process.exec("/bin/ls")); var opts = { stdin : 'Hello world', stdout:
                              '', stderr: ''}; var exitStatus = Jaxer.Process.exec("/bin/cat", "-", opts); document.write("Finished /bin/cat with status
                              " + exitStatus + ": opts = " + uneval(opts));

static execAsync(String path) : void
Asynchronously executes the process specified by the given absolute path (so it does not block). Any remaining arguments to this function are used as the arguments to the process, except possibly for the last argument if it is an object, in which case it's removed and used to set options. By default, nothing is written to STDIN nor read from STDOUT or STDERR, and the process is immediately detached after it is launched. To override these defaults, pass as a final argument an object containing the properties to be overridden: stdin and/or autoDetachIfAsync. If stdin is set, it will be used. If autoDetachIfAsync is not set (or set to the default value of true), the process will be detached immediately after any STDIN is written. If autoDetachIfAsync is set to false, the process will not be detached until it falls out of scope, at which point it will be detached.

Show Details

1.0

no

Parameters

String | path | The absolute path of the executable file to execute

Examples

       Jaxer.Process.execAsync("/bin/sleep", 1, { autoDetachIfAsync : false } ); var opts = { stdout : ''}; Jaxer.Process.exec('/bin/ps',
                              '-ax', opts); print("Sleep is running? " + (Jaxer.Util.String.grep(opts.stdout, "/bin/sleep").length > 0)); Jaxer.Util.sleep(2000);
                              Jaxer.Process.exec('/bin/ps', '-ax', opts); print("Sleep is running? " + (Jaxer.Util.String.grep(opts.stdout, "/bin/sleep").length
                              > 0));

aptana_docs