# Poco

# class File

Library: Foundation
Package: Filesystem
Header: Poco/File.h

## Description

The File class provides methods for working with a file.

Regarding paths passed to the various methods, note that platform-specific limitations regarding maximum length of the entire path and its components apply.

On Windows, the implementation tries to work around the rather low 260 characters MAX_PATH limit by adding the "\\?\" prefix if a path is absolute and exceeds MAX_PATH characters in length. Note that various limitations regarding usage of the "\\?\" prefix apply in that case, e.g. the path must not contain relative components ("." and "..") and must not use the forward slash ("/") as directory separator.

## Inheritance

Direct Base Classes: FileImpl

All Base Classes: FileImpl

Known Derived Classes: TemporaryFile

## Member Summary

Member Functions: absolutePath, canExecute, canRead, canWrite, copyDirectory, copyTo, createDirectories, createDirectory, createFile, created, exists, existsAnywhere, freeSpace, getExecutablePath, getLastModified, getSize, handleLastError, isDevice, isDirectory, isFile, isHidden, isLink, linkTo, list, moveTo, operator !=, operator <, operator <=, operator =, operator ==, operator >, operator >=, path, remove, renameTo, setExecutable, setLastModified, setReadOnly, setSize, setWriteable, swap, totalSpace, usableSpace

Inherited Functions: canExecuteImpl, canReadImpl, canWriteImpl, convertPath, copyToImpl, createDirectoryImpl, createFileImpl, createdImpl, existsImpl, freeSpaceImpl, getExecutablePathImpl, getLastModifiedImpl, getPathImpl, getSizeImpl, handleLastErrorImpl, isDeviceImpl, isDirectoryImpl, isFileImpl, isHiddenImpl, isLinkImpl, linkToImpl, removeImpl, renameToImpl, setExecutableImpl, setLastModifiedImpl, setPathImpl, setSizeImpl, setWriteableImpl, swapImpl, totalSpaceImpl, usableSpaceImpl

## Types Aliases

### FileSize

using FileSize = FileSizeImpl;

## Enumerations

### LinkType

Type of link for linkTo().

LINK_HARD = 0

hard link

LINK_SYMBOLIC = 1

symbolic link

### Options

Options for File Copy/Movement

OPT_FAIL_ON_OVERWRITE = OPT_FAIL_ON_OVERWRITE_IMPL

## Constructors

### File

File();

Creates the file.

### File

File(
const std::string & path
);

Creates the file.

### File

File(
const char * path
);

Creates the file.

### File

File(
const Path & path
);

Creates the file.

### File

File(
const File & file
);

Copy constructor.

## Destructor

### ~File

~File() override;

Destroys the file.

## Member Functions

### absolutePath

std::string absolutePath() const;

Returns the absolute path.

If the path is already absolute, returns it unchanged. If the path is relative, resolves it against the current working directory.

### canExecute

bool canExecute() const;

Returns true if and only if the file is executable.

Resolves the executable path using getExecutablePath(). If the resolved path is empty, returns false.

### canRead

bool canRead() const;

Returns true if and only if the file is readable.

### canWrite

bool canWrite() const;

Returns true if and only if the file is writeable.

### copyTo

void copyTo(
const std::string & path,
int options = 0
) const;

Copies the file (or directory) to the given path. The target path can be a directory.

A directory is copied recursively. If options is set to OPT_FAIL_ON_OVERWRITE the method throws a FileExistsException if the File already exists.

### createDirectories

void createDirectories();

Creates a directory (and all parent directories if necessary).

### createDirectory

bool createDirectory();

Creates a directory. Returns true if the directory has been created and false if it already exists. Throws an exception if an error occurs.

### createFile

bool createFile();

Creates a new, empty file in an atomic operation. Returns true if the file has been created and false if the file already exists. Throws an exception if an error occurs.

### created

Timestamp created() const;

Returns the creation date of the file.

Not all platforms or filesystems (e.g. Linux and most Unix platforms with the exception of FreeBSD and Mac OS X) maintain the creation date of a file. On such platforms, created() returns the time of the last inode modification.

### exists

bool exists() const;

Returns true if and only if the file exists.

### existsAnywhere

bool existsAnywhere() const;

Returns true if and only if the file exists anywhere in the file system, including in directories listed in the PATH environment variable.

### freeSpace

FileSize freeSpace() const;

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

### getExecutablePath

std::string getExecutablePath() const;

Resolves the executable path.

If the path contains a directory separator, checks whether it exists and is executable, resolves it to an absolute path and returns it.

If the path is a bare filename (no directory separator), searches the current directory and the PATH environment variable for an executable match.

On Windows, also tries appending each PATHEXT extension (e.g. .EXE, .CMD, .BAT) if the bare filename is not found as-is.

Returns the fully resolved absolute path on success, or an empty string if no executable was found.

Known limitation on Windows: If the PATH environment variable contains UNC paths (e.g., \\server\share\bin), SearchPathW may not find executables in those locations when searching for bare filenames. This is a Windows API limitation, not a Poco limitation. Workaround: Use the full UNC path including the executable name.

### getLastModified

Timestamp getLastModified() const;

Returns the modification date of the file.

### getSize

FileSize getSize() const;

Returns the size of the file in bytes.

### handleLastError

static void handleLastError(
const std::string & path
);

For internal use only. Throws an appropriate exception for the last file-related error.

### isDevice

bool isDevice() const;

Returns true if and only if the file is a device.

### isDirectory

bool isDirectory() const;

Returns true if and only if the file is a directory.

### isFile

bool isFile() const;

Returns true if and only if the file is a regular file.

### isHidden

bool isHidden() const;

Returns true if the file is hidden.

On Windows platforms, the file's hidden attribute is set for this to be true.

On Unix platforms, the file name must begin with a period for this to be true.

### isLink

bool isLink() const;

Returns true if and only if the file is a symbolic link.

### linkTo

void linkTo(
const std::string & path,
LinkType type = LINK_SYMBOLIC
) const;

Creates a link (symbolic or hard, depending on type argument) at the given path to the file or directory.

May not be supported on all platforms. Furthermore, some operating systems do not allow creating hard links to directories.

### list

void list(
std::vector < std::string > & files
) const;

Fills the vector with the names of all files in the directory.

### list

void list(
std::vector < File > & files
) const;

Fills the vector with the names of all files in the directory.

### moveTo

void moveTo(
const std::string & path,
int options = 0
);

Copies the file (or directory) to the given path and removes the original file. The target path can be a directory. If options is set to OPT_FAIL_ON_OVERWRITE the method throws a FileExistsException if the File already exists.

### operator !=

bool operator != (
const File & file
) const;

### operator <

bool operator < (
const File & file
) const;

### operator <=

bool operator <= (
const File & file
) const;

### operator =

File & operator = (
const File & file
);

Assignment operator.

### operator =

File & operator = (
const std::string & path
);

Assignment operator.

### operator =

File & operator = (
const char * path
);

Assignment operator.

### operator =

File & operator = (
const Path & path
);

Assignment operator.

### operator ==

bool operator == (
const File & file
) const;

### operator >

bool operator > (
const File & file
) const;

### operator >=

bool operator >= (
const File & file
) const;

### path

const std::string & path() const;

Returns the path.

### remove

void remove(
bool recursive = false
);

Deletes the file. If recursive is true and the file is a directory, recursively deletes all files in the directory.

### renameTo

void renameTo(
const std::string & path,
int options = 0
);

Renames the file to the new name. If options is set to OPT_FAIL_ON_OVERWRITE the method throws a FileExistsException if the File already exists.

### setExecutable

File & setExecutable(
bool flag = true
);

Makes the file executable (if flag is true), or non-executable (if flag is false) by setting the file's permission bits accordingly.

Does nothing on Windows.

### setLastModified

File & setLastModified(
const Timestamp & ts
);

Sets the modification date of the file.

### setReadOnly

File & setReadOnly(
bool flag = true
);

Makes the file non-writeable (if flag is true), or writeable (if flag is false) by setting the file's flags in the filesystem accordingly.

### setSize

File & setSize(
FileSize size
);

Sets the size of the file in bytes. Can be used to truncate a file.

### setWriteable

File & setWriteable(
bool flag = true
);

Makes the file writeable (if flag is true), or non-writeable (if flag is false) by setting the file's flags in the filesystem accordingly.

### swap

void swap(
File & file
) noexcept;

Swaps the file with another one.

### totalSpace

FileSize totalSpace() const;

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

### usableSpace

FileSize usableSpace() const;

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

### copyDirectory

void copyDirectory(
const std::string & path,
int options = 0
) const;

Copies a directory. Used internally by copyTo().