QFile Class

The QFile class provides an interface for reading from and writing to files. More…

List of all members, including inherited members

Public Functions

Reimplemented Public Functions

Static Public Members

Detailed Description

QFile opens a file by name and reads and writes it through the operating system's file descriptors. Set the name in the constructor or with setFileName(), then call open():

QFile file("data.txt");
if (file.open(QIODevice::ReadOnly)) {
    const QByteArray contents = file.readAll();
    file.close();
}

A name that starts with a colon, such as :/data/config.json, refers to a resource compiled into the program. Resources can be opened only for reading, and cannot be removed, renamed or changed; copy() copies one out to a real file. A compressed resource is decompressed into memory when it is opened.

QFile also has static functions to check whether a file exists and to remove, rename and copy files. For text and binary data, use QTextStream and QDataStream on top of a QFile.

See also QFileDevice, QTextStream, QDataStream, QSaveFile and QTemporaryFile.

Differences from Qt

Member Function Documentation

QFile::QFile()

Constructs a QFile with no file name and no parent.

See also setFileName().

[explicit] QFile::QFile(const QString &name)

This is an overloaded function.

Constructs a new file object to represent the file with the given name.

[explicit] QFile::QFile(QObject *parent)

This is an overloaded function.

Constructs a QFile with no file name and the given parent.

QFile::QFile(const QString &name, QObject *parent)

This is an overloaded function.

Constructs a new file object with the given parent to represent the file with the given name.

[override] QFile::~QFile()

Destroys the file object, closing it if necessary.

bool QFile::copy(const QString &newName)

Copies the file currently specified by fileName() to a file called newName, closing it first if it is open. Returns true if successful; otherwise returns false and sets error() to CopyError. The copy fails if a file named newName already exists.

See also rename() and remove().

[static] bool QFile::copy(const QString &fileName, const QString &newName)

This is an overloaded function.

Copies the file fileName to newName. Returns true if successful; otherwise returns false. The copy fails if a file named newName already exists.

See also copy().

[static] QString QFile::decodeName(const QByteArray &localFileName)

Returns the file name localFileName, given in the 8-bit encoding of file names (UTF-8), as a QString.

See also encodeName().

[static] QString QFile::decodeName(const char *localFileName)

This is an overloaded function.

Returns the file name localFileName, given in UTF-8, as a QString.

[static] QByteArray QFile::encodeName(const QString &fileName)

Returns fileName converted to the 8-bit encoding of file names, which is UTF-8.

See also decodeName().

bool QFile::exists() const

This is an overloaded function.

Returns true if the file specified by fileName() exists; otherwise returns false.

See also fileName() and setFileName().

[static] bool QFile::exists(const QString &fileName)

Returns true if the file specified by fileName exists; otherwise returns false.

See also remove().

bool QFile::link(const QString &linkName)

Creates a symbolic link named linkName that points to fileName(). Returns true if successful; otherwise sets error() to RenameError and returns false. An existing linkName is not replaced.

See also symLinkTarget().

[static] bool QFile::link(const QString &fileName, const QString &linkName)

This is an overloaded function.

Creates a symbolic link named linkName that points to fileName. The link stores fileName as given, so a relative name is resolved relative to the directory of the link. Returns true if successful; otherwise returns false.

bool QFile::moveToTrash()

Moves the file named by fileName() to the trash, closing it first, and sets fileName() to its path in the trash. Returns true if successful; otherwise returns false and sets error() to RenameError.

This function was introduced in 5.15.

See also remove().

[static] bool QFile::moveToTrash(const QString &fileName, QString *pathInTrash = nullptr)

This is an overloaded function.

Moves the file or directory fileName to the trash of the desktop, as the freedesktop.org trash specification describes, so that the user can restore it. Returns true if successful and stores the new path in *pathInTrash if pathInTrash is not nullptr.

This function was introduced in 5.15.

[override] bool QFile::open(OpenMode mode)

Reimplements QFileDevice::open().

Opens the file named by fileName() using the given mode. Returns true if successful; otherwise returns false and sets error() to OpenError. It fails if no file name has been set, the file is already open, or the operating system refuses to open it.

See also QFileDevice::openPath(), close() and setFileName().

bool QFile::open(OpenMode mode, Permissions permissions)

This is an overloaded function.

Opens the file named by fileName() using the given mode, and returns true if successful. If the file does not exist and mode creates it, it is created with the access permissions permissions, less what the umask of the process takes away. The file never exists with wider permissions, as it would for a moment if it were created first and restricted with setPermissions() afterwards. A file that exists already keeps the permissions that it has.

QFile key("server.key");
if (key.open(QIODevice::WriteOnly | QIODevice::NewOnly, QFileDevice::ReadOwner | QFileDevice::WriteOwner))
    key.write(secret);

This function was introduced in 6.3.

See also setPermissions().

bool QFile::open(std::FILE *fh, OpenMode mode, FileHandleFlags handleFlags = DontCloseHandle)

This is an overloaded function.

Opens the existing C stream fh in mode, which must match how the stream was opened. close() also closes the stream if handleFlags has AutoCloseHandle. Reads and writes go to the stream's descriptor, so do not mix them with stdio calls on fh.

QFile out;
out.open(stdout, QIODevice::WriteOnly);

bool QFile::open(int fd, OpenMode mode, FileHandleFlags handleFlags = DontCloseHandle)

This is an overloaded function.

Opens the existing file descriptor fd in mode. close() also closes the descriptor if handleFlags has AutoCloseHandle.

[override] Permissions QFile::permissions() const

Reimplements QFileDevice::permissions().

Returns the permissions of the file named fileName(), or of the open descriptor.

[static] Permissions QFile::permissions(const QString &fileName)

This is an overloaded function.

Returns the permissions of the file fileName, or no permissions if the file does not exist.

QString QFile::readLink() const

Returns the target of the symbolic link named by fileName() exactly as it is stored, without making it absolute, or an empty string if the file is not a symbolic link.

This function was introduced in 6.6.

See also symLinkTarget().

[static] QString QFile::readLink(const QString &fileName)

This is an overloaded function.

Returns the stored target of the symbolic link fileName, or an empty string if it is not a symbolic link.

This function was introduced in 6.6.

bool QFile::remove()

Removes the file specified by fileName(), closing it first if it is open. Returns true if successful; otherwise returns false and sets error() to RemoveError.

See also exists().

[static] bool QFile::remove(const QString &fileName)

This is an overloaded function.

Removes the file specified by fileName. Returns true if successful; otherwise returns false. The file is not moved to a trash.

See also remove() and exists().

bool QFile::rename(const QString &newName)

Renames the file currently specified by fileName() to newName, closing it first if it is open. Returns true if successful; otherwise returns false and sets error() to RenameError. On success, fileName() becomes newName.

See also exists().

[static] bool QFile::rename(const QString &oldName, const QString &newName)

This is an overloaded function.

Renames the file oldName to newName. Returns true if successful; otherwise returns false. An existing file at newName is replaced.

See also rename().

void QFile::setFileName(const QString &name)

Sets the name of the file. The name has no path, a relative path, or an absolute path. Does nothing if the file is open.

See also fileName() and exists().

[override] bool QFile::setPermissions(Permissions permissions)

Reimplements QFileDevice::setPermissions().

Sets the permissions of the file to permissions.

[static] bool QFile::setPermissions(const QString &fileName, Permissions permissions)

This is an overloaded function.

Sets the permissions of the file fileName to permissions. Returns true if successful; otherwise returns false.

QString QFile::symLinkTarget() const

Returns the absolute path that the symbolic link fileName() points to, or an empty string if the file is not a symbolic link.

This function was introduced in 4.2.

See also link() and QFileInfo::symLinkTarget().

[static] QString QFile::symLinkTarget(const QString &fileName)

This is an overloaded function.

Returns the absolute path that the symbolic link fileName points to, or an empty string if it is not a symbolic link.