### Starting a Root Service as a Task

Source: https://topjohnwu.github.io/libsu/com/topjohnwu/superuser/ipc/RootService.html

These methods allow binding to a RootService and optionally creating a task to launch a new root process if needed. This is useful for managing the service lifecycle more explicitly.

```APIDOC
## bindOrTask(Intent intent, Executor executor, ServiceConnection conn)

### Description
Bind to a root service, creating a task to launch a new root process if needed. This overload includes an Executor for asynchronous operations.

### Method
static Shell.Task

### Parameters
- **intent** (Intent) - The intent specifying the service to bind to.
- **executor** (Executor) - The executor to use for the operation.
- **conn** (ServiceConnection) - The connection to be established with the service.

### Returns
- Shell.Task - A task object that can be used to manage the operation.
```

--------------------------------

### FileSystemManager.getService

Source: https://topjohnwu.github.io/libsu/index-all.html

Gets the service that exports the file system of the current process over Binder IPC. This is a lower-level method for accessing the file system service.

```APIDOC
## getService()

### Description
Get the service that exports the file system of the current process over Binder IPC.

### Method
Static method in class com.topjohnwu.superuser.nio.FileSystemManager
```

--------------------------------

### Shell.getShell (async with callback)

Source: https://topjohnwu.github.io/libsu/index-all.html

Gets the main shell instance asynchronously using a callback. This is useful when shell initialization might take time and should not block the main thread.

```APIDOC
## getShell(Shell.GetShellCallback)

### Description
Get the main shell instance asynchronously via a callback.

### Method
Static method in class com.topjohnwu.superuser.Shell
```

--------------------------------

### Shell.getShell

Source: https://topjohnwu.github.io/libsu/index-all.html

Gets the main shell instance. This can be called synchronously to obtain the shell.

```APIDOC
## getShell()

### Description
Get the main shell instance.

### Method
Static method in class com.topjohnwu.superuser.Shell
```

--------------------------------

### Accessing FileSystemManager

Source: https://topjohnwu.github.io/libsu/com/topjohnwu/superuser/nio/FileSystemManager.html

Provides methods to get the local FileSystemManager instance or a remote one via a Binder.

```APIDOC
## getService

### Description
Get the service that exports the file system of the current process over Binder IPC. Sending the Binder obtained from this method to a client process enables the current process to perform file system operations on behalf of the client. This allows a client process to access files normally denied by its permissions. This method is usually called in a root process, and the Binder service returned will be send over to a non-root client process. You can pass this Binder object in multiple ways, such as returning it in the `onBind()` method of root services, passing it around in a `Bundle`, or returning it in an AIDL interface method. The receiving end will get an `IBinder`, which the developer should then pass to `getRemote(IBinder)` for usage.

### Method
GET

### Endpoint
/getService

### Returns
- **Binder** - The Binder service for file system operations.
```

```APIDOC
## getLocal

### Description
Get the `FileSystemManager` to access the file system of the current local process.

### Method
GET

### Endpoint
/getLocal

### Returns
- **FileSystemManager** - The local FileSystemManager instance.
```

```APIDOC
## getRemote

### Description
Create a `FileSystemManager` to access the file system of a remote process. Several APIs are not supported through a remote process: `File.deleteOnExit()`, `FileChannel.map()`, `FileChannel.lock()`, `FileChannel.lock(long, long, boolean)`, `FileChannel.tryLock()`, `FileChannel.tryLock(long, long, boolean)`. Calling these APIs will throw `UnsupportedOperationException`.

### Method
POST

### Endpoint
/getRemote

### Parameters
#### Request Body
- **binder** (IBinder) - Required - A remote proxy of the `Binder` obtained from `getService()`

### Returns
- **FileSystemManager** - A FileSystemManager instance for the remote process.

### Throws
- **RemoteException** - if the remote process has died.
```

--------------------------------

### FileSystemManager.getLocal

Source: https://topjohnwu.github.io/libsu/index-all.html

Gets the `FileSystemManager` instance for accessing the file system of the current local process. This is the default way to interact with local files.

```APIDOC
## getLocal()

### Description
Get the `FileSystemManager` to access the file system of the current local process.

### Method
Static method in class com.topjohnwu.superuser.nio.FileSystemManager
```

--------------------------------

### Shell.getShell (async with executor and callback)

Source: https://topjohnwu.github.io/libsu/index-all.html

Gets the main shell instance asynchronously using a specified executor and a callback. This provides more control over the execution context for the asynchronous shell retrieval.

```APIDOC
## getShell(Executor, Shell.GetShellCallback)

### Description
Get the main shell instance asynchronously via a callback.

### Method
Static method in class com.topjohnwu.superuser.Shell
```

--------------------------------

### onInit

Source: https://topjohnwu.github.io/libsu/com/topjohnwu/superuser/Shell.Initializer.html

This method is called when a new shell is constructed. It allows for custom initialization logic to be executed.

```APIDOC
## onInit(Context context, Shell shell)

### Description
Called when a new shell is constructed.

### Method
public boolean onInit(@NonNull Context context, @NonNull Shell shell)

### Parameters
#### Path Parameters
- **context** (Context) - Required - the application context.
- **shell** (Shell) - Required - the newly constructed shell.

### Response
#### Success Response (boolean)
- **true** when initialization is successful.
- **false** when initialization fails.
```

--------------------------------

### SuFile.getFilePointer

Source: https://topjohnwu.github.io/libsu/index-all.html

Gets the current position of the file pointer in a random access file. This is relevant for `SuRandomAccessFile` operations.

```APIDOC
## getFilePointer()

### Description
Get the file pointer of the file.

### Method
Method in class com.topjohnwu.superuser.io.SuRandomAccessFile
```

--------------------------------

### SuFile

Source: https://topjohnwu.github.io/libsu/allclasses-index.html

A `File` implementation using root shell.

```APIDOC
## Class SuFile

### Description
A `File` implementation using root shell.

### Type
Class
```

--------------------------------

### Shell.Result.getOut

Source: https://topjohnwu.github.io/libsu/index-all.html

Gets the standard output (STDOUT) from a shell command execution. This contains the primary results of the command.

```APIDOC
## getOut()

### Description
Get the output of STDOUT.

### Method
Method in class com.topjohnwu.superuser.Shell.Result
```

--------------------------------

### mkdirs()

Source: https://topjohnwu.github.io/libsu/com/topjohnwu/superuser/io/SuFile.html

Creates the directory and any necessary but nonexistent parent directories. Requires the 'mkdir' command.

```APIDOC
## mkdirs()

### Description
Creates the directory named by this abstract pathname, including any necessary but nonexistent parent directories.

### Requires
`mkdir` command.

### Overrides
`mkdirs` in class `File`
```

--------------------------------

### Shell.Result.getErr

Source: https://topjohnwu.github.io/libsu/index-all.html

Gets the standard error output (STDERR) from a shell command execution. This is useful for diagnosing errors.

```APIDOC
## getErr()

### Description
Get the output of STDERR.

### Method
Method in class com.topjohnwu.superuser.Shell.Result
```

--------------------------------

### Job Construction and Execution

Source: https://topjohnwu.github.io/libsu/com/topjohnwu/superuser/Shell.Job.html

This section covers the basic methods for creating a job, adding commands or input streams, and executing the job immediately.

```APIDOC
## Job()

### Description
Constructs a new Job.

### Constructor
`Job()`
```

```APIDOC
## add(String... cmds)

### Description
Add a new operation running commands.

### Method
`add`

### Parameters
#### Path Parameters
- **cmds** (String...) - Required - The commands to run.

### Returns
`Shell.Job` - this Job object for chaining of calls.
```

```APIDOC
## add(InputStream in)

### Description
Add a new operation serving an InputStream to STDIN. This is NOT executing the script like `sh script.sh`. This is similar to sourcing the script (`. script.sh`) as the raw content of the script is directly fed into STDIN. If you call `exit` in the script, the shell will be killed and this shell instance will no longer be alive!

### Method
`add`

### Parameters
#### Path Parameters
- **in** (InputStream) - Required - The InputStream to serve to STDIN. The stream will be closed after consumption.

### Returns
`Shell.Job` - this Job object for chaining of calls.
```

```APIDOC
## exec()

### Description
Execute the job immediately and returns the result.

### Method
`exec`

### Returns
`Shell.Result` - the result of the job.
```

--------------------------------

### SuFile Constructors

Source: https://topjohnwu.github.io/libsu/com/topjohnwu/superuser/io/SuFile.html

Constructors for creating SuFile instances with different path specifications.

```APIDOC
## SuFile Constructors

### SuFile(String pathname)
Creates a new SuFile instance with the specified pathname.

### SuFile(String parent, String child)
Creates a new SuFile instance given a parent pathname string and a child pathname string.

### SuFile(File parent, String child)
Creates a new SuFile instance given a parent abstract pathname and a child pathname string.

### SuFile(URI uri)
Creates a new SuFile instance from a URI.
```

--------------------------------

### SuFile.getChildFile

Source: https://topjohnwu.github.io/libsu/index-all.html

Gets a child file relative to the current abstract pathname. This is useful for navigating the file system hierarchy.

```APIDOC
## getChildFile(String)

### Description
Create a child relative to the abstract pathname using the same file system backend.

### Method
Method in class com.topjohnwu.superuser.io.SuFile
```

--------------------------------

### Shell.Result.getCode

Source: https://topjohnwu.github.io/libsu/index-all.html

Gets the return code of a shell command execution. A return code of 0 typically indicates success.

```APIDOC
## getCode()

### Description
Get the return code of the job.

### Method
Method in class com.topjohnwu.superuser.Shell.Result
```

--------------------------------

### newInputStream()

Source: https://topjohnwu.github.io/libsu/com/topjohnwu/superuser/io/SuFile.html

Opens an InputStream with the matching file system backend of the file. Throws IOException.

```APIDOC
## newInputStream()

### Description
Opens an InputStream with the matching file system backend of the file.

### Method
`@NonNull public InputStream newInputStream() throws IOException`

### Throws
* `IOException`

### See Also
* `FileInputStream(File)`
```

--------------------------------

### Shell.Builder.build (with commands)

Source: https://topjohnwu.github.io/libsu/com/topjohnwu/superuser/Shell.Builder.html

Builds a new Shell instance using the provided commands.

```APIDOC
## Method

### build

`@NonNull public final Shell build(String... commands)`

Combine all of the options that have been set and build a new `Shell` instance with the provided commands.

Parameters:
    `commands` - commands that will be passed to `Runtime.exec(String[])` to create a new `Process`.

Returns:
    the built `Shell` instance.

Throws:
    `NoShellException` - the provided command cannot create a `Shell` instance, or initialization failed when using the configured `Shell.Initializer`s.
```

--------------------------------

### Shell.Builder.build (with process)

Source: https://topjohnwu.github.io/libsu/com/topjohnwu/superuser/Shell.Builder.html

Builds a new Shell instance using a pre-created process.

```APIDOC
## Method

### build

`@NonNull public abstract Shell build(Process process)`

Combine all of the options that have been set and build a new `Shell` instance with the provided process.

Parameters:
    `process` - a shell `Process` that has already been created.

Returns:
    the built `Shell` instance.

Throws:
    `NoShellException` - the provided process is not a valid shell, or initialization failed when using the configured `Shell.Initializer`s.
```

--------------------------------

### list()

Source: https://topjohnwu.github.io/libsu/com/topjohnwu/superuser/io/SuFile.html

Returns an array of strings naming the files and directories in the directory. Requires the 'ls' command.

```APIDOC
## list()

### Description
Returns an array of strings naming the files and directories in the directory denoted by this abstract pathname.

### Requires
`ls` command.

### Overrides
`list` in class `File`
```

--------------------------------

### SuFile Methods

Source: https://topjohnwu.github.io/libsu/index-all.html

Methods for interacting with files and directories using SuFile.

```APIDOC
## SuFile Methods

### isBlock()

Checks if the file is a block device.

### isCharacter()

Checks if the file is a character device.

### isDirectory()

Checks if the file is a directory.

### isFile()

Checks if the file is a regular file.

### isNamedPipe()

Checks if the file is a named pipe.

### isSocket()

Checks if the file is a socket.

### isSymlink()

Checks if the file is a symbolic link.

### lastModified()

Returns the last modified time of the file.

### length()

Returns the length of the file.

### list()

Returns an array of names of files and directories in the directory.

### list(FilenameFilter)

Returns an array of names of files and directories in the directory that satisfy the specified filter.

### listFiles()

Returns an array of abstract pathnames denoting the files in the directory.

### listFiles(FileFilter)

Returns an array of abstract pathnames denoting the files in the directory that satisfy the specified filter.

### listFiles(FilenameFilter)

Returns an array of abstract pathnames denoting the files in the directory that satisfy the specified filter.
```

--------------------------------

### SuRandomAccessFile Methods

Source: https://topjohnwu.github.io/libsu/index-all.html

Methods for random access file operations.

```APIDOC
## SuRandomAccessFile Methods

### length()

Returns the length of the file.
```

--------------------------------

### FileSystemManager.getFile (multiple overloads)

Source: https://topjohnwu.github.io/libsu/index-all.html

Provides various ways to obtain a `FileSystemManager` instance to access file systems. This includes accessing the local file system, remote file systems via `IBinder`, and creating file objects from paths or URIs.

```APIDOC
## getFile(File, String)
## getFile(String)
## getFile(String, String)
## getFile(URI)

### Description
Provides methods to get a `FileSystemManager` instance to access different file systems.

### Method
Methods in class com.topjohnwu.superuser.nio.FileSystemManager
```

--------------------------------

### Binding with Task Creation

Source: https://topjohnwu.github.io/libsu/com/topjohnwu/superuser/ipc/RootService.html

This method binds to a root service and creates a task to launch a new root process if needed. It returns a `Shell.Task` that must be executed to initiate the process launch.

```APIDOC
## bindOrTask

### Description
Bind to a root service, creating a task to launch a new root process if needed. If the application is already connected to a root process, binding will happen immediately and this method will return `null`. Or else this method returns a `Shell.Task` that has to be executed to launch the root process. Binding will only happen after the developer has executed the returned task with `Shell.execTask(Shell.Task)`.

### Method
`@MainThread @Nullable public static Shell.Task bindOrTask(@NonNull Intent intent, @NonNull Executor executor, @NonNull ServiceConnection conn)`

### Parameters
- `intent` (Intent) - Required - Identifies the service to connect to.
- `executor` (Executor) - Required - Callbacks on ServiceConnection will be called on this executor.
- `conn` (ServiceConnection) - Required - Receives information as the service is started and stopped.

### Returns
- `Shell.Task` - The task to launch a root process. If there is no need to launch a new root process, `null` is returned.

### See Also
`bind(Intent, Executor, ServiceConnection)`
```

--------------------------------

### SuFile Constructors

Source: https://topjohnwu.github.io/libsu/com/topjohnwu/superuser/io/SuFile.html

Constructors for creating SuFile objects.

```APIDOC
## Constructors

### `SuFile(File parent, String child)`
Creates a new `SuFile` instance from a parent `File` object and a child pathname string.

### `SuFile(String pathname)`
Creates a new `SuFile` instance from a pathname string.

### `SuFile(String parent, String child)`
Creates a new `SuFile` instance from a parent pathname string and a child pathname string.

### `SuFile(URI uri)`
Creates a new `SuFile` instance from a `URI` object.
```

--------------------------------

### Shell Builder Methods

Source: https://topjohnwu.github.io/libsu/index-all.html

Methods for building a Shell instance with various configurations.

```APIDOC
## create()

### Description
Create a new `Shell.Builder`.

### Method
Static method in class com.topjohnwu.superuser.Shell.Builder

## build()

### Description
Combine all of the options that have been set and build a new `Shell` instance.

### Method
Method in class com.topjohnwu.superuser.Shell.Builder

## build(Process)

### Description
Combine all of the options that have been set and build a new `Shell` instance with the provided process.

### Method
Method in class com.topjohnwu.superuser.Shell.Builder

### Parameters
- **process** (Process) - The process to build the shell with.

## build(String...)

### Description
Combine all of the options that have been set and build a new `Shell` instance with the provided commands.

### Method
Method in class com.topjohnwu.superuser.Shell.Builder

### Parameters
- **commands** (String...) - The commands to include in the new shell instance.
```

--------------------------------

### Shell.Builder.build (default commands)

Source: https://topjohnwu.github.io/libsu/com/topjohnwu/superuser/Shell.Builder.html

Builds a new Shell instance using default commands or fallback mechanisms.

```APIDOC
## Method

### build

`@NonNull public abstract Shell build()`

Combine all of the options that have been set and build a new `Shell` instance. If not `setCommands(String...)`, there are 3 methods to construct a Unix shell; if any method fails, it will fallback to the next method:
  1. If `Shell.FLAG_NON_ROOT_SHELL` is not set and `Shell.FLAG_MOUNT_MASTER` is set, construct a Unix shell by calling `su --mount-master`. It may fail if the root implementation does not support mount master.
  2. If `Shell.FLAG_NON_ROOT_SHELL` is not set, construct a Unix shell by calling `su`. It may fail if the device is not rooted, or root permission is not granted.
  3. Construct a Unix shell by calling `sh`. This would never fail in normal conditions, but should it fail, it will throw `NoShellException`
The developer should check the status of the returned `Shell` with `Shell.getStatus()` since it may be constructed with calling `sh`.
If `setCommands(String...)` is called, the provided commands will be used to create a new `Process` directly. If the process fails to create, or the process is not a valid shell, it will throw `NoShellException`.

Returns:
    the created `Shell` instance.

Throws:
    `NoShellException` - impossible to construct a `Shell` instance, or initialization failed when using the configured `Shell.Initializer`s.
```

--------------------------------

### onAddElement Method

Source: https://topjohnwu.github.io/libsu/com/topjohnwu/superuser/CallbackList.html

Abstract method to be implemented by subclasses to handle new elements added to the list.

```APIDOC
## onAddElement(E e)

### Description
This callback is invoked after an element is added to the list. The thread on which this method is executed depends on the constructor used.

### Method
`public abstract void onAddElement(E e)`

### Parameters
* **e** (E) - The new element that was added to the list.
```

--------------------------------

### mkdir()

Source: https://topjohnwu.github.io/libsu/com/topjohnwu/superuser/io/SuFile.html

Creates the directory named by this abstract pathname. Requires the 'mkdir' command.

```APIDOC
## mkdir()

### Description
Creates the directory named by this abstract pathname.

### Requires
`mkdir` command.

### Overrides
`mkdir` in class `File`
```

--------------------------------

### Shell Instance Management

Source: https://topjohnwu.github.io/libsu/com/topjohnwu/superuser/Shell.html

Methods for obtaining and managing the main Shell instance. These methods are crucial for interacting with the device's shell, especially for root operations.

```APIDOC
## getShell()

### Description
Get the main shell instance. If no shell is cached, a new one will be constructed using the default builder. This method may block until the shell is created, potentially a long time if root permission is requested.

### Method
`public static Shell getShell()

### Returns
the cached/created main shell instance.

### See Also
`Shell.Builder.build()`
```

```APIDOC
## getShell(GetShellCallback callback)

### Description
Get the main shell instance asynchronously via a callback. If no shell is cached, a new one will be constructed in a background thread. The result is returned to the callback on the main thread.

### Method
`public static void getShell(@NonNull Shell.GetShellCallback callback)

### Parameters
* `callback` - invoked when a shell is acquired.
```

```APIDOC
## getShell(Executor executor, GetShellCallback callback)

### Description
Get the main shell instance asynchronously via a callback, using a specified executor for the callback. If no shell is cached, a new one will be constructed in a background thread.

### Method
`public static void getShell(@Nullable Executor executor, @NonNull Shell.GetShellCallback callback)

### Parameters
* `executor` - the executor used to handle the result callback event. If null, the callback can run on any thread.
* `callback` - invoked when a shell is acquired.
```

```APIDOC
## getCachedShell()

### Description
Get the cached main shell instance without creating a new one if it doesn't exist. Returns null if no shell is cached or the cached shell is inactive.

### Method
`@Nullable public static Shell getCachedShell()

### Returns
a `Shell` instance, or `null`.
```

--------------------------------

### SuFile Factory Methods

Source: https://topjohnwu.github.io/libsu/com/topjohnwu/superuser/io/SuFile.html

Factory methods for obtaining SuFile instances. These methods will return a normal File instance if the main shell does not have root access, otherwise, they return a SuFile instance. Warning: these factory methods may block the calling thread if a main shell has not been created yet.

```APIDOC
## SuFile.open(...)

### Description
Factory method to obtain a `File` instance. Returns a `SuFile` if root access is available, otherwise a normal `File`.

### Parameters
* **path** (String) - The path to the file.
* **context** (Context) - The application context.

### Returns
* `File` - An instance of `SuFile` or a normal `File`.
```

--------------------------------

### FileSystemManager Constructor

Source: https://topjohnwu.github.io/libsu/index-all.html

Constructor for `FileSystemManager`.

```APIDOC
## FileSystemManager()

### Description
Constructor for `FileSystemManager`.

### Method
`FileSystemManager()`

### Class
`com.topjohnwu.superuser.nio.FileSystemManager`
```

--------------------------------

### Opening a SuRandomAccessFile

Source: https://topjohnwu.github.io/libsu/com/topjohnwu/superuser/io/SuRandomAccessFile.html

Opens a SuRandomAccessFile for the specified file and mode. This method can be used to create or access files.

```APIDOC
## open

### Description
Opens a `SuRandomAccessFile` for the specified file and mode.

### Method
`public static SuRandomAccessFile open(@NonNull File file, String mode)`

### Parameters
#### Path Parameters
- **file** (`File`) - Required - The file object to open.
- **mode** (`String`) - Required - The access mode. Note: `rws`, `rwd` behave the same as `rw` if a shell-backed implementation is used.

### Throws
- `FileNotFoundException`

### See Also
- `RandomAccessFile(File, String)`
```

```APIDOC
## open

### Description
Opens a `SuRandomAccessFile` for the specified file path and mode.

### Method
`public static SuRandomAccessFile open(@NonNull String path, String mode)`

### Parameters
#### Path Parameters
- **path** (`String`) - Required - The path to the file to open.
- **mode** (`String`) - Required - The access mode. Note: `rws`, `rwd` behave the same as `rw` if a shell-backed implementation is used.

### Throws
- `FileNotFoundException`

### See Also
- `SuRandomAccessFile.open(File, String)`
```

--------------------------------

### SuRandomAccessFile

Source: https://topjohnwu.github.io/libsu/allclasses-index.html

Access files using the main shell and mimics `RandomAccessFile`.

```APIDOC
## Class SuRandomAccessFile

### Description
Access files using the main shell and mimics `RandomAccessFile`.

### Type
Class
```

--------------------------------

### ShellUtils

Source: https://topjohnwu.github.io/libsu/allclasses-index.html

Some handy utility methods that are used in `libsu`.

```APIDOC
## Class ShellUtils

### Description
Some handy utility methods that are used in `libsu`.

### Type
Class
```

--------------------------------

### Shell.Builder.create

Source: https://topjohnwu.github.io/libsu/com/topjohnwu/superuser/Shell.Builder.html

Creates a new Shell.Builder instance.

```APIDOC
## Static Method

### create

`@NonNull public static Shell.Builder create()`

Create a new `Shell.Builder`.

Returns:
    a new Builder object.
```

--------------------------------

### Constructors

Source: https://topjohnwu.github.io/libsu/index-all.html

Constructors for initializing objects.

```APIDOC
## Constructors

### Initializer()

Constructor for class com.topjohnwu.superuser.Shell.Initializer.

### Job()

Constructor for class com.topjohnwu.superuser.Shell.Job.
```

--------------------------------

### newOutputStream(boolean append)

Source: https://topjohnwu.github.io/libsu/com/topjohnwu/superuser/io/SuFile.html

Opens an OutputStream with the matching file system backend of the file. Throws IOException.

```APIDOC
## newOutputStream(boolean append)

### Description
Opens an OutputStream with the matching file system backend of the file.

### Method
`@NonNull public OutputStream newOutputStream(boolean append) throws IOException`

### Throws
* `IOException`

### See Also
* `FileOutputStream(File, boolean)`
```

--------------------------------

### open(String path, boolean append)

Source: https://topjohnwu.github.io/libsu/com/topjohnwu/superuser/io/SuFileOutputStream.html

Opens an OutputStream with root access for the specified file path, with an option to append to the file.

```APIDOC
## open(String path, boolean append)

### Description
Opens an `OutputStream` with root access for the specified file path. If `append` is true, data will be written to the end of the file rather than overwriting it.

### Method
`public static OutputStream open(@NonNull String path, boolean append)`

### Parameters
* **path** (String) - Required - The path to the file.
* **append** (boolean) - Required - `true` to append to the file, `false` to overwrite.

### Throws
* `FileNotFoundException` - If the file cannot be opened.

### See Also
* `FileOutputStream(File, boolean)`
```

--------------------------------

### SuRandomAccessFile

Source: https://topjohnwu.github.io/libsu/index-all.html

Provides random access file operations with root privileges.

```APIDOC
## SuRandomAccessFile

### Description
Provides random access file operations with root privileges.

### Methods
- `seek(long)`: Moves the file pointer to the specified position.
- `setLength(long)`: Sets the length of the file.
```

--------------------------------

### Managing Shell Instances

Source: https://topjohnwu.github.io/libsu/com/topjohnwu/superuser/Shell.html

APIs for obtaining and managing the main shell instance, including asynchronous retrieval and caching.

```APIDOC
## getShell()

### Description
Gets the main shell instance. This is a globally shared shell that is constructed on-demand and cached.

### Method
`static Shell`
```

```APIDOC
## getCachedShell()

### Description
Gets the cached main shell instance without creating a new one if it doesn't exist.

### Method
`static Shell`
```

```APIDOC
## getShell(Shell.GetShellCallback callback)

### Description
Gets the main shell instance asynchronously via a callback.

### Method
`static void`

### Parameters
- `callback` (Shell.GetShellCallback) - The callback to receive the shell instance.
```

```APIDOC
## getShell(Executor executor, Shell.GetShellCallback callback)

### Description
Gets the main shell instance asynchronously via a callback, using the provided executor for the callback.

### Method
`static void`

### Parameters
- `executor` (Executor) - The executor to use for the callback.
- `callback` (Shell.GetShellCallback) - The callback to receive the shell instance.
```

```APIDOC
## setDefaultBuilder(Shell.Builder builder)

### Description
Overrides the default `Shell.Builder` used for creating new shell instances.

### Method
`static void`

### Parameters
- `builder` (Shell.Builder) - The custom builder to set.
```

--------------------------------

### Constructor Details

Source: https://topjohnwu.github.io/libsu/com/topjohnwu/superuser/nio/ExtendedFile.html

Details on the various constructors available for the ExtendedFile class.

```APIDOC
## Constructor Details

### ExtendedFile
protected ExtendedFile(@NonNull String pathname)

See Also:
  * `File(String)`

### ExtendedFile
protected ExtendedFile(@Nullable String parent, @NonNull String child)

See Also:
  * `File(String, String)`

### ExtendedFile
protected ExtendedFile(@Nullable File parent, @NonNull String child)

See Also:
  * `File(File, String)`

### ExtendedFile
protected ExtendedFile(@NonNull URI uri)

See Also:
  * `File(URI)`
```

--------------------------------

### Shell.Builder Methods

Source: https://topjohnwu.github.io/libsu/com/topjohnwu/superuser/Shell.Builder.html

This section details the methods available on the Shell.Builder class for configuring Shell instances.

```APIDOC
## create()

### Description
Creates a new instance of Shell.Builder.

### Method
static Shell.Builder

### Returns
A new Shell.Builder instance.
```

```APIDOC
## build()

### Description
Combines all set options to build a new Shell instance.

### Method
abstract Shell

### Returns
A configured Shell instance.
```

```APIDOC
## build(Process process)

### Description
Combines all set options to build a new Shell instance using the provided Process.

### Method
abstract Shell

### Parameters
#### Path Parameters
- **process** (Process) - Required - The process to use for the shell.
```

```APIDOC
## build(String... commands)

### Description
Combines all set options to build a new Shell instance with the provided commands.

### Method
final Shell

### Parameters
#### Path Parameters
- **commands** (String...) - Required - The commands to execute in the shell.
```

```APIDOC
## setCommands(String... commands)

### Description
Sets the commands that will be used to create a new Shell.

### Method
abstract Shell.Builder

### Parameters
#### Path Parameters
- **commands** (String...) - Required - The commands to set for the shell.
```

```APIDOC
## setContext(Context context)

### Description
Sets the Context to use when creating a shell.

### Method
final Shell.Builder

### Parameters
#### Path Parameters
- **context** (Context) - Required - The context to use.
```

```APIDOC
## setFlags(int flags)

### Description
Sets flags to control how a new Shell will be constructed.

### Method
abstract Shell.Builder

### Parameters
#### Path Parameters
- **flags** (int) - Required - The flags to set.
```

```APIDOC
## setInitializers(Class<? extends Shell.Initializer>... classes)

### Description
Sets the desired Shell.Initializer classes.

### Method
final Shell.Builder

### Parameters
#### Path Parameters
- **classes** (Class<? extends Shell.Initializer>...) - Required - The initializer classes to set.
```

```APIDOC
## setTimeout(long timeout)

### Description
Sets the maximum time to wait for shell verification.

### Method
abstract Shell.Builder

### Parameters
#### Path Parameters
- **timeout** (long) - Required - The timeout duration in milliseconds.
```

--------------------------------

### Shell.isAlive()

Source: https://topjohnwu.github.io/libsu/com/topjohnwu/superuser/Shell.html

Checks if the shell process is currently running and responsive.

```APIDOC
## isAlive
public abstract boolean isAlive()

Return whether the shell is still alive. 

Returns:
    `true` if the shell is still alive.
```

--------------------------------

### Shell.cmd(@NonNull String... commands)

Source: https://topjohnwu.github.io/libsu/com/topjohnwu/superuser/Shell.html

Creates a pending Shell.Job with the provided commands. The main shell is not requested until a job execution method is invoked. This allows for job construction before a root shell is available.

```APIDOC
## cmd
@NonNull public static Shell.Job cmd(@NonNull String... commands)

Create a pending `Shell.Job` of the main shell with commands. 
This method can be treated as functionally equivalent to `Shell.getShell().newJob().add(commands).to(new ArrayList<>())`, but the internal implementation is specialized for this use case and does not run this exact code. The developer can manually override output destination(s) with either `Shell.Job.to(List)` or `Shell.Job.to(List, List)`.
The main shell will NOT be requested until the developer invokes either `Shell.Job.exec()`, `Shell.Job.enqueue()`, or `Job.submit(...)`. This makes it possible to construct `Shell.Job`s before the program has created any root shell. 

Returns:
    a job that the developer can execute or submit later.

See Also:
    
      * `Shell.Job.add(String...)`
```

--------------------------------

### SuFileInputStream

Source: https://topjohnwu.github.io/libsu/allclasses-index.html

Open `InputStream`s that read files with root access.

```APIDOC
## Class SuFileInputStream

### Description
Open `InputStream`s that read files with root access.

### Type
Class
```

--------------------------------

### open(File file, boolean append)

Source: https://topjohnwu.github.io/libsu/com/topjohnwu/superuser/io/SuFileOutputStream.html

Opens an OutputStream with root access for the specified File object, with an option to append to the file.

```APIDOC
## open(File file, boolean append)

### Description
Opens an `OutputStream` with root access for the specified `File` object. Unless `file` is an `SuFile`, this method will always try to directly open a `FileOutputStream`, and fallback to using root access when it fails. If `append` is true, data will be written to the end of the file rather than overwriting it.

### Method
`public static OutputStream open(@NonNull File file, boolean append)`

### Parameters
* **file** (File) - Required - The `File` object.
* **append** (boolean) - Required - `true` to append to the file, `false` to overwrite.

### Throws
* `FileNotFoundException` - If the file cannot be opened.

### See Also
* `FileOutputStream(File, boolean)`
```

--------------------------------

### Static open Methods

Source: https://topjohnwu.github.io/libsu/com/topjohnwu/superuser/io/SuFile.html

Static methods to open files using various path specifications, returning an ExtendedFile.

```APIDOC
## Static open Methods

### open(String pathname)
public static ExtendedFile open(String pathname)
Opens a file with the given pathname.

### open(String parent, String child)
public static ExtendedFile open(String parent, String child)
Opens a file with the given parent and child pathnames.

### open(File parent, String child)
public static ExtendedFile open(File parent, String child)
Opens a file with the given parent File object and child pathname string.

### open(URI uri)
public static ExtendedFile open(URI uri)
Opens a file with the given URI.
```

--------------------------------

### Executing Commands

Source: https://topjohnwu.github.io/libsu/com/topjohnwu/superuser/Shell.html

These methods allow you to execute commands in the main shell. You can provide commands as a string array or pipe an InputStream to the shell.

```APIDOC
## cmd(String... commands)

### Description
Creates a pending `Shell.Job` of the main shell with the provided commands.

### Method
`static Shell.Job`

### Parameters
- `commands` (String...) - The commands to execute.
```

```APIDOC
## cmd(InputStream in)

### Description
Creates a pending `Shell.Job` of the main shell with an `InputStream`.

### Method
`static Shell.Job`

### Parameters
- `in` (InputStream) - The input stream to pipe to the shell.
```

--------------------------------

### FileSystemManager

Source: https://topjohnwu.github.io/libsu/allclasses-index.html

Access file system APIs.

```APIDOC
## Class FileSystemManager

### Description
Access file system APIs.

### Type
Class
```

--------------------------------

### Shell.Builder.setCommands

Source: https://topjohnwu.github.io/libsu/com/topjohnwu/superuser/Shell.Builder.html

Sets the commands that will be used to create a new Shell.

```APIDOC
## Method

### setCommands

`@NonNull public abstract Shell.Builder setCommands(String... commands)`

Set the commands that will be used to create a new `Shell`.

Parameters:
    `commands` - commands that will be passed to `Runtime.exec(String[])` to create a new `Process`.

Returns:
    this Builder object for chaining of calls.
```

--------------------------------

### Shell.execTask(@NonNull Shell.Task task)

Source: https://topjohnwu.github.io/libsu/com/topjohnwu/superuser/Shell.html

Executes a low-level Shell.Task directly, exposing STDIN/STDOUT/STDERR. Use with caution, as it requires careful management of buffers and shell state. Recommended for advanced, low-level operations.

```APIDOC
## execTask
public abstract void execTask(@NonNull Shell.Task task) throws IOException

Execute a low-level `Shell.Task` using the shell. USE THIS METHOD WITH CAUTION! 
This method exposes raw STDIN/STDOUT/STDERR directly to the developer. This is meant for implementing low-level operations. The shell may stall if the buffer of STDOUT/STDERR is full. It is recommended to use additional threads to consume STDOUT/STDERR in parallel. 
STDOUT/STDERR is cleared before executing the task. No output from any previous tasks should be left over. It is the developer's responsibility to make sure all operations are done; the shell should be in idle and waiting for further input when the task returns. 

Parameters:
    `task` - the desired task. 

Throws:
    `IOException` - I/O errors when doing operations with STDIN/STDOUT/STDERR
```

--------------------------------

### Shell.Builder

Source: https://topjohnwu.github.io/libsu/index-all.html

Builder class for creating and configuring Shell instances. Allows setting commands, context, flags, initializers, and timeouts.

```APIDOC
## Shell.Builder

### Description
Builder class for `Shell` instances. Allows setting commands, context, flags, initializers, and timeouts.

### Methods
- `setCommands(String...)`: Set the commands that will be used to create a new `Shell`.
- `setContext(Context)`: Set the `Context` to use when creating a shell.
- `setFlags(int)`: Set flags to control how a new `Shell` will be constructed.
- `setInitializers(Class<? extends Shell.Initializer>...)`: Set the desired `Shell.Initializer`s.
- `setTimeout(long)`: Set the maximum time to wait for shell verification.
```

--------------------------------

### Shell.Builder Constructor

Source: https://topjohnwu.github.io/libsu/com/topjohnwu/superuser/Shell.Builder.html

Initializes a new instance of the Shell.Builder class.

```APIDOC
## Constructor

### Builder

`public Builder()`

Initializes a new instance of the `Shell.Builder` class.
```

--------------------------------

### Static Factory Methods

Source: https://topjohnwu.github.io/libsu/com/topjohnwu/superuser/io/SuFile.html

Static methods for creating ExtendedFile instances.

```APIDOC
## Static Factory Methods

### `static ExtendedFile open(File parent, String child)`
Creates an `ExtendedFile` instance from a parent `File` object and a child pathname string.

### `static ExtendedFile open(String pathname)`
Creates an `ExtendedFile` instance from a pathname string.

### `static ExtendedFile open(String parent, String child)`
Creates an `ExtendedFile` instance from a parent pathname string and a child pathname string.

### `static ExtendedFile open(URI uri)`
Creates an `ExtendedFile` instance from a `URI` object.
```

--------------------------------

### Input/Output Streams

Source: https://topjohnwu.github.io/libsu/com/topjohnwu/superuser/io/SuFile.html

Methods for opening input and output streams for files.

```APIDOC
## Input/Output Streams

### `InputStream newInputStream()`
Opens an `InputStream` with the matching file system backend of the file.

### `OutputStream newOutputStream(boolean append)`
Opens an `OutputStream` with the matching file system backend of the file.
```

--------------------------------

### Shell.newJob()

Source: https://topjohnwu.github.io/libsu/com/topjohnwu/superuser/Shell.html

Constructs a new Shell.Job instance. Output is not collected unless explicitly set using `to(List)` or `to(List, List)`. This provides more control over job creation.

```APIDOC
## newJob
@NonNull public abstract Shell.Job newJob()

Construct a new `Shell.Job` that uses the shell for execution. 
Unlike `cmd(String...)` and `cmd(InputStream)`, **NO** output will be collected if the developer did not set the output destination with `Shell.Job.to(List)` or `Shell.Job.to(List, List)`. 

Returns:
    a job that the developer can execute or submit later.
```

--------------------------------

### listFiles()

Source: https://topjohnwu.github.io/libsu/com/topjohnwu/superuser/io/SuFile.html

Returns an array of abstract pathnames denoting the files in the directory denoted by this abstract pathname. Requires the 'ls' command.

```APIDOC
## listFiles()

### Description
Returns an array of abstract pathnames denoting the files in the directory denoted by this abstract pathname.
Requires command `ls`.

### Method
`@Nullable public SuFile[] listFiles()`

### See Also
* `File.listFiles()`
```

--------------------------------

### RootService Bind Methods

Source: https://topjohnwu.github.io/libsu/index-all.html

Methods for binding to a root service. These methods can launch a new root process if one is not already available.

```APIDOC
## bind(Intent, Executor, ServiceConnection)

### Description
Bind to a root service, launching a new root process if needed.

### Method
Static method in class com.topjohnwu.superuser.ipc.RootService

### Parameters
- **intent** (Intent) - Description of the intent to bind.
- **executor** (Executor) - The executor to use for callbacks.
- **connection** (ServiceConnection) - The service connection to establish.

## bind(Intent, ServiceConnection)

### Description
Bind to a root service, launching a new root process if needed.

### Method
Static method in class com.topjohnwu.superuser.ipc.RootService

### Parameters
- **intent** (Intent) - Description of the intent to bind.
- **connection** (ServiceConnection) - The service connection to establish.

## bindOrTask(Intent, Executor, ServiceConnection)

### Description
Bind to a root service, creating a task to launch a new root process if needed.

### Method
Static method in class com.topjohnwu.superuser.ipc.RootService

### Parameters
- **intent** (Intent) - Description of the intent to bind.
- **executor** (Executor) - The executor to use for callbacks.
- **connection** (ServiceConnection) - The service connection to establish.
```

--------------------------------

### Binding to a Root Service

Source: https://topjohnwu.github.io/libsu/com/topjohnwu/superuser/ipc/RootService.html

These methods are used to bind to a RootService. If the service is not already running, a new root process will be launched. The `bind` method with an Executor allows for asynchronous execution of the binding process.

```APIDOC
## bind(Intent intent, Executor executor, ServiceConnection conn)

### Description
Bind to a root service, launching a new root process if needed. This overload allows specifying an Executor for asynchronous binding.

### Method
static void

### Parameters
- **intent** (Intent) - The intent specifying the service to bind to.
- **executor** (Executor) - The executor to use for the binding operation.
- **conn** (ServiceConnection) - The connection to be established with the service.

## bind(Intent intent, ServiceConnection conn)

### Description
Bind to a root service, launching a new root process if needed. This is a simpler overload that uses the default executor.

### Method
static void

### Parameters
- **intent** (Intent) - The intent specifying the service to bind to.
- **conn** (ServiceConnection) - The connection to be established with the service.
```

--------------------------------

### getTotalSpace()

Source: https://topjohnwu.github.io/libsu/com/topjohnwu/superuser/io/SuFile.html

Returns the size of the partition where the file resides. Requires the 'stat' command.

```APIDOC
## getTotalSpace()

### Description
Returns the size of the partition.

### Requires
`stat` command.

### Overrides
`getTotalSpace` in class `File`
```

--------------------------------

### SuFile.getTotalSpace

Source: https://topjohnwu.github.io/libsu/index-all.html

Returns the total size of the partition on which the file resides. This gives the overall capacity of the storage.

```APIDOC
## getTotalSpace()

### Description
Returns the size of the partition.

### Method
Method in class com.topjohnwu.superuser.io.SuFile
```

--------------------------------

### Shell.Builder

Source: https://topjohnwu.github.io/libsu/allclasses-index.html

Builder class for `Shell` instances.

```APIDOC
## Class Shell.Builder

### Description
Builder class for `Shell` instances.

### Type
Class
```

--------------------------------

### Accessing File System Managers

Source: https://topjohnwu.github.io/libsu/com/topjohnwu/superuser/nio/FileSystemManager.html

Provides static methods to obtain FileSystemManager instances for local or remote processes.

```APIDOC
## Accessing File System Managers

### Description
These static methods allow you to get a `FileSystemManager` instance to interact with the file system of the current local process or a remote process.

### Methods

#### `static FileSystemManager getLocal()`
Get the `FileSystemManager` to access the file system of the current local process.

#### `static FileSystemManager getRemote(IBinder binder)`
Create a `FileSystemManager` to access the file system of a remote process.

#### `static Binder getService()`
Get the service that exports the file system of the current process over Binder IPC.
```

--------------------------------

### Open InputStream with Root Access (String Path)

Source: https://topjohnwu.github.io/libsu/com/topjohnwu/superuser/io/SuFileInputStream.html

Opens an InputStream for the specified file path with root access. This method is a convenience wrapper around `SuFileInputStream.open(new File(path))`.

```APIDOC
## open

### Description
Opens an `InputStream` with root access using a file path.

### Method
```java
public static InputStream open(String path)
```

### Parameters
* **path** (String) - Required - The path to the file.

### Throws
* `FileNotFoundException` - If the file cannot be opened.

### See Also
* `FileInputStream(File)`
```

--------------------------------

### SuFileOutputStream

Source: https://topjohnwu.github.io/libsu/allclasses-index.html

Open `OutputStream`s that read files with root access.

```APIDOC
## Class SuFileOutputStream

### Description
Open `OutputStream`s that read files with root access.

### Type
Class
```

--------------------------------

### File System Operations

Source: https://topjohnwu.github.io/libsu/com/topjohnwu/superuser/nio/ExtendedFile.html

Methods for creating links, checking file types, and listing directory contents.

```APIDOC
## createNewLink

### Description
Creates a new hard link named by this abstract pathname of an existing file if and only if a file with this name does not yet exist.

### Method
abstract boolean

### Endpoint
createNewLink(String existing)

## createNewSymlink

### Description
Creates a new symbolic link named by this abstract pathname to a target file if and only if a file with this name does not yet exist.

### Method
abstract boolean

### Endpoint
createNewSymlink(String target)

## getAbsoluteFile

### Description
Returns the absolute canonical form of this abstract pathname.

### Method
abstract ExtendedFile

### Endpoint
getAbsoluteFile()

## getCanonicalFile

### Description
Returns the canonical form of this abstract pathname.

### Method
abstract ExtendedFile

### Endpoint
getCanonicalFile()

## getChildFile

### Description
Create a child relative to the abstract pathname using the same file system backend.

### Method
abstract ExtendedFile

### Endpoint
getChildFile(String child)

## getParentFile

### Description
Returns the an abstract pathname denoting the parent of the file denoted by this abstract pathname.

### Method
abstract ExtendedFile

### Endpoint
getParentFile()

## isBlock

### Description
Tests whether or not this abstract pathname denotes a block special file.

### Method
abstract boolean

### Endpoint
isBlock()

## isCharacter

### Description
Tests whether or not this abstract pathname denotes a character special file.

### Method
abstract boolean

### Endpoint
isCharacter()

## isNamedPipe

### Description
Tests whether or not this abstract pathname denotes a named pipe.

### Method
abstract boolean

### Endpoint
isNamedPipe()

## isSocket

### Description
Tests whether or not this abstract pathname denotes a socket.

### Method
abstract boolean

### Endpoint
isSocket()

## isSymlink

### Description
Tests whether or not this abstract pathname denotes a symbolic link.

### Method
abstract boolean

### Endpoint
isSymlink()

## listFiles

### Description
Returns an array of abstract pathnames that are contained in the directory denoted by this abstract pathname.

### Method
abstract ExtendedFile[]

### Endpoint
listFiles()

## listFiles with filter

### Description
Returns an array of abstract pathnames that are contained in the directory denoted by this abstract pathname, filtering by a `FileFilter`.

### Method
abstract ExtendedFile[]

### Endpoint
listFiles(FileFilter filter)

## listFiles with filename filter

### Description
Returns an array of abstract pathnames that are contained in the directory denoted by this abstract pathname, filtering by a `FilenameFilter`.

### Method
abstract ExtendedFile[]

### Endpoint
listFiles(FilenameFilter filter)

```

--------------------------------

### Shell Operations

Source: https://topjohnwu.github.io/libsu/com/topjohnwu/superuser/io/SuFile.html

Methods for setting and retrieving the Shell instance.

```APIDOC
## Shell Operations

### `void setShell(Shell shell)`
Sets the `Shell` instance to be used internally for all operations.

### `Shell getShell()`
Returns the `Shell` instance used for operations.
```

--------------------------------

### open(String path)

Source: https://topjohnwu.github.io/libsu/com/topjohnwu/superuser/io/SuFileOutputStream.html

Opens an OutputStream with root access for the specified file path. This method defaults to not appending to the file.

```APIDOC
## open(String path)

### Description
Opens an `OutputStream` with root access for the specified file path. This is a convenience method that calls `SuFileOutputStream.open(new File(path), false)`.

### Method
`public static OutputStream open(@NonNull String path)`

### Parameters
* **path** (String) - Required - The path to the file.

### Throws
* `FileNotFoundException` - If the file cannot be opened.

### See Also
* `FileOutputStream(File, boolean)`
```