Add documentation for node.Process

1 files changed, 61 insertions, 0 deletions

diff --git a/website/api.html b/website/api.html
index 59bb15a4a..3b3bcdbaf 100644
--- a/website/api.html
+++ b/website/api.html
@@ -13,6 +13,7 @@
 <div id="toc">
   <ol>
     <li><a href="#timers">Timers</a></li>
+    <li><a href="#processes">Processes</a></li>
     <li>
       <a href="#files">File I/O</a>
       <ol>
@@ -130,6 +131,66 @@
     <dd>Stops a interval from triggering.</dd>
   </dl>
 
+  <h2 id="processes">Processes and IPC</h2>
+
+  <p>
+    Node provides a tridirectional <code>popen(3)</code> facility.
+    It is possible to stream data through the child's <code>stdin</code>,
+    <code>stdout</code>, and <code>stderr</code> in a fully non-blocking
+    way.
+  </p>
+
+  <dl>
+    <dt><code>new node.Process(command)</code></dt>
+    <dd>Launches a new process with the given <code>command</code>. For example:
+    <pre>var ls = new Process("ls -lh /usr");</pre> 
+    </dd>
+
+    <dt><code>process.pid</code></dt>
+    <dd>The PID of the child process.</dd>
+
+    <dt><code>process.onOutput = function (chunk) { };</code></dt>
+    <dd>A callback to receive output from the process's <code>stdout</code>. 
+    At the moment the received data is always a string and utf8 encoded.
+    (More encodings will be supported in the future.)
+
+    <p>If the process closes it's <code>stdout</code>, this callback will
+    be issued with <code>null</code> as an argument. Be prepared for this
+    possibility.
+    </dd>
+
+    <dt><code>process.onError = function (chunk) { };</code></dt>
+    <dd>A callback to receive output from the process's <code>stderr</code>. 
+    At the moment the received data is always a string and utf8 encoded.
+    (More encodings will be supported in the future.)
+
+    <p>If the process closes it's <code>stderr</code>, this callback will
+    be issued with <code>null</code> as an argument. Be prepared for this
+    possibility.
+    </dd>
+
+    <dt><code>process.onExit = function (exit_code) { };</code></dt>
+    <dd>A callback which is called when the sub-process exits. The argument
+    is the exit status of the child.
+    </dd>
+
+    <dt><code>process.write(data, encoding="ascii");</code></dt>
+    <dd>Write data to the child process's <code>stdin</code>. The second
+    argument is optional and specifies the encoding: possible values are
+    <code>"utf8"</code>, <code>"ascii"</code>, and <code>"raw"</code>.
+    </dd>
+
+    <dt><code>process.close();</code></dt>
+    <dd>Closes the processes <code>stdin</code> stream.</dd>
+
+    <dt><code>process.kill(signal=node.SIGTERM);</code></dt>
+    <dd>Kills the child process with the given signal. If no argument is
+    given, the process will be sent <code>node.SIGTERM</code>. The standard
+    POSIX signals are defined under the <code>node</code> namespace (e.g.
+    <code>node.SIGINT</code>, <code>node.SIGUSR1</code>).
+    </dd>
+  </dl>
+
   <h2 id="files"><code>node.fs</code></h2>
 
   <p>