# ShellProcess

Artifact: [androidx.test.uiautomator:uiautomator-shell](https://developer.android.com/jetpack/androidx/releases/test-uiautomator) [View Source](https://cs.android.com/search?q=file:androidx/test/shell/ShellProcess.kt+class:androidx.test.shell.ShellProcess) Added in [2.4.1](https://developer.android.com/jetpack/androidx/releases/test-uiautomator#2.4.1)

*** ** * ** ***


```
public final class ShellProcess implements AutoCloseable
```

<br />

*** ** * ** ***

Represents a process that is running sh as a shell user.

Opposite to `https://developer.android.com/reference/androidx/test/shell/Shell` this class doesn't handle the concept of command, rather it allows to read and write in the process streams, i.e. stdin, stdout, stderr. For example, using `https://developer.android.com/reference/androidx/test/shell/ShellProcess`, it's possible to write a file in shell space like `/data/local/tmp` launching `cp /dev/stdin /data/local/tmp/myfile`:

```
ShellProcess.create().use {

  // Writing a file
  it.write("cp /dev/stdin /data/local/tmp/myfile")
  it.stdin.write(myByteByffer)

  // Reading a file
  it.write("cat /data/local/tmp/somefile")
  assert(it.stdout.bufferedReader().readLine() == "This is a test")
}
```

For the vast majority of commands used for testing, `https://developer.android.com/reference/androidx/test/shell/Shell` process is a better candidate and automatically captures the full command output, as opposed to `https://developer.android.com/reference/androidx/test/shell/ShellProcess` that doesn't distinguish where a command ends and another starts.

Note that this class is not thread safe due to internal state changes, although streams can be read or written by another thread, as long as it's always the same. For example it's possible to read `https://developer.android.com/reference/androidx/test/shell/ShellProcess#stdOut()` from another thread, as long as this doesn't change later.

`https://developer.android.com/reference/androidx/test/shell/ShellProcess` should be used only when access to streams is required, like in the above example.

## Summary

| ### Public methods |
|---|---|
| `void` | `https://developer.android.com/reference/androidx/test/shell/ShellProcess#close()()` Closes the current process. |
| `final @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/io/InputStream.html` | `https://developer.android.com/reference/androidx/test/shell/ShellProcess#getStdErr()()` An `https://developer.android.com/reference/java/io/InputStream.html` for the process standard error. |
| `final @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/io/OutputStream.html` | `https://developer.android.com/reference/androidx/test/shell/ShellProcess#getStdIn()()` An `https://developer.android.com/reference/java/io/OutputStream.html` for the process standard output. |
| `final @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/io/InputStream.html` | `https://developer.android.com/reference/androidx/test/shell/ShellProcess#getStdOut()()` An `https://developer.android.com/reference/java/io/InputStream.html` for the process standard output. |
| `final boolean` | `https://developer.android.com/reference/androidx/test/shell/ShellProcess#isClosed()()` Returns whether the process is closed. |
| `final void` | `https://developer.android.com/reference/androidx/test/shell/ShellProcess#writeLine(kotlin.String)(@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/lang/String.html string)` Writes a string in the process standard input. |

## Public methods

### close

Added in [2.4.1](https://developer.android.com/jetpack/androidx/releases/test-uiautomator#2.4.1)

```
public void close()
```

Closes the current process. Internally this simply sends the shell process the exit command. This means that the process is not immediately terminated, but gracefully shutdown finishing prior commands execution. Once a shell process is closed, further calls to close don't have any effect, as the `https://developer.android.com/reference/androidx/test/shell/ShellProcess#stdIn()` will be closed after the first one.

### getStdErr

Added in [2.4.1](https://developer.android.com/jetpack/androidx/releases/test-uiautomator#2.4.1)

```
public final @NonNull InputStream getStdErr()
```

An `https://developer.android.com/reference/java/io/InputStream.html` for the process standard error. Note that this is backed by a tcp connection to the native cli utility. If a large output is expected but it's not important to capture it, a shell command may be launched piping in /dev/null.

For example:

```
cat large_file 2> /dev/null
```

### getStdIn

Added in [2.4.1](https://developer.android.com/jetpack/androidx/releases/test-uiautomator#2.4.1)

```
public final @NonNull OutputStream getStdIn()
```

An `https://developer.android.com/reference/java/io/OutputStream.html` for the process standard output.

### getStdOut

Added in [2.4.1](https://developer.android.com/jetpack/androidx/releases/test-uiautomator#2.4.1)

```
public final @NonNull InputStream getStdOut()
```

An `https://developer.android.com/reference/java/io/InputStream.html` for the process standard output. Note that this is backed by a tcp connection to the native cli utility. If a large output is expected but it's not important to capture it, a shell command may be launched piping in /dev/null.

For example:

```
cat large_file > /dev/null
```

### isClosed

Added in [2.4.1](https://developer.android.com/jetpack/androidx/releases/test-uiautomator#2.4.1)

```
public final boolean isClosed()
```

Returns whether the process is closed.

### writeLine

Added in [2.4.1](https://developer.android.com/jetpack/androidx/releases/test-uiautomator#2.4.1)

```
public final void writeLine(@NonNull String string)
```

Writes a string in the process standard input.

| Parameters |
|---|---|
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/lang/String.html string` | a utf-8 string to write in the process stdin. |