{"__v":4,"_id":"54dd2838ca1e5219007e9dcb","category":{"__v":19,"_id":"54d5635632d98b0d00384afe","pages":["54d5635732d98b0d00384b12","54d5635732d98b0d00384b13","54d5635732d98b0d00384b14","54d847c125e90a0d00db551f","54d995416a09052100a6b6d7","54d995534c49f40d00dff98a","54d9956b4c49f40d00dff98c","54dbce210e553a0d00dc1d09","54dcdf7bac05560d00335a15","54dd133c08f6b61700a691f7","54dd136108f6b61700a691fa","54dd27e0db3b362100131294","54dd2838ca1e5219007e9dcb","54dd28c8db3b362100131296","54deb1133a91410d001b1791","54deb134c4a3570d009d4a60","54dec5c0c2b4b70d009c3f05","54ded495e8e35a0d007551a0","54ded57d8e7b000d007c7f31","551447a90edb420d0050016e","551c4369ff892b3700d1c616"],"project":"54d53c7b23010a0d001aca0c","version":"54d5635532d98b0d00384afb","sync":{"url":"","isSync":false},"reference":false,"createdAt":"2015-02-06T23:44:18.708Z","from_sync":false,"order":4,"slug":"api-plugins","title":"API Plugins"},"parentDoc":null,"project":"54d53c7b23010a0d001aca0c","user":"54cfa8e1a8a4fd0d00b7fd1d","version":{"__v":10,"_id":"54d5635532d98b0d00384afb","forked_from":"54d53c7c23010a0d001aca0f","project":"54d53c7b23010a0d001aca0c","createdAt":"2015-02-07T00:59:01.934Z","releaseDate":"2015-02-07T00:59:01.934Z","categories":["54d5635632d98b0d00384afc","54d5635632d98b0d00384afd","54d5635632d98b0d00384afe","54d5635632d98b0d00384aff","54d5635632d98b0d00384b00","54d5635632d98b0d00384b01","54d5635632d98b0d00384b02","54d652097e05890d006f153e","54dd1315ca1e5219007e9daa","54e21e2b22de1c230094b147","54e68e62a43fe13500db3879","54fa1d3fe7a0ba2f00306309","551c453a23a1ee190034d19a","551df586e52a0b23000c62b6","551f39be6886f8230055f02a","55a6720751457325000e4d97"],"is_deprecated":false,"is_hidden":false,"is_beta":true,"is_stable":true,"codename":"","version_clean":"0.1.0","version":"0.1"},"updates":[],"next":{"pages":[],"description":""},"createdAt":"2015-02-12T22:24:56.615Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"auth":"required","params":[],"url":""},"isReference":false,"order":5,"body":"Plugins often want to interact with files, processes and network within the user's workspace. Because all Cloud9 plugins run in the browser and there is a network between the browser and the user's workspace we looked for an API that would work asynchronously. The Node.js APIs were an obvious match and so we based our Filesystem (`fs`), Process (`proc`) and Network (`net`) APIs on Node's fs, child_process and net modules.\n\n# Getting a reference to the plugin\n\nThe following examples show how to gain access to the `proc` API.\n\nFirst, make sure to add \"proc\" to your list of plugins you depend on like so:\n\n```\nmain.consumes = [\"Plugin\", \"proc\"];\n```\n\nAnd then get a reference to the plugin in the main function:\n\n```\nfunction main(options, imports, register) {\n    var proc = imports.proc;\n```\n\n# Process\n\n*For a complete reference to all the methods and events of the `proc` plugin check out the [proc api reference](https://docs.c9.io/api/#!/api/proc).*\n\nThe following table lists of all the methods supported by the `proc` plugin. \n[block:html]\n{\n  \"html\": \"<table>\\n  <tr><th>execFile</th><td>Executes an executable file in the workspace and buffers the stdout and stderr until the process is complete.</td></tr>\\n<tr><th>pty</th><td>Spawns a child process in a PTY and returns a stream object.</td></tr>\\n<tr><th>spawn</th><td>Spawns a child process and returns a process object complete with three stdio streams.</td></tr>\\n<tr><th>tmux</th><td>Spawns a child process in a TMUX session and returns a stream object.</td></tr>\\n</table>\"\n}\n[/block]\nThe following examples show some of the most common use cases dealing with processes. The paths are always absolute or when specifying only a filename, the executable will be looked up in the PATH environment variable.\n\nExecuting a utility and fetching the output as a string:\n```\nproc.execFile(\"find\", { \n    args: [\".\"],\n    cwd: \"/home/ubuntu/workspace\"\n}, function(err, stdout, stderr) {\n    if (err) return console.error(err);\n\n    console.log(stderr, stdout);\n});\n```\n\nExecuting a long running process and interacting using stderr and stdin\n```\nproc.spawn(\"python\", {\n    args: [\"-i\"]\n}, function(err, process) {\n    if (err) return console.error(err);\n\n    var executed;\n    process.stderr.on(\"data\", function(chunk) {\n        console.log(chunk);    \n\n        if (chunk.indexOf(\">>>\") > -1) {\n            if (!executed) \n                process.stdin.write(\"1+1\\n\");\n            else \n                process.stdin.write(\"exit()\\n\");\n            executed = true;\n        }\n    });\n    process.on(\"exit\", function(code) {\n        console.log(\"Process Stopped\"); \n    });\n});\n```\n\n## Long Running Processes\n\nIn some cases you want a process to run for a long time, surviving the session of the user. When the user's session ends, the vfs process in the user's workspace will kill all it's child processes - which include all the processes started with the API described above. If you don't want this to happen call `unref()` to detach your process from it's parent.\n\n```\nprocess.unref();\n```","excerpt":"","slug":"the-process-api","type":"basic","title":"The Process API"}
Plugins often want to interact with files, processes and network within the user's workspace. Because all Cloud9 plugins run in the browser and there is a network between the browser and the user's workspace we looked for an API that would work asynchronously. The Node.js APIs were an obvious match and so we based our Filesystem (`fs`), Process (`proc`) and Network (`net`) APIs on Node's fs, child_process and net modules. # Getting a reference to the plugin The following examples show how to gain access to the `proc` API. First, make sure to add "proc" to your list of plugins you depend on like so: ``` main.consumes = ["Plugin", "proc"]; ``` And then get a reference to the plugin in the main function: ``` function main(options, imports, register) { var proc = imports.proc; ``` # Process *For a complete reference to all the methods and events of the `proc` plugin check out the [proc api reference](https://docs.c9.io/api/#!/api/proc).* The following table lists of all the methods supported by the `proc` plugin. [block:html] { "html": "<table>\n <tr><th>execFile</th><td>Executes an executable file in the workspace and buffers the stdout and stderr until the process is complete.</td></tr>\n<tr><th>pty</th><td>Spawns a child process in a PTY and returns a stream object.</td></tr>\n<tr><th>spawn</th><td>Spawns a child process and returns a process object complete with three stdio streams.</td></tr>\n<tr><th>tmux</th><td>Spawns a child process in a TMUX session and returns a stream object.</td></tr>\n</table>" } [/block] The following examples show some of the most common use cases dealing with processes. The paths are always absolute or when specifying only a filename, the executable will be looked up in the PATH environment variable. Executing a utility and fetching the output as a string: ``` proc.execFile("find", { args: ["."], cwd: "/home/ubuntu/workspace" }, function(err, stdout, stderr) { if (err) return console.error(err); console.log(stderr, stdout); }); ``` Executing a long running process and interacting using stderr and stdin ``` proc.spawn("python", { args: ["-i"] }, function(err, process) { if (err) return console.error(err); var executed; process.stderr.on("data", function(chunk) { console.log(chunk); if (chunk.indexOf(">>>") > -1) { if (!executed) process.stdin.write("1+1\n"); else process.stdin.write("exit()\n"); executed = true; } }); process.on("exit", function(code) { console.log("Process Stopped"); }); }); ``` ## Long Running Processes In some cases you want a process to run for a long time, surviving the session of the user. When the user's session ends, the vfs process in the user's workspace will kill all it's child processes - which include all the processes started with the API described above. If you don't want this to happen call `unref()` to detach your process from it's parent. ``` process.unref(); ```