class Poco::File

Overview

The File class provides methods for working with a file. More…

#include <File.h>

class File: private Poco::FileImpl
{
public:
    // typedefs

    typedef FileSizeImpl FileSize;

    // construction

    File();
    File(const std::string& path);
    File(const char* path);
    File(const Path& path);
    File(const File& file);

    // methods

    File&
    operator=(const File& file);

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

    File&
    operator=(const char* path);

    File&
    operator=(const Path& path);

    void
    swap(File& file);

    const std::string&
    path() const;

    bool
    exists() const;

    bool
    canRead() const;

    bool
    canWrite() const;

    bool
    canExecute() const;

    bool
    isFile() const;

    bool
    isLink() const;

    bool
    isDirectory() const;

    bool
    isDevice() const;

    bool
    isHidden() const;

    Timestamp
    created() const;

    Timestamp
    getLastModified() const;

    File&
    setLastModified(const Timestamp& ts);

    FileSize
    getSize() const;

    File&
    setSize(FileSize size);

    File&
    setWriteable(bool flag = true);

    File&
    setReadOnly(bool flag = true);

    File&
    setExecutable(bool flag = true);

    void
    copyTo(const std::string& path) const;

    void
    moveTo(const std::string& path);

    void
    renameTo(const std::string& path);

    void
    remove(bool recursive = false);

    bool
    createFile();

    bool
    createDirectory();

    void
    createDirectories();

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

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

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

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

    bool
    operator<(const File& file) const;

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

    bool
    operator>(const File& file) const;

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

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

protected:
    // methods

    void
    copyDirectory(const std::string& path) const;
};

// direct descendants

class TemporaryFile;

Inherited Members

protected:
    // typedefs

    typedef UInt64 FileSizeImpl;

    // methods

    const std::string&
    getPathImpl() const;

    void
    setPath(const std::string& path);

    void
    swapImpl(FileImpl& file);

    void
    setPathImpl(const std::string& path);

    const std::string&
    getPathImpl() const;

    bool
    existsImpl() const;

    bool
    canReadImpl() const;

    bool
    canWriteImpl() const;

    bool
    canExecuteImpl() const;

    bool
    isFileImpl() const;

    bool
    isDirectoryImpl() const;

    bool
    isLinkImpl() const;

    bool
    isDeviceImpl() const;

    bool
    isHiddenImpl() const;

    Timestamp
    createdImpl() const;

    Timestamp
    getLastModifiedImpl() const;

    void
    setLastModifiedImpl(const Timestamp& ts);

    FileSizeImpl
    getSizeImpl() const;

    void
    setSizeImpl(FileSizeImpl size);

    void
    setWriteableImpl(bool flag = true);

    void
    setExecutableImpl(bool flag = true);

    void
    copyToImpl(const std::string& path) const;

    void
    renameToImpl(const std::string& path);

    void
    removeImpl();

    bool
    createFileImpl();

    bool
    createDirectoryImpl();

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

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

    static
    void
    convertPath(
        const std::string& utf8Path,
        std::wstring& utf16Path
        );

Detailed Documentation

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, if compiled with UTF-8 support (POCO_WIN32_UTF8) 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.

Construction

File()

Creates the file.

File(const std::string& path)

Creates the file.

File(const char* path)

Creates the file.

File(const Path& path)

Creates the file.

File(const File& file)

Copy constructor.

Methods

File&
operator=(const File& file)

Assignment operator.

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

Assignment operator.

File&
operator=(const char* path)

Assignment operator.

File&
operator=(const Path& path)

Assignment operator.

void
swap(File& file)

Swaps the file with another one.

const std::string&
path() const

Returns the path.

bool
exists() const

Returns true iff the file exists.

bool
canRead() const

Returns true iff the file is readable.

bool
canWrite() const

Returns true iff the file is writeable.

bool
canExecute() const

Returns true iff the file is executable.

On Windows and OpenVMS, the file must have the extension “.EXE” to be executable. On Unix platforms, the executable permission bit must be set.

bool
isFile() const

Returns true iff the file is a regular file.

bool
isLink() const

Returns true iff the file is a symbolic link.

bool
isDirectory() const

Returns true iff the file is a directory.

bool
isDevice() const

Returns true iff the file is a device.

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.

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.

Timestamp
getLastModified() const

Returns the modification date of the file.

File&
setLastModified(const Timestamp& ts)

Sets the modification date of the file.

FileSize
getSize() const

Returns the size of the file in bytes.

File&
setSize(FileSize size)

Sets the size of the file in bytes.

Can be used to truncate a file.

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.

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.

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 and OpenVMS.

void
copyTo(const std::string& path) const

Copies the file (or directory) to the given path.

The target path can be a directory.

A directory is copied recursively.

void
moveTo(const std::string& path)

Copies the file (or directory) to the given path and removes the original file.

The target path can be a directory.

void
renameTo(const std::string& path)

Renames the file to the new name.

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.

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.

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.

void
createDirectories()

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

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

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

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

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

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

For internal use only.

Throws an appropriate exception for the last file-related error.

void
copyDirectory(const std::string& path) const

Copies a directory. Used internally by copyTo().