Added in API level 1

Summary: Nested Classes | Constants | Inherited Constants | Fields | Ctors | Methods | Protected Methods | Inherited Methods

ParcelFileDescriptor

---

Kotlin |Java

public class ParcelFileDescriptor
extends Object implements Closeable, Parcelable

java.lang.Object
↳	android.os.ParcelFileDescriptor

---

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

Summary

Nested classes
class	ParcelFileDescriptor.AutoCloseInputStream An InputStream you can create on a ParcelFileDescriptor, which will take care of calling ParcelFileDescriptor.close() for you when the stream is closed.
class	ParcelFileDescriptor.AutoCloseOutputStream An OutputStream you can create on a ParcelFileDescriptor, which will take care of calling ParcelFileDescriptor.close() for you when the stream is closed.
class	ParcelFileDescriptor.FileDescriptorDetachedException Exception that indicates that the file descriptor was detached.
interface	ParcelFileDescriptor.OnCloseListener Callback indicating that a ParcelFileDescriptor has been closed.

Constants
int	MODE_APPEND For use with open(File, int): append to end of file while writing.
int	MODE_CREATE For use with open(File, int): create the file if it doesn't already exist.
int	MODE_READ_ONLY For use with open(File, int): open the file with read-only access.
int	MODE_READ_WRITE For use with open(File, int): open the file with read and write access.
int	MODE_TRUNCATE For use with open(File, int): erase contents of file when opening.
int	MODE_WORLD_READABLE This constant was deprecated in API level 19. 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 Service. There are no guarantees that this access mode will remain on a file, such as when it goes through a backup and restore.
int	MODE_WORLD_WRITEABLE This constant was deprecated in API level 19. 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 Service. There are no guarantees that this access mode will remain on a file, such as when it goes through a backup and restore.
int	MODE_WRITE_ONLY For use with open(File, int): open the file with write-only access.

Inherited constants

From interface android.os.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(Parcel, int): 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)".

Fields
public static final Creator<ParcelFileDescriptor>	CREATOR

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

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

Protected methods
void	finalize() Called by the garbage collector on an object when garbage collection determines that there are no more references to the object.

Inherited methods
From class java.lang.Object Object clone() Creates and returns a copy of this object. boolean equals(Object obj) Indicates whether some other object is "equal to" this one. void finalize() Called by the garbage collector on an object when garbage collection determines that there are no more references to the object. final Class<?> getClass() Returns the runtime class of this Object. int hashCode() Returns a hash code value for the object. final void notify() Wakes up a single thread that is waiting on this object's monitor. final void notifyAll() Wakes up all threads that are waiting on this object's monitor. String toString() Returns a string representation of the object. final void wait(long timeoutMillis, int nanos) Causes the current thread to wait until it is awakened, typically by being notified or interrupted, or until a certain amount of real time has elapsed. final void wait(long timeoutMillis) Causes the current thread to wait until it is awakened, typically by being notified or interrupted, or until a certain amount of real time has elapsed. final void wait() Causes the current thread to wait until it is awakened, typically by being notified or interrupted.
From interface java.io.Closeable abstract void close() Closes this stream and releases any system resources associated with it.
From interface android.os.Parcelable abstract int describeContents() Describe the kinds of special objects contained in this Parcelable instance's marshaled representation. abstract void writeToParcel(Parcel dest, int flags) Flatten this object in to a Parcel.
From interface java.lang.AutoCloseable abstract void close() Closes this resource, relinquishing any underlying resources.

Constants

MODE_APPEND

Added in API level 3

public static final int MODE_APPEND

For use with open(File, int): append to end of file while writing.

Constant Value: 33554432 (0x02000000)

MODE_CREATE

Added in API level 1

public static final int MODE_CREATE

For use with open(File, int): create the file if it doesn't already exist.

Constant Value: 134217728 (0x08000000)

MODE_READ_ONLY

Added in API level 1

public static final int MODE_READ_ONLY

For use with open(File, int): open the file with read-only access.

Constant Value: 268435456 (0x10000000)

MODE_READ_WRITE

Added in API level 1

public static final int MODE_READ_WRITE

For use with open(File, int): open the file with read and write access.

Constant Value: 805306368 (0x30000000)

MODE_TRUNCATE

Added in API level 1

public static final int MODE_TRUNCATE

For use with open(File, int): erase contents of file when opening.

Constant Value: 67108864 (0x04000000)

MODE_WORLD_READABLE

Added in API level 1
Deprecated in API level 19

public static final int MODE_WORLD_READABLE

This constant was deprecated in API level 19.
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 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(File, int): 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.

Constant Value: 1 (0x00000001)

MODE_WORLD_WRITEABLE

Added in API level 1
Deprecated in API level 19

public static final int MODE_WORLD_WRITEABLE

This constant was deprecated in API level 19.
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 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(File, int): 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.

Constant Value: 2 (0x00000002)

MODE_WRITE_ONLY

Added in API level 1

public static final int MODE_WRITE_ONLY

For use with open(File, int): open the file with write-only access.

Constant Value: 536870912 (0x20000000)

Fields

CREATOR

Added in API level 1

public static final Creator<ParcelFileDescriptor> CREATOR

Public constructors

ParcelFileDescriptor

Added in API level 1

public ParcelFileDescriptor (ParcelFileDescriptor wrapped)

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

Parameters
wrapped	ParcelFileDescriptor

Public methods

adoptFd

Added in API level 13

public static ParcelFileDescriptor adoptFd (int fd)

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.

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

canDetectErrors

Added in API level 19

public boolean canDetectErrors ()

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

Returns
boolean

See also:

• checkError()

checkError

Added in API level 19

public void checkError ()

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.

Throws
IOException	for normal errors.
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

public void close ()

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

Throws
IOException	If an error occurs attempting to close this ParcelFileDescriptor.

closeWithError

Added in API level 19

public void closeWithError (String msg)

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.

Throws
IOException

createPipe

Added in API level 9

public static ParcelFileDescriptor[] createPipe ()

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.

Returns
ParcelFileDescriptor[]

Throws
IOException

createReliablePipe

Added in API level 19

public static ParcelFileDescriptor[] createReliablePipe ()

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.

Returns
ParcelFileDescriptor[]

Throws
IOException

createReliableSocketPair

Added in API level 19

public static ParcelFileDescriptor[] createReliableSocketPair ()

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.

Returns
ParcelFileDescriptor[]

Throws
IOException

createSocketPair

Added in API level 19

public static ParcelFileDescriptor[] createSocketPair ()

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

Returns
ParcelFileDescriptor[]

Throws
IOException

describeContents

Added in API level 1

public int describeContents ()

Describe the kinds of special objects contained in this Parcelable instance's marshaled representation. For example, if the object will include a file descriptor in the output of writeToParcel(android.os.Parcel, int), the return value of this method must include the CONTENTS_FILE_DESCRIPTOR bit.

Returns
int	a bitmask indicating the set of special object types marshaled by this Parcelable object instance. Value is either 0 or CONTENTS_FILE_DESCRIPTOR

detachFd

Added in API level 12

public int detachFd ()

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

Returns
int

See also:

• canDetectErrors()

dup

Added in API level 13

public static ParcelFileDescriptor dup (FileDescriptor orig)

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.

Parameters
orig	FileDescriptor

Returns
ParcelFileDescriptor

Throws
IOException

dup

Added in API level 14

public ParcelFileDescriptor dup ()

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.

Returns
ParcelFileDescriptor

Throws
IOException

fromDatagramSocket

Added in API level 14

public static ParcelFileDescriptor fromDatagramSocket (DatagramSocket datagramSocket)

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:

ParcelFileDescriptor pfd = ParcelFileDescriptor.fromDatagramSocket(socket).dup();
 

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

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

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

fromFd

Added in API level 13

public static ParcelFileDescriptor fromFd (int fd)

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.

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

Throws
IOException

fromSocket

Added in API level 1

public static ParcelFileDescriptor fromSocket (Socket socket)

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:

ParcelFileDescriptor pfd = ParcelFileDescriptor.fromSocket(socket).dup();
 

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

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

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

getFd

Added in API level 12

public int getFd ()

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.

Returns
int

getFileDescriptor

Added in API level 1

public FileDescriptor getFileDescriptor ()

Retrieve the actual FileDescriptor associated with this object.

Returns
FileDescriptor	Returns the FileDescriptor associated with this object.

getStatSize

Added in API level 3

public long getStatSize ()

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

Returns
long

open

Added in API level 1

public static ParcelFileDescriptor open (File file, 
                int mode)

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.

Returns
ParcelFileDescriptor	a new ParcelFileDescriptor pointing to the given file.

Throws
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

public static ParcelFileDescriptor open (File file, 
                int mode, 
                Handler handler, 
                ParcelFileDescriptor.OnCloseListener listener)

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.

Returns
ParcelFileDescriptor	a new ParcelFileDescriptor pointing to the given file.

Throws
FileNotFoundException	if the given file does not exist or can not be opened with the requested mode.
IOException

See also:

• parseMode(String)

parseMode

Added in API level 19

public static int parseMode (String mode)

Converts a string representing a file mode, such as "rw", into a bitmask suitable for use with open(File, int).

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".

Returns
int	A bitmask representing the given file mode.

Throws
IllegalArgumentException	if the given string does not match a known file mode.

toString

Added in API level 1

public String toString ()

Returns a string representation of the object.

Returns
String	a string representation of the object.

wrap

Added in API level 30

public static ParcelFileDescriptor wrap (ParcelFileDescriptor pfd, 
                Handler handler, 
                ParcelFileDescriptor.OnCloseListener listener)

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.

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

Throws
IOException

writeToParcel

Added in API level 1

public void writeToParcel (Parcel out, 
                int flags)

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
out	Parcel: 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.PARCELABLE_WRITE_RETURN_VALUE. Value is either 0 or a combination of Parcelable.PARCELABLE_WRITE_RETURN_VALUE, and android.os.Parcelable.PARCELABLE_ELIDE_DUPLICATES

Protected methods

finalize

Added in API level 1

protected void finalize ()

Called by the garbage collector on an object when garbage collection determines that there are no more references to the object. A subclass overrides the finalize method to dispose of system resources or to perform other cleanup.

The general contract of finalize is that it is invoked if and when the Java virtual machine has determined that there is no longer any means by which this object can be accessed by any thread that has not yet died, except as a result of an action taken by the finalization of some other object or class which is ready to be finalized. The finalize method may take any action, including making this object available again to other threads; the usual purpose of finalize, however, is to perform cleanup actions before the object is irrevocably discarded. For example, the finalize method for an object that represents an input/output connection might perform explicit I/O transactions to break the connection before the object is permanently discarded.

The finalize method of class Object performs no special action; it simply returns normally. Subclasses of Object may override this definition.

The Java programming language does not guarantee which thread will invoke the finalize method for any given object. It is guaranteed, however, that the thread that invokes finalize will not be holding any user-visible synchronization locks when finalize is invoked. If an uncaught exception is thrown by the finalize method, the exception is ignored and finalization of that object terminates.

After the finalize method has been invoked for an object, no further action is taken until the Java virtual machine has again determined that there is no longer any means by which this object can be accessed by any thread that has not yet died, including possible actions by other objects or classes which are ready to be finalized, at which point the object may be discarded.

The finalize method is never invoked more than once by a Java virtual machine for any given object.

Any exception thrown by the finalize method causes the finalization of this object to be halted, but is otherwise ignored.

Throws
Throwable