okio/okio/FileHandle

FileHandle

abstract class FileHandle(val readWrite: Boolean) : Closeable

An open file for reading and writing; using either streaming and random access.

Use read and write to perform one-off random-access reads and writes. Use source, sink, and appendingSink for streaming reads and writes.

File handles must be closed when they are no longer needed. It is an error to read, write, or create streams after a file handle is closed. The operating system resources held by a file handle will be released once the file handle and all of its streams are closed.

Although this class offers both reading and writing APIs, file handle instances may be read-only or write-only. For example, a handle to a file on a read-only file system will throw an exception if a write is attempted.

File handles may be used by multiple threads concurrently. But the individual sources and sinks produced by a file handle are not safe for concurrent use.

Constructors

FileHandle

constructor(readWrite: Boolean)

Properties

lock

val lock: Lock

readWrite

val readWrite: Boolean

True if this handle supports both reading and writing. If this is false all write operations including write, sink, resize, and flush will all throw IllegalStateException if called.

Functions

appendingSink

fun appendingSink(): Sink

Returns a sink that writes to this starting at the end. The returned sink must be closed when it is no longer needed.

override fun close()

Closes this object and releases the resources it holds. It is an error to use an object after it has been closed. It is safe to close an object more than once.

flush

fun flush()

Pushes all buffered bytes to their final destination.

position

fun position(sink: Sink): Long

Returns the position of sink in the file. The argument sink must be either a sink produced by this file handle, or a BufferedSink that directly wraps such a sink. If the parameter is a BufferedSink, it adjusts for buffered bytes.

fun position(source: Source): Long

Returns the position of source in the file. The argument source must be either a source produced by this file handle, or a BufferedSource that directly wraps such a source. If the parameter is a BufferedSource, it adjusts for buffered bytes.

read

fun read(fileOffset: Long, sink: Buffer, byteCount: Long): Long

Reads at least 1, and up to byteCount bytes from this starting at fileOffset and appends them to sink. Returns the number of bytes read, or -1 if fileOffset equals size.

fun read(fileOffset: Long, array: ByteArray, arrayOffset: Int, byteCount: Int): Int

Reads at least 1, and up to byteCount bytes from this starting at fileOffset and copies them to array at arrayOffset. Returns the number of bytes read, or -1 if fileOffset equals size.

reposition

fun reposition(sink: Sink, position: Long)

Change the position of sink in the file to position. The argument sink must be either a sink produced by this file handle, or a BufferedSink that directly wraps such a sink. If the parameter is a BufferedSink, it emits for buffered bytes.

fun reposition(source: Source, position: Long)

Change the position of source in the file to position. The argument source must be either a source produced by this file handle, or a BufferedSource that directly wraps such a source. If the parameter is a BufferedSource, it will skip or clear buffered bytes.

resize

fun resize(size: Long)

Changes the number of bytes in this file to size. This will remove bytes from the end if the new size is smaller. It will add 0 bytes to the end if it is larger.

sink

fun sink(fileOffset: Long = 0): Sink

Returns a sink that writes to this starting at fileOffset. The returned sink must be closed when it is no longer needed.

size

fun size(): Long

Returns the total number of bytes in the file. This will change if the file size changes.

source

fun source(fileOffset: Long = 0): Source

Returns a source that reads from this starting at fileOffset. The returned source must be closed when it is no longer needed.

write

fun write(fileOffset: Long, source: Buffer, byteCount: Long)

Removes byteCount bytes from source and writes them to this at fileOffset.

fun write(fileOffset: Long, array: ByteArray, arrayOffset: Int, byteCount: Int)

Reads byteCount bytes from array and writes them to this at fileOffset.