Skip to content

Most visited

Recently visited

navigation
Added in API level 1

File

public class File
extends Object implements Serializable, Comparable<File>

java.lang.Object
   ↳ java.io.File


An "abstract" representation of a file system entity identified by a pathname. The pathname may be absolute (relative to the root directory of the file system) or relative to the current directory in which the program is running.

The actual file referenced by a File may or may not exist. It may also, despite the name File, be a directory or other non-regular file.

This class provides limited functionality for getting/setting file permissions, file type, and last modified time.

On Android strings are converted to UTF-8 byte sequences when sending filenames to the operating system, and byte sequences returned by the operating system (from the various list methods) are converted to strings by decoding them as UTF-8 byte sequences.

See also:

Summary

Fields

public static final String pathSeparator

The system-dependent string used to separate components in search paths (":").

public static final char pathSeparatorChar

The system-dependent character used to separate components in search paths (':').

public static final String separator

The system-dependent string used to separate components in filenames ('/').

public static final char separatorChar

The system-dependent character used to separate components in filenames ('/').

Public constructors

File(File dir, String name)

Constructs a new file using the specified directory and name.

File(String path)

Constructs a new file using the specified path.

File(String dirPath, String name)

Constructs a new File using the specified directory path and file name, placing a path separator between the two.

File(URI uri)

Constructs a new File using the path of the specified URI.

Public methods

boolean canExecute()

Tests whether or not this process is allowed to execute this file.

boolean canRead()

Indicates whether the current context is allowed to read from this file.

boolean canWrite()

Indicates whether the current context is allowed to write to this file.

int compareTo(File another)

Returns the relative sort ordering of the paths for this file and the file another.

boolean createNewFile()

Creates a new, empty file on the file system according to the path information stored in this file.

static File createTempFile(String prefix, String suffix, File directory)

Creates an empty temporary file in the given directory using the given prefix and suffix as part of the file name.

static File createTempFile(String prefix, String suffix)

Creates an empty temporary file using the given prefix and suffix as part of the file name.

boolean delete()

Deletes this file.

void deleteOnExit()

Schedules this file to be automatically deleted when the VM terminates normally.

boolean equals(Object obj)

Compares obj to this file and returns true if they represent the same object using a path specific comparison.

boolean exists()

Returns a boolean indicating whether this file can be found on the underlying file system.

File getAbsoluteFile()

Returns a new file constructed using the absolute path of this file.

String getAbsolutePath()

Returns the absolute path of this file.

File getCanonicalFile()

Returns a new file created using the canonical path of this file.

String getCanonicalPath()

Returns the canonical path of this file.

long getFreeSpace()

Returns the number of free bytes on the partition containing this path.

String getName()

Returns the name of the file or directory represented by this file.

String getParent()

Returns the pathname of the parent of this file.

File getParentFile()

Returns a new file made from the pathname of the parent of this file.

String getPath()

Returns the path of this file.

long getTotalSpace()

Returns the total size in bytes of the partition containing this path.

long getUsableSpace()

Returns the number of usable free bytes on the partition containing this path.

int hashCode()

Returns an integer hash code for the receiver.

boolean isAbsolute()

Indicates if this file's pathname is absolute.

boolean isDirectory()

Indicates if this file represents a directory on the underlying file system.

boolean isFile()

Indicates if this file represents a file on the underlying file system.

boolean isHidden()

Returns whether or not this file is a hidden file as defined by the operating system.

long lastModified()

Returns the time when this file was last modified, measured in milliseconds since January 1st, 1970, midnight.

long length()

Returns the length of this file in bytes.

String[] list()

Returns an array of strings with the file names in the directory represented by this file.

String[] list(FilenameFilter filter)

Gets a list of the files in the directory represented by this file.

File[] listFiles()

Returns an array of files contained in the directory represented by this file.

File[] listFiles(FilenameFilter filter)

Gets a list of the files in the directory represented by this file.

File[] listFiles(FileFilter filter)

Gets a list of the files in the directory represented by this file.

static File[] listRoots()

Returns the file system roots.

boolean mkdir()

Creates the directory named by this file, assuming its parents exist.

boolean mkdirs()

Creates the directory named by this file, creating missing parent directories if necessary.

boolean renameTo(File newPath)

Renames this file to newPath.

boolean setExecutable(boolean executable)

Equivalent to setExecutable(executable, true).

boolean setExecutable(boolean executable, boolean ownerOnly)

Manipulates the execute permissions for the abstract path designated by this file.

boolean setLastModified(long time)

Sets the time this file was last modified, measured in milliseconds since January 1st, 1970, midnight.

boolean setReadOnly()

Equivalent to setWritable(false, false).

boolean setReadable(boolean readable)

Equivalent to setReadable(readable, true).

boolean setReadable(boolean readable, boolean ownerOnly)

Manipulates the read permissions for the abstract path designated by this file.

boolean setWritable(boolean writable, boolean ownerOnly)

Manipulates the write permissions for the abstract path designated by this file.

boolean setWritable(boolean writable)

Equivalent to setWritable(writable, true).

String toString()

Returns a string containing a concise, human-readable description of this file.

URI toURI()

Returns a Uniform Resource Identifier for this file.

URL toURL()

This method was deprecated in API level 9. Use toURI() and toURL() to correctly escape illegal characters.

Inherited methods

From class java.lang.Object
From interface java.lang.Comparable

Fields

pathSeparator

Added in API level 1
String pathSeparator

The system-dependent string used to separate components in search paths (":"). See pathSeparatorChar.

pathSeparatorChar

Added in API level 1
char pathSeparatorChar

The system-dependent character used to separate components in search paths (':'). This is used to split such things as the PATH environment variable and classpath system properties into lists of directories to be searched.

This field is initialized from the system property "path.separator". Later changes to that property will have no effect on this field or this class.

separator

Added in API level 1
String separator

The system-dependent string used to separate components in filenames ('/'). See separatorChar.

separatorChar

Added in API level 1
char separatorChar

The system-dependent character used to separate components in filenames ('/'). Use of this (rather than hard-coding '/') helps portability to other operating systems.

This field is initialized from the system property "file.separator". Later changes to that property will have no effect on this field or this class.

Public constructors

File

Added in API level 1
File (File dir, 
                String name)

Constructs a new file using the specified directory and name.

Parameters
dir File: the directory where the file is stored.
name String: the file's name.
Throws
NullPointerException if name is null.

File

Added in API level 1
File (String path)

Constructs a new file using the specified path.

Parameters
path String: the path to be used for the file.
Throws
NullPointerException if path is null.

File

Added in API level 1
File (String dirPath, 
                String name)

Constructs a new File using the specified directory path and file name, placing a path separator between the two.

Parameters
dirPath String: the path to the directory where the file is stored.
name String: the file's name.
Throws
NullPointerException if name == null.

File

Added in API level 1
File (URI uri)

Constructs a new File using the path of the specified URI. uri needs to be an absolute and hierarchical Unified Resource Identifier with file scheme and non-empty path component, but with undefined authority, query or fragment components.

Parameters
uri URI: the Unified Resource Identifier that is used to construct this file.
Throws
NullPointerException if uri == null.
IllegalArgumentException if uri does not comply with the conditions above.

See also:

Public methods

canExecute

Added in API level 9
boolean canExecute ()

Tests whether or not this process is allowed to execute this file. Note that this is a best-effort result; the only way to be certain is to actually attempt the operation.

Returns
boolean true if this file can be executed, false otherwise.

canRead

Added in API level 1
boolean canRead ()

Indicates whether the current context is allowed to read from this file.

Returns
boolean true if this file can be read, false otherwise.

canWrite

Added in API level 1
boolean canWrite ()

Indicates whether the current context is allowed to write to this file.

Returns
boolean true if this file can be written, false otherwise.

compareTo

Added in API level 1
int compareTo (File another)

Returns the relative sort ordering of the paths for this file and the file another. The ordering is platform dependent.

Parameters
another File: a file to compare this file to
Returns
int an int determined by comparing the two paths. Possible values are described in the Comparable interface.

See also:

createNewFile

Added in API level 1
boolean createNewFile ()

Creates a new, empty file on the file system according to the path information stored in this file. This method returns true if it creates a file, false if the file already existed. Note that it returns false even if the file is not a file (because it's a directory, say).

This method is not generally useful. For creating temporary files, use createTempFile(String, String) instead. For reading/writing files, use FileInputStream, FileOutputStream, or RandomAccessFile, all of which can create files.

Note that this method does not throw IOException if the file already exists, even if it's not a regular file. Callers should always check the return value, and may additionally want to call isFile().

Returns
boolean true if the file has been created, false if it already exists.
Throws
IOException if it's not possible to create the file.

createTempFile

Added in API level 1
File createTempFile (String prefix, 
                String suffix, 
                File directory)

Creates an empty temporary file in the given directory using the given prefix and suffix as part of the file name. If suffix is null, .tmp is used.

Note that this method does not call deleteOnExit(), but see the documentation for that method before you call it manually.

Parameters
prefix String: the prefix to the temp file name.
suffix String: the suffix to the temp file name.
directory File: the location to which the temp file is to be written, or null for the default location for temporary files, which is taken from the "java.io.tmpdir" system property. It may be necessary to set this property to an existing, writable directory for this method to work properly.
Returns
File the temporary file.
Throws
IllegalArgumentException if the length of prefix is less than 3.
IOException if an error occurs when writing the file.

createTempFile

Added in API level 1
File createTempFile (String prefix, 
                String suffix)

Creates an empty temporary file using the given prefix and suffix as part of the file name. If suffix is null, .tmp is used. This method is a convenience method that calls createTempFile(String, String, File) with the third argument being null.

Parameters
prefix String: the prefix to the temp file name.
suffix String: the suffix to the temp file name.
Returns
File the temporary file.
Throws
IOException if an error occurs when writing the file.

delete

Added in API level 1
boolean delete ()

Deletes this file. Directories must be empty before they will be deleted.

Note that this method does not throw IOException on failure. Callers must check the return value.

Returns
boolean true if this file was deleted, false otherwise.

deleteOnExit

Added in API level 1
void deleteOnExit ()

Schedules this file to be automatically deleted when the VM terminates normally.

Note that on Android, the application lifecycle does not include VM termination, so calling this method will not ensure that files are deleted. Instead, you should use the most appropriate out of:

  • Use a finally clause to manually invoke delete().
  • Maintain your own set of files to delete, and process it at an appropriate point in your application's lifecycle.
  • Use the Unix trick of deleting the file as soon as all readers and writers have opened it. No new readers/writers will be able to access the file, but all existing ones will still have access until the last one closes the file.

equals

Added in API level 1
boolean equals (Object obj)

Compares obj to this file and returns true if they represent the same object using a path specific comparison.

Parameters
obj Object: the object to compare this file with.
Returns
boolean true if obj is the same as this object, false otherwise.

exists

Added in API level 1
boolean exists ()

Returns a boolean indicating whether this file can be found on the underlying file system.

Returns
boolean true if this file exists, false otherwise.

getAbsoluteFile

Added in API level 1
File getAbsoluteFile ()

Returns a new file constructed using the absolute path of this file. Equivalent to new File(this.getAbsolutePath()).

Returns
File

getAbsolutePath

Added in API level 1
String getAbsolutePath ()

Returns the absolute path of this file. An absolute path is a path that starts at a root of the file system. On Android, there is only one root: /.

A common use for absolute paths is when passing paths to a Process as command-line arguments, to remove the requirement implied by relative paths, that the child must have the same working directory as its parent.

Returns
String

getCanonicalFile

Added in API level 1
File getCanonicalFile ()

Returns a new file created using the canonical path of this file. Equivalent to new File(this.getCanonicalPath()).

Returns
File the new file constructed from this file's canonical path.
Throws
IOException if an I/O error occurs.

getCanonicalPath

Added in API level 1
String getCanonicalPath ()

Returns the canonical path of this file. An absolute path is one that begins at the root of the file system. A canonical path is an absolute path with symbolic links and references to "." or ".." resolved. If a path element does not exist (or is not searchable), there is a conflict between interpreting canonicalization as a textual operation (where "a/../b" is "b" even if "a" does not exist) .

Most callers should use getAbsolutePath() instead. A canonical path is significantly more expensive to compute, and not generally useful. The primary use for canonical paths is determining whether two paths point to the same file by comparing the canonicalized paths.

It can be actively harmful to use a canonical path, specifically because canonicalization removes symbolic links. It's wise to assume that a symbolic link is present for a reason, and that that reason is because the link may need to change. Canonicalization removes this layer of indirection. Good code should generally avoid caching canonical paths.

Returns
String the canonical path of this file.
Throws
IOException if an I/O error occurs.

getFreeSpace

Added in API level 9
long getFreeSpace ()

Returns the number of free bytes on the partition containing this path. Returns 0 if this path does not exist.

Note that this is likely to be an optimistic over-estimate and should not be taken as a guarantee your application can actually write this many bytes.

Returns
long

getName

Added in API level 1
String getName ()

Returns the name of the file or directory represented by this file.

Returns
String this file's name or an empty string if there is no name part in the file's path.

getParent

Added in API level 1
String getParent ()

Returns the pathname of the parent of this file. This is the path up to but not including the last name. null is returned if there is no parent.

Returns
String this file's parent pathname or null.

getParentFile

Added in API level 1
File getParentFile ()

Returns a new file made from the pathname of the parent of this file. This is the path up to but not including the last name. null is returned when there is no parent.

Returns
File a new file representing this file's parent or null.

getPath

Added in API level 1
String getPath ()

Returns the path of this file.

Returns
String

getTotalSpace

Added in API level 9
long getTotalSpace ()

Returns the total size in bytes of the partition containing this path. Returns 0 if this path does not exist.

Returns
long

getUsableSpace

Added in API level 9
long getUsableSpace ()

Returns the number of usable free bytes on the partition containing this path. Returns 0 if this path does not exist.

Note that this is likely to be an optimistic over-estimate and should not be taken as a guarantee your application can actually write this many bytes. On Android (and other Unix-based systems), this method returns the number of free bytes available to non-root users, regardless of whether you're actually running as root, and regardless of any quota or other restrictions that might apply to the user. (The getFreeSpace method returns the number of bytes potentially available to root.)

Returns
long

hashCode

Added in API level 1
int hashCode ()

Returns an integer hash code for the receiver. Any two objects for which equals returns true must return the same hash code.

Returns
int this files's hash value.

See also:

isAbsolute

Added in API level 1
boolean isAbsolute ()

Indicates if this file's pathname is absolute. Whether a pathname is absolute is platform specific. On Android, absolute paths start with the character '/'.

Returns
boolean true if this file's pathname is absolute, false otherwise.

See also:

isDirectory

Added in API level 1
boolean isDirectory ()

Indicates if this file represents a directory on the underlying file system.

Returns
boolean true if this file is a directory, false otherwise.

isFile

Added in API level 1
boolean isFile ()

Indicates if this file represents a file on the underlying file system.

Returns
boolean true if this file is a file, false otherwise.

isHidden

Added in API level 1
boolean isHidden ()

Returns whether or not this file is a hidden file as defined by the operating system. The notion of "hidden" is system-dependent. For Unix systems a file is considered hidden if its name starts with a ".". For Windows systems there is an explicit flag in the file system for this purpose.

Returns
boolean true if the file is hidden, false otherwise.

lastModified

Added in API level 1
long lastModified ()

Returns the time when this file was last modified, measured in milliseconds since January 1st, 1970, midnight. Returns 0 if the file does not exist.

Returns
long the time when this file was last modified.

length

Added in API level 1
long length ()

Returns the length of this file in bytes. Returns 0 if the file does not exist. The result for a directory is not defined.

Returns
long the number of bytes in this file.

list

Added in API level 1
String[] list ()

Returns an array of strings with the file names in the directory represented by this file. The result is null if this file is not a directory.

The entries . and .. representing the current and parent directory are not returned as part of the list.

Returns
String[] an array of strings with file names or null.

list

Added in API level 1
String[] list (FilenameFilter filter)

Gets a list of the files in the directory represented by this file. This list is then filtered through a FilenameFilter and the names of files with matching names are returned as an array of strings. Returns null if this file is not a directory. If filter is null then all filenames match.

The entries . and .. representing the current and parent directories are not returned as part of the list.

Parameters
filter FilenameFilter: the filter to match names against, may be null.
Returns
String[] an array of files or null.

listFiles

Added in API level 1
File[] listFiles ()

Returns an array of files contained in the directory represented by this file. The result is null if this file is not a directory. The paths of the files in the array are absolute if the path of this file is absolute, they are relative otherwise.

Returns
File[] an array of files or null.

listFiles

Added in API level 1
File[] listFiles (FilenameFilter filter)

Gets a list of the files in the directory represented by this file. This list is then filtered through a FilenameFilter and files with matching names are returned as an array of files. Returns null if this file is not a directory. If filter is null then all filenames match.

The entries . and .. representing the current and parent directories are not returned as part of the list.

Parameters
filter FilenameFilter: the filter to match names against, may be null.
Returns
File[] an array of files or null.

listFiles

Added in API level 1
File[] listFiles (FileFilter filter)

Gets a list of the files in the directory represented by this file. This list is then filtered through a FileFilter and matching files are returned as an array of files. Returns null if this file is not a directory. If filter is null then all files match.

The entries . and .. representing the current and parent directories are not returned as part of the list.

Parameters
filter FileFilter: the filter to match names against, may be null.
Returns
File[] an array of files or null.

listRoots

Added in API level 1
File[] listRoots ()

Returns the file system roots. On Android and other Unix systems, there is a single root, /.

Returns
File[]

mkdir

Added in API level 1
boolean mkdir ()

Creates the directory named by this file, assuming its parents exist. Use mkdirs() if you also want to create missing parents.

Note that this method does not throw IOException on failure. Callers must check the return value. Note also that this method returns false if the directory already existed. If you want to know whether the directory exists on return, either use (f.mkdir() || f.isDirectory()) or simply ignore the return value from this method and simply call isDirectory().

Returns
boolean true if the directory was created, false on failure or if the directory already existed.

mkdirs

Added in API level 1
boolean mkdirs ()

Creates the directory named by this file, creating missing parent directories if necessary. Use mkdir() if you don't want to create missing parents.

Note that this method does not throw IOException on failure. Callers must check the return value. Note also that this method returns false if the directory already existed. If you want to know whether the directory exists on return, either use (f.mkdirs() || f.isDirectory()) or simply ignore the return value from this method and simply call isDirectory().

Returns
boolean true if the directory was created, false on failure or if the directory already existed.

renameTo

Added in API level 1
boolean renameTo (File newPath)

Renames this file to newPath. This operation is supported for both files and directories.

Many failures are possible. Some of the more likely failures include:

  • Write permission is required on the directories containing both the source and destination paths.
  • Search permission is required for all parents of both paths.
  • Both paths be on the same mount point. On Android, applications are most likely to hit this restriction when attempting to copy between internal storage and an SD card.

Note that this method does not throw IOException on failure. Callers must check the return value.

Parameters
newPath File: the new path.
Returns
boolean true on success.

setExecutable

Added in API level 9
boolean setExecutable (boolean executable)

Equivalent to setExecutable(executable, true).

Parameters
executable boolean
Returns
boolean

See also:

setExecutable

Added in API level 9
boolean setExecutable (boolean executable, 
                boolean ownerOnly)

Manipulates the execute permissions for the abstract path designated by this file.

Note that this method does not throw IOException on failure. Callers must check the return value.

Parameters
executable boolean: To allow execute permission if true, otherwise disallow
ownerOnly boolean: To manipulate execute permission only for owner if true, otherwise for everyone. The manipulation will apply to everyone regardless of this value if the underlying system does not distinguish owner and other users.
Returns
boolean true if and only if the operation succeeded. If the user does not have permission to change the access permissions of this abstract pathname the operation will fail. If the underlying file system does not support execute permission and the value of executable is false, this operation will fail.

setLastModified

Added in API level 1
boolean setLastModified (long time)

Sets the time this file was last modified, measured in milliseconds since January 1st, 1970, midnight.

Note that this method does not throw IOException on failure. Callers must check the return value.

Parameters
time long: the last modification time for this file.
Returns
boolean true if the operation is successful, false otherwise.
Throws
IllegalArgumentException if time < 0.

setReadOnly

Added in API level 1
boolean setReadOnly ()

Equivalent to setWritable(false, false).

Returns
boolean

See also:

setReadable

Added in API level 9
boolean setReadable (boolean readable)

Equivalent to setReadable(readable, true).

Parameters
readable boolean
Returns
boolean

See also:

setReadable

Added in API level 9
boolean setReadable (boolean readable, 
                boolean ownerOnly)

Manipulates the read permissions for the abstract path designated by this file.

Parameters
readable boolean: To allow read permission if true, otherwise disallow
ownerOnly boolean: To manipulate read permission only for owner if true, otherwise for everyone. The manipulation will apply to everyone regardless of this value if the underlying system does not distinguish owner and other users.
Returns
boolean true if and only if the operation succeeded. If the user does not have permission to change the access permissions of this abstract pathname the operation will fail. If the underlying file system does not support read permission and the value of readable is false, this operation will fail.

setWritable

Added in API level 9
boolean setWritable (boolean writable, 
                boolean ownerOnly)

Manipulates the write permissions for the abstract path designated by this file.

Parameters
writable boolean: To allow write permission if true, otherwise disallow
ownerOnly boolean: To manipulate write permission only for owner if true, otherwise for everyone. The manipulation will apply to everyone regardless of this value if the underlying system does not distinguish owner and other users.
Returns
boolean true if and only if the operation succeeded. If the user does not have permission to change the access permissions of this abstract pathname the operation will fail.

setWritable

Added in API level 9
boolean setWritable (boolean writable)

Equivalent to setWritable(writable, true).

Parameters
writable boolean
Returns
boolean

See also:

toString

Added in API level 1
String toString ()

Returns a string containing a concise, human-readable description of this file.

Returns
String a printable representation of this file.

toURI

Added in API level 1
URI toURI ()

Returns a Uniform Resource Identifier for this file. The URI is system dependent and may not be transferable between different operating / file systems.

Returns
URI an URI for this file.

toURL

Added in API level 1
URL toURL ()

This method was deprecated in API level 9.
Use toURI() and toURL() to correctly escape illegal characters.

Returns a Uniform Resource Locator for this file. The URL is system dependent and may not be transferable between different operating / file systems.

Returns
URL a URL for this file.
Throws
MalformedURLException if the path cannot be transformed into a URL.
This site uses cookies to store your preferences for site-specific language and display options.

Hooray!

This class requires API level or higher

This doc is hidden because your selected API level for the documentation is . You can change the documentation API level with the selector above the left navigation.

For more information about specifying the API level your app requires, read Supporting Different Platform Versions.