hawkinswnaf / shell-fork Goto Github PK

1. What is this?

fork is a "remote shell". It allows the user to remotely start a shell, manage jobs, and give input and take output from those jobs. This means that all jobs share fork as their parent and inherit its permissions which is great for Android applications that want to ask for SuperUser only once. All remote interactions with fork are done through fork's standard input and output. 

1a. Job control

All job control happens over standard I/O. Communication between a fork client and fork is done using an ASCII protocol: COMMAND:TAG:EXTRA: 

COMMAND: One of START, STOP, INPUT, KILL. START and STOP start and stop processes, respectively. INPUT gives input to a process. KILL kills fork itself.
TAG: Identifies the process to be acted upon by the COMMAND. The TAG must be unique among currently running processes. TAGs can be reused once the associated process has finished. 
EXTRA: Only used by START and INPUT commands. For START commands, the EXTRA gives the command line to be executed to start a job. For INPUT commands, the EXTRA gives the actual input to be sent to the process' standard input.

1b. Job output

All job output is doubly tagged by the output type and the process' tag. 

The output type is one of OUTPUT, DEBUG, and ERROR. Output tagged by DEBUG and ERROR is for debugging and error reporting, respectively. The Java API discards these messages as soon as they are received.

Output tagged by OUTPUT is actual job output. After the OUTPUT tag, the job's tag is prepended to output and separated from the actual output with a ":". E.g., 
OUTPUT:GREP: asdfasdf
OUTPUT:GREP: asdfasdf
OUTPUT:PS: dddddddddd

2. API

The user can interact with fork directly over standard I/O. However, there is an included Java API that hides most of the fork protocol from the user. See the associated JavaDoc for information on how to use that API.

3. Building

Building fork itself is done with Make:
make

This puts the fork binary in the source code's root directory. 

Building the Java API is done with Ant:
ant jar

This puts Shell.jar in the source code's root directory. There are associated unit tests that can be build and run with Ant too:
ant junit 

This builds the unit tests and executes them. Unit tests will take about 30 seconds to run. During that time, expect no output. All unit test output will be placed in a file in the source code's root directory (its filename is generated dynamically but will include the TEST- prefix).