Added in API level 1

ParcelFileDescriptor

---

Kotlin |Java

open class ParcelFileDescriptor : Parcelable, Closeable

kotlin.Any
↳	android.os.ParcelFileDescriptor

The FileDescriptor returned by Parcel#readFileDescriptor, allowing you to close it when done with it.

Summary

Nested classes
open	AutoCloseInputStream An InputStream you can create on a ParcelFileDescriptor, which will take care of calling android.
open	AutoCloseOutputStream An OutputStream you can create on a ParcelFileDescriptor, which will take care of calling android.
open	FileDescriptorDetachedException Exception that indicates that the file descriptor was detached.
abstract	OnCloseListener Callback indicating that a ParcelFileDescriptor has been closed.

Constants
static Int	MODE_APPEND For use with #open: append to end of file while writing.
static Int	MODE_CREATE For use with #open: create the file if it doesn't already exist.
static Int	MODE_READ_ONLY For use with #open: open the file with read-only access.
static Int	MODE_READ_WRITE For use with #open: open the file with read and write access.
static Int	MODE_TRUNCATE For use with #open: erase contents of file when opening.
static Int	MODE_WORLD_READABLE For use with #open: if MODE_CREATE has been supplied and this file doesn't already exist, then create the file with permissions such that any application can read it.
static Int	MODE_WORLD_WRITEABLE For use with #open: if MODE_CREATE has been supplied and this file doesn't already exist, then create the file with permissions such that any application can write it.
static Int	MODE_WRITE_ONLY For use with #open: open the file with write-only access.

Inherited constants

From class Parcelable Int CONTENTS_FILE_DESCRIPTOR Descriptor bit used with describeContents(): indicates that the Parcelable object's flattened representation includes a file descriptor. Int PARCELABLE_WRITE_RETURN_VALUE Flag for use with writeToParcel: the object being written is a return value, that is the result of a function such as "Parcelable someFunction()", "void someFunction(out Parcelable)", or "void someFunction(inout Parcelable)". Some implementations may want to release resources at this point.

Public constructors
ParcelFileDescriptor(wrapped: ParcelFileDescriptor!) Create a new ParcelFileDescriptor wrapped around another descriptor.

Public methods
open static ParcelFileDescriptor!	adoptFd(fd: Int) Take ownership of a raw native fd in to a new ParcelFileDescriptor.
open Boolean	canDetectErrors() Indicates if this ParcelFileDescriptor can communicate and detect remote errors/crashes.
open Unit	checkError() Detect and throw if the other end of a pipe or socket pair encountered an error or crashed.
open Unit	close() Close the ParcelFileDescriptor.
open Unit	closeWithError(msg: String!) Close the ParcelFileDescriptor, informing any peer that an error occurred while processing.
open static Array<ParcelFileDescriptor!>!	createPipe() Create two ParcelFileDescriptors structured as a data pipe.
open static Array<ParcelFileDescriptor!>!	createReliablePipe() Create two ParcelFileDescriptors structured as a data pipe.
open static Array<ParcelFileDescriptor!>!	createReliableSocketPair() Create two ParcelFileDescriptors structured as a pair of sockets connected to each other.
open static Array<ParcelFileDescriptor!>!	createSocketPair() Create two ParcelFileDescriptors structured as a pair of sockets connected to each other.
open Int	describeContents()
open Int	detachFd() Return the native fd int for this ParcelFileDescriptor and detach it from the object here.
open ParcelFileDescriptor!	dup() Create a new ParcelFileDescriptor that is a dup of the existing FileDescriptor.
open static ParcelFileDescriptor!	dup(orig: FileDescriptor!) Create a new ParcelFileDescriptor that is a dup of an existing FileDescriptor.
open static ParcelFileDescriptor!	fromDatagramSocket(datagramSocket: DatagramSocket!) Create a new ParcelFileDescriptor from the specified DatagramSocket.
open static ParcelFileDescriptor!	fromFd(fd: Int) Create a new ParcelFileDescriptor from a raw native fd.
open static ParcelFileDescriptor!	fromSocket(socket: Socket!) Create a new ParcelFileDescriptor from the specified Socket.
open Int	getFd() Return the native fd int for this ParcelFileDescriptor.
open FileDescriptor!	getFileDescriptor() Retrieve the actual FileDescriptor associated with this object.
open Long	getStatSize() Return the total size of the file representing this fd, as determined by stat().
open static ParcelFileDescriptor!	open(file: File!, mode: Int) Create a new ParcelFileDescriptor accessing a given file.
open static ParcelFileDescriptor!	open(file: File!, mode: Int, handler: Handler!, listener: ParcelFileDescriptor.OnCloseListener!) Create a new ParcelFileDescriptor accessing a given file.
open static Int	parseMode(mode: String!) Converts a string representing a file mode, such as "rw", into a bitmask suitable for use with #open.
open String	toString()
open static ParcelFileDescriptor	wrap(pfd: ParcelFileDescriptor, handler: Handler, listener: ParcelFileDescriptor.OnCloseListener) Create a new ParcelFileDescriptor wrapping an already-opened file.
open Unit	writeToParcel(out: Parcel, flags: Int) Flatten this object in to a Parcel.

Protected methods
open Unit	finalize()

Properties
static Parcelable.Creator<ParcelFileDescriptor!>	CREATOR

Constants

MODE_APPEND

Added in API level 3

static val MODE_APPEND: Int

For use with #open: append to end of file while writing.

Value: 33554432

MODE_CREATE

Added in API level 1

static val MODE_CREATE: Int

For use with #open: create the file if it doesn't already exist.

Value: 134217728

MODE_READ_ONLY

Added in API level 1

static val MODE_READ_ONLY: Int

For use with #open: open the file with read-only access.

Value: 268435456

MODE_READ_WRITE

Added in API level 1

static val MODE_READ_WRITE: Int

For use with #open: open the file with read and write access.

Value: 805306368

MODE_TRUNCATE

Added in API level 1

static val MODE_TRUNCATE: Int

For use with #open: erase contents of file when opening.

Value: 67108864

MODE_WORLD_READABLE

Added in API level 1
Deprecated in API level 19

static val MODE_WORLD_READABLE: Int

Deprecated: Creating world-readable files is very dangerous, and likely to cause security holes in applications. It is strongly discouraged; instead, applications should use more formal mechanism for interactions such as ContentProvider, BroadcastReceiver, and android.app.Service. There are no guarantees that this access mode will remain on a file, such as when it goes through a backup and restore.

For use with #open: if MODE_CREATE has been supplied and this file doesn't already exist, then create the file with permissions such that any application can read it.

Value: 1

MODE_WORLD_WRITEABLE

Added in API level 1
Deprecated in API level 19

static val MODE_WORLD_WRITEABLE: Int

Deprecated: Creating world-writable files is very dangerous, and likely to cause security holes in applications. It is strongly discouraged; instead, applications should use more formal mechanism for interactions such as ContentProvider, BroadcastReceiver, and android.app.Service. There are no guarantees that this access mode will remain on a file, such as when it goes through a backup and restore.

For use with #open: if MODE_CREATE has been supplied and this file doesn't already exist, then create the file with permissions such that any application can write it.

Value: 2

MODE_WRITE_ONLY

Added in API level 1

static val MODE_WRITE_ONLY: Int

For use with #open: open the file with write-only access.

Value: 536870912

Public constructors

ParcelFileDescriptor

Added in API level 1

ParcelFileDescriptor(wrapped: ParcelFileDescriptor!)

Create a new ParcelFileDescriptor wrapped around another descriptor. By default all method calls are delegated to the wrapped descriptor.

Public methods

adoptFd

Added in API level 13

open static fun adoptFd(fd: Int): ParcelFileDescriptor!

Take ownership of a raw native fd in to a new ParcelFileDescriptor. The returned ParcelFileDescriptor now owns the given fd, and will be responsible for closing it.

WARNING: You must not close the fd yourself after this call, and ownership of the file descriptor must have been released prior to the call to this function.

Parameters
fd	Int: The native fd that the ParcelFileDescriptor should adopt.

Return
ParcelFileDescriptor!	Returns a new ParcelFileDescriptor holding a FileDescriptor for the given fd.

canDetectErrors

Added in API level 19

open fun canDetectErrors(): Boolean

Indicates if this ParcelFileDescriptor can communicate and detect remote errors/crashes.

See Also

• #checkError()

checkError

Added in API level 19

open fun checkError(): Unit

Detect and throw if the other end of a pipe or socket pair encountered an error or crashed. This allows a reader to distinguish between a valid EOF and an error/crash.

If this ParcelFileDescriptor is unable to detect remote errors, it will return silently.

Exceptions
java.io.IOException	for normal errors.
android.os.ParcelFileDescriptor.FileDescriptorDetachedException	if the remote side called detachFd(). Once detached, the remote side is unable to communicate any errors through closeWithError(java.lang.String).

See Also

• #canDetectErrors()

close

Added in API level 1

open fun close(): Unit

Close the ParcelFileDescriptor. This implementation closes the underlying OS resources allocated to represent this stream.

Exceptions
java.lang.Exception	if this resource cannot be closed
java.io.IOException	If an error occurs attempting to close this ParcelFileDescriptor.

closeWithError

Added in API level 19

open fun closeWithError(msg: String!): Unit

Close the ParcelFileDescriptor, informing any peer that an error occurred while processing. If the creator of this descriptor is not observing errors, it will close normally.

Parameters
msg	String!: describing the error; must not be null.

createPipe

Added in API level 9

open static fun createPipe(): Array<ParcelFileDescriptor!>!

Create two ParcelFileDescriptors structured as a data pipe. The first ParcelFileDescriptor in the returned array is the read side; the second is the write side.

createReliablePipe

Added in API level 19

open static fun createReliablePipe(): Array<ParcelFileDescriptor!>!

Create two ParcelFileDescriptors structured as a data pipe. The first ParcelFileDescriptor in the returned array is the read side; the second is the write side.

The write end has the ability to deliver an error message through closeWithError(java.lang.String) which can be handled by the read end calling checkError(), usually after detecting an EOF. This can also be used to detect remote crashes.

createReliableSocketPair

Added in API level 19

open static fun createReliableSocketPair(): Array<ParcelFileDescriptor!>!

Create two ParcelFileDescriptors structured as a pair of sockets connected to each other. The two sockets are indistinguishable.

Both ends have the ability to deliver an error message through closeWithError(java.lang.String) which can be detected by the other end calling checkError(), usually after detecting an EOF. This can also be used to detect remote crashes.

createSocketPair

Added in API level 19

open static fun createSocketPair(): Array<ParcelFileDescriptor!>!

Create two ParcelFileDescriptors structured as a pair of sockets connected to each other. The two sockets are indistinguishable.

describeContents

Added in API level 1

open fun describeContents(): Int

Return
Int	a bitmask indicating the set of special object types marshaled by this Parcelable object instance. Value is either 0 or android.os.Parcelable#CONTENTS_FILE_DESCRIPTOR

detachFd

Added in API level 12

open fun detachFd(): Int

Return the native fd int for this ParcelFileDescriptor and detach it from the object here. You are now responsible for closing the fd in native code.

You should not detach when the original creator of the descriptor is expecting a reliable signal through #close() or closeWithError(java.lang.String).

See Also

• #canDetectErrors()

dup

Added in API level 14

open fun dup(): ParcelFileDescriptor!

Create a new ParcelFileDescriptor that is a dup of the existing FileDescriptor. This obeys standard POSIX semantics, where the new file descriptor shared state such as file position with the original file descriptor.

dup

Added in API level 13

open static fun dup(orig: FileDescriptor!): ParcelFileDescriptor!

Create a new ParcelFileDescriptor that is a dup of an existing FileDescriptor. This obeys standard POSIX semantics, where the new file descriptor shared state such as file position with the original file descriptor.

fromDatagramSocket

Added in API level 14

open static fun fromDatagramSocket(datagramSocket: DatagramSocket!): ParcelFileDescriptor!

Create a new ParcelFileDescriptor from the specified DatagramSocket. The new ParcelFileDescriptor holds a dup of the original FileDescriptor in the DatagramSocket, so you must still close the DatagramSocket as well as the new ParcelFileDescriptor.

WARNING: Prior to API level 29, this function would not actually dup the DatagramSocket's FileDescriptor, and would take a reference to the its internal FileDescriptor instead. If the DatagramSocket gets garbage collected before the ParcelFileDescriptor, this may lead to the ParcelFileDescriptor being unexpectedly closed. To avoid this, the following pattern can be used:

<code>ParcelFileDescriptor pfd = ParcelFileDescriptor.fromDatagramSocket(socket).dup();
  </code>

Parameters
datagramSocket	DatagramSocket!: The DatagramSocket whose FileDescriptor is used to create a new ParcelFileDescriptor.

Return
ParcelFileDescriptor!	A new ParcelFileDescriptor with a duped copy of the FileDescriptor of the specified Socket.

Exceptions
java.io.UncheckedIOException	if dup(java.io.FileDescriptor) throws IOException.

fromFd

Added in API level 13

open static fun fromFd(fd: Int): ParcelFileDescriptor!

Create a new ParcelFileDescriptor from a raw native fd. The new ParcelFileDescriptor holds a dup of the original fd passed in here, so you must still close that fd as well as the new ParcelFileDescriptor.

Parameters
fd	Int: The native fd that the ParcelFileDescriptor should dup.

Return
ParcelFileDescriptor!	Returns a new ParcelFileDescriptor holding a FileDescriptor for a dup of the given fd.

fromSocket

Added in API level 1

open static fun fromSocket(socket: Socket!): ParcelFileDescriptor!

Create a new ParcelFileDescriptor from the specified Socket. The new ParcelFileDescriptor holds a dup of the original FileDescriptor in the Socket, so you must still close the Socket as well as the new ParcelFileDescriptor.

WARNING: Prior to API level 29, this function would not actually dup the Socket's FileDescriptor, and would take a reference to the its internal FileDescriptor instead. If the Socket gets garbage collected before the ParcelFileDescriptor, this may lead to the ParcelFileDescriptor being unexpectedly closed. To avoid this, the following pattern can be used:

<code>ParcelFileDescriptor pfd = ParcelFileDescriptor.fromSocket(socket).dup();
  </code>

Parameters
socket	Socket!: The Socket whose FileDescriptor is used to create a new ParcelFileDescriptor.

Return
ParcelFileDescriptor!	A new ParcelFileDescriptor with a duped copy of the FileDescriptor of the specified Socket.

Exceptions
java.io.UncheckedIOException	if dup(java.io.FileDescriptor) throws IOException.

getFd

Added in API level 12

open fun getFd(): Int

Return the native fd int for this ParcelFileDescriptor. The ParcelFileDescriptor still owns the fd, and it still must be closed through this API.

WARNING: Do not call close on the return value of this function or pass it to a function that assumes ownership of the fd.

getFileDescriptor

Added in API level 1

open fun getFileDescriptor(): FileDescriptor!

Retrieve the actual FileDescriptor associated with this object.

Return
FileDescriptor!	Returns the FileDescriptor associated with this object.

getStatSize

Added in API level 3

open fun getStatSize(): Long

Return the total size of the file representing this fd, as determined by stat(). Returns -1 if the fd is not a file.

open

Added in API level 1

open static fun open(
    file: File!, 
    mode: Int
): ParcelFileDescriptor!

Create a new ParcelFileDescriptor accessing a given file.

This method should only be used for files that you have direct access to; if you'd like to work with files hosted outside your app, use an API like ContentResolver#openFile(Uri, String, CancellationSignal).

Parameters
file	File!: The file to be opened.
mode	Int: The desired access mode, must be one of MODE_READ_ONLY, MODE_WRITE_ONLY, or MODE_READ_WRITE; may also be any combination of MODE_CREATE, MODE_TRUNCATE, MODE_WORLD_READABLE, and MODE_WORLD_WRITEABLE.

Return
ParcelFileDescriptor!	a new ParcelFileDescriptor pointing to the given file.

Exceptions
java.io.FileNotFoundException	if the given file does not exist or can not be opened with the requested mode.

See Also

• #parseMode(String)

open

Added in API level 19

open static fun open(
    file: File!, 
    mode: Int, 
    handler: Handler!, 
    listener: ParcelFileDescriptor.OnCloseListener!
): ParcelFileDescriptor!

Create a new ParcelFileDescriptor accessing a given file.

This method should only be used for files that you have direct access to; if you'd like to work with files hosted outside your app, use an API like ContentResolver#openFile(Uri, String, CancellationSignal).

Parameters
file	File!: The file to be opened.
mode	Int: The desired access mode, must be one of MODE_READ_ONLY, MODE_WRITE_ONLY, or MODE_READ_WRITE; may also be any combination of MODE_CREATE, MODE_TRUNCATE, MODE_WORLD_READABLE, and MODE_WORLD_WRITEABLE.
handler	Handler!: to call listener from; must not be null.
listener	ParcelFileDescriptor.OnCloseListener!: to be invoked when the returned descriptor has been closed; must not be null.

Return
ParcelFileDescriptor!	a new ParcelFileDescriptor pointing to the given file.

Exceptions
java.io.FileNotFoundException	if the given file does not exist or can not be opened with the requested mode.

See Also

• #parseMode(String)

parseMode

Added in API level 19

open static fun parseMode(mode: String!): Int

Converts a string representing a file mode, such as "rw", into a bitmask suitable for use with #open.

The argument must define at least one of the following base access modes:

• "r" indicates the file should be opened in read-only mode, equivalent to OsConstants#O_RDONLY.
• "w" indicates the file should be opened in write-only mode, equivalent to OsConstants#O_WRONLY.
• "rw" indicates the file should be opened in read-write mode, equivalent to OsConstants#O_RDWR.

In addition to a base access mode, the following additional modes may requested:

• "a" indicates the file should be opened in append mode, equivalent to OsConstants#O_APPEND. Before each write, the file offset is positioned at the end of the file.
• "t" indicates the file should be opened in truncate mode, equivalent to OsConstants#O_TRUNC. If the file already exists and is a regular file and is opened for writing, it will be truncated to length 0.

Parameters
mode	String!: The string representation of the file mode. Can be "r", "w", "wt", "wa", "rw" or "rwt".

Return
Int	A bitmask representing the given file mode.

Exceptions
java.lang.IllegalArgumentException	if the given string does not match a known file mode.

toString

Added in API level 1

open fun toString(): String

Return
String	a string representation of the object.

wrap

Added in API level 30

open static fun wrap(
    pfd: ParcelFileDescriptor, 
    handler: Handler, 
    listener: ParcelFileDescriptor.OnCloseListener
): ParcelFileDescriptor

Create a new ParcelFileDescriptor wrapping an already-opened file.

Parameters
pfd	ParcelFileDescriptor: The already-opened file. This value cannot be null.
handler	Handler: to call listener from. This value cannot be null.
listener	ParcelFileDescriptor.OnCloseListener: to be invoked when the returned descriptor has been closed. This value cannot be null.

Return
ParcelFileDescriptor	a new ParcelFileDescriptor pointing to the given file. This value cannot be null.

writeToParcel

Added in API level 1

open fun writeToParcel(
    out: Parcel, 
    flags: Int
): Unit

Flatten this object in to a Parcel. If Parcelable#PARCELABLE_WRITE_RETURN_VALUE is set in flags, the file descriptor will be closed after a copy is written to the Parcel.

Parameters
dest	The Parcel in which the object should be written. This value cannot be null.
flags	Int: Additional flags about how the object should be written. May be 0 or PARCELABLE_WRITE_RETURN_VALUE. Value is either 0 or a combination of android.os.Parcelable#PARCELABLE_WRITE_RETURN_VALUE, and android.os.Parcelable.PARCELABLE_ELIDE_DUPLICATES

Protected methods

finalize

Added in API level 1

protected open fun finalize(): Unit

Exceptions
java.lang.Throwable	the Exception raised by this method

Properties

CREATOR

Added in API level 1

static val CREATOR: Parcelable.Creator<ParcelFileDescriptor!>