# 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)

*** ** * ** ***


```
class ShellProcess : AutoCloseable
```

<br />

*** ** * ** ***

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

Opposite to `https://developer.android.com/reference/kotlin/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/kotlin/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`:

```kotlin
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/kotlin/androidx/test/shell/Shell` process is a better candidate and automatically captures the full command output, as opposed to `https://developer.android.com/reference/kotlin/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/kotlin/androidx/test/shell/ShellProcess#stdOut()` from another thread, as long as this doesn't change later.

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

## Summary

| ### Public functions |
|---|---|
| `open https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` | `https://developer.android.com/reference/kotlin/androidx/test/shell/ShellProcess#close()()` Closes the current process. |
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-boolean/index.html` | `https://developer.android.com/reference/kotlin/androidx/test/shell/ShellProcess#isClosed()()` Returns whether the process is closed. |
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` | `https://developer.android.com/reference/kotlin/androidx/test/shell/ShellProcess#writeLine(kotlin.String)(string: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html)` Writes a string in the process standard input. |

| ### Public properties |
|---|---|
| `https://developer.android.com/reference/java/io/InputStream.html` | `https://developer.android.com/reference/kotlin/androidx/test/shell/ShellProcess#stdErr()` An `https://developer.android.com/reference/java/io/InputStream.html` for the process standard error. |
| `https://developer.android.com/reference/java/io/OutputStream.html` | `https://developer.android.com/reference/kotlin/androidx/test/shell/ShellProcess#stdIn()` An `https://developer.android.com/reference/java/io/OutputStream.html` for the process standard output. |
| `https://developer.android.com/reference/java/io/InputStream.html` | `https://developer.android.com/reference/kotlin/androidx/test/shell/ShellProcess#stdOut()` An `https://developer.android.com/reference/java/io/InputStream.html` for the process standard output. |

## Public functions

### close

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

```
open fun close(): Unit
```

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/kotlin/androidx/test/shell/ShellProcess#stdIn()` will be closed after the first one.

### isClosed

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

```
fun isClosed(): Boolean
```

Returns whether the process is closed.

### writeLine

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

```
fun writeLine(string: String): Unit
```

Writes a string in the process standard input.

| Parameters |
|---|---|
| `string: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html` | a utf-8 string to write in the process stdin. |

## Public properties

### stdErr

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

```
val stdErr: InputStream
```

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:

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

### stdIn

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

```
val stdIn: OutputStream
```

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

### stdOut

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

```
val stdOut: InputStream
```

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:

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