Revision control
Copy as Markdown
// Copyright (C) 2020 The Qt Company Ltd.
// Copyright (C) 2017 Intel Corporation.
// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR LGPL-3.0-only OR GPL-2.0-only OR GPL-3.0-only
// Qt-Security score:significant reason:default
#include "qplatformdefs.h"
#include "qdebug.h"
#include "qfile.h"
#include "qfileinfo.h"
#include "qfsfileengine_p.h"
#include "qlist.h"
#include "qsavefile.h"
#include "qtemporaryfile.h"
#include "private/qiodevice_p.h"
#include "private/qfile_p.h"
#include "private/qfilesystemengine_p.h"
#include "private/qsavefile_p.h"
#include "private/qsystemerror_p.h"
#include "private/qtemporaryfile_p.h"
#if defined(QT_BUILD_CORE_LIB)
# include "qcoreapplication.h"
#endif
#ifdef QT_NO_QOBJECT
#define tr(X) QString::fromLatin1(X)
#endif
QT_BEGIN_NAMESPACE
using namespace Qt::StringLiterals;
Q_DECL_COLD_FUNCTION
static bool file_already_open(QFile &file, const char *where = nullptr)
{
qWarning("QFile::%s: File (%ls) already open", where ? where : "open", qUtf16Printable(file.fileName()));
return false;
}
//************* QFilePrivate
QFilePrivate::QFilePrivate()
{
}
QFilePrivate::~QFilePrivate()
{
}
bool
QFilePrivate::openExternalFile(QIODevice::OpenMode flags, int fd, QFile::FileHandleFlags handleFlags)
{
#ifdef QT_NO_FSFILEENGINE
Q_UNUSED(flags);
Q_UNUSED(fd);
return false;
#else
auto fs = std::make_unique<QFSFileEngine>();
auto fe = fs.get();
fileEngine = std::move(fs);
return fe->open(flags, fd, handleFlags);
#endif
}
bool
QFilePrivate::openExternalFile(QIODevice::OpenMode flags, FILE *fh, QFile::FileHandleFlags handleFlags)
{
#ifdef QT_NO_FSFILEENGINE
Q_UNUSED(flags);
Q_UNUSED(fh);
return false;
#else
auto fs = std::make_unique<QFSFileEngine>();
auto fe = fs.get();
fileEngine = std::move(fs);
return fe->open(flags, fh, handleFlags);
#endif
}
QAbstractFileEngine *QFilePrivate::engine() const
{
if (!fileEngine)
fileEngine = QAbstractFileEngine::create(fileName);
return fileEngine.get();
}
//************* QFile
/*!
\class QFile
\inmodule QtCore
\brief The QFile class provides an interface for reading from and writing to files.
\ingroup io
\reentrant
QFile is an I/O device for reading and writing text and binary
files and \l{The Qt Resource System}{resources}. A QFile may be
used by itself or, more conveniently, with a QTextStream or
QDataStream.
The file name is usually passed in the constructor, but it can be
set at any time using setFileName(). QFile expects the file
separator to be '/' regardless of operating system. The use of
other separators (e.g., '\\') is not supported.
You can check for a file's existence using exists(), and remove a
file using remove(). (More advanced file system related operations
are provided by QFileInfo and QDir.)
The file is opened with open(), closed with close(), and flushed
with flush(). Data is usually read and written using QDataStream
or QTextStream, but you can also call the QIODevice-inherited
functions read(), readLine(), readAll(), write(). QFile also
inherits getChar(), putChar(), and ungetChar(), which work one
character at a time.
The size of the file is returned by size(). You can get the
current file position using pos(), or move to a new file position
using seek(). If you've reached the end of the file, atEnd()
returns \c true.
\section1 Reading Files Directly
The following example reads a text file line by line:
\snippet file/file.cpp 0
The \l{QIODeviceBase::}{Text} flag passed to open() tells Qt to convert
Windows-style line terminators ("\\r\\n") into C++-style
terminators ("\\n"). By default, QFile assumes binary, i.e. it
doesn't perform any conversion on the bytes stored in the file.
\section1 Using Streams to Read Files
The next example uses QTextStream to read a text file
line by line:
\snippet file/file.cpp 1
QTextStream takes care of converting the 8-bit data stored on
disk into a 16-bit Unicode QString. By default, it assumes that
the file is encoded in UTF-8. This can be changed using
\l QTextStream::setEncoding().
To write text, we can use operator<<(), which is overloaded to
take a QTextStream on the left and various data types (including
QString) on the right:
\snippet file/file.cpp 2
QDataStream is similar, in that you can use operator<<() to write
data and operator>>() to read it back. See the class
documentation for details.
\section1 Signals
Unlike other QIODevice implementations, such as QTcpSocket, QFile does not
emit the aboutToClose(), bytesWritten(), or readyRead() signals. This
implementation detail means that QFile is not suitable for reading and
writing certain types of files, such as device files on Unix platforms.
\section1 Platform Specific Issues
\l{Input/Output and Networking}{Qt APIs related to I/O} use UTF-16 based
QStrings to represent file paths. Standard C++ APIs (\c <cstdio> or
\c <iostream>) or platform-specific APIs however often need a 8-bit encoded
path. You can use encodeName() and decodeName() to convert between both
representations.
On Unix, there are some special system files (e.g. in \c /proc) for which
size() will always return 0, yet you may still be able to read more data
from such a file; the data is generated in direct response to you calling
read(). In this case, however, you cannot use atEnd() to determine if
there is more data to read (since atEnd() will return true for a file that
claims to have size 0). Instead, you should either call readAll(), or call
read() or readLine() repeatedly until no more data can be read. The next
example uses QTextStream to read \c /proc/modules line by line:
\snippet file/file.cpp 3
\include android-content-uri-limitations.qdocinc
\section1 Security Considerations
\section2 Windows path normalization
Qt APIs that handle file and directory paths perform the normalization and
canonicalization differently from the native Windows APIs:
\list
\li The trailing dots and/or whitespaces are not stripped.
\li The \l{https://learn.microsoft.com/en-us/windows/win32/fileio/naming-a-file#short-vs-long-names}
{8.3 short names} are not expanded.
\li The \c{\\?\} and \c{\\?\UNC\} prefixes are always discarded.
\endlist
These differences open a possibility for bypassing security checks based
on string comparison or pattern matching. For example, the code below will
yield \c{false} for both comparisons, but passing this path into QFile will
successfully open \c {myapp.exe} in \c{Program Files}.
\code
const QString path = u"C:\\PROGRA~1\\MyApp\\myapp.exe."_s; // note the trailing dot
QFileInfo fi(path);
qDebug() << fi.canonicalFilePath().contains("Program Files"_L1); // false
qDebug() << (fi.suffix() == "exe"_L1); // false
QFile f(path);
f.open(QIODevice::WriteOnly); // true
\endcode
\section2 File permissions
File permissions are handled differently on Unix-like systems and
Windows. In a non \l{QIODevice::isWritable()}{writable}
directory on Unix-like systems, files cannot be created. This is not always
the case on Windows, where, for instance, the 'My Documents'
directory usually is not writable, but it is still possible to
create files in it.
Qt's understanding of file permissions is limited, which affects especially
the \l QFile::setPermissions() function. On Windows, Qt will set only the
legacy read-only flag, and that only when none of the Write* flags are
passed. Qt does not manipulate access control lists (ACLs), which makes this
function mostly useless for NTFS volumes. It may still be of use for USB
sticks that use VFAT file systems. POSIX ACLs are not manipulated, either.
\sa QTextStream, QDataStream, QFileInfo, QDir, {The Qt Resource System}
*/
#ifdef QT_NO_QOBJECT
QFile::QFile()
: QFileDevice(*new QFilePrivate)
{
}
QFile::QFile(const QString &name)
: QFileDevice(*new QFilePrivate)
{
d_func()->fileName = name;
}
QFile::QFile(QFilePrivate &dd)
: QFileDevice(dd)
{
}
#else
/*!
Constructs a QFile object.
*/
QFile::QFile()
: QFileDevice(*new QFilePrivate, nullptr)
{
}
/*!
Constructs a new file object with the given \a parent.
*/
QFile::QFile(QObject *parent)
: QFileDevice(*new QFilePrivate, parent)
{
}
/*!
Constructs a new file object to represent the file with the given \a name.
//! [qfile-explicit-constructor-note]
\note In versions up to and including Qt 6.8, this constructor is
implicit, for backward compatibility. Starting from Qt 6.9 this
constructor is unconditionally \c{explicit}. Users can force this
constructor to be \c{explicit} even in earlier versions of Qt by
defining the \c{QT_EXPLICIT_QFILE_CONSTRUCTION_FROM_PATH} macro
before including any Qt header.
//! [qfile-explicit-constructor-note]
*/
QFile::QFile(const QString &name)
: QFileDevice(*new QFilePrivate, nullptr)
{
Q_D(QFile);
d->fileName = name;
}
/*!
Constructs a new file object with the given \a parent to represent the
file with the specified \a name.
*/
QFile::QFile(const QString &name, QObject *parent)
: QFileDevice(*new QFilePrivate, parent)
{
Q_D(QFile);
d->fileName = name;
}
/*!
\internal
*/
QFile::QFile(QFilePrivate &dd, QObject *parent)
: QFileDevice(dd, parent)
{
}
#endif
/*!
Destroys the file object, closing it if necessary.
*/
QFile::~QFile()
{
}
/*!
Returns the name of the file as set by setFileName(), rename(), or
by the QFile constructors.
\sa setFileName(), rename(), QFileInfo::fileName()
*/
QString QFile::fileName() const
{
Q_D(const QFile);
return d->engine()->fileName(QAbstractFileEngine::DefaultName);
}
/*!
Sets the \a name of the file. The name can have no path, a
relative path, or an absolute path.
Do not call this function if the file has already been opened.
If the file name has no path or a relative path, the path used
will be the application's current directory path
\e{at the time of the open()} call.
Example:
\snippet code/src_corelib_io_qfile.cpp 0
Note that the directory separator "/" works for all operating
systems supported by Qt.
\sa fileName(), QFileInfo, QDir
*/
void
QFile::setFileName(const QString &name)
{
Q_D(QFile);
if (isOpen()) {
file_already_open(*this, "setFileName");
close();
}
d->fileEngine.reset(); //get a new file engine later
d->fileName = name;
}
/*!
\fn QString QFile::decodeName(const char *localFileName)
\overload
Returns the Unicode version of the given \a localFileName. See
encodeName() for details.
*/
/*!
\fn QByteArray QFile::encodeName(const QString &fileName)
Converts \a fileName to an 8-bit encoding that you can use in native
APIs. On Windows, the encoding is the one from active Windows (ANSI)
codepage. On other platforms, this is UTF-8, for \macos in decomposed
form (NFD).
\sa decodeName()
*/
/*!
\fn QString QFile::decodeName(const QByteArray &localFileName)
This does the reverse of QFile::encodeName() using \a localFileName.
\sa encodeName()
*/
/*!
\overload
Returns \c true if the file specified by fileName() exists; otherwise
returns \c false.
\sa fileName(), setFileName()
*/
bool
QFile::exists() const
{
Q_D(const QFile);
// 0x1000000 = QAbstractFileEngine::Refresh, forcing an update
return d->engine()->fileFlags(QAbstractFileEngine::FlagsMask
| QAbstractFileEngine::Refresh).testAnyFlag(QAbstractFileEngine::ExistsFlag);
}
/*!
Returns \c true if the file specified by \a fileName exists; otherwise
returns \c false.
\note If \a fileName is a symlink that points to a non-existing
file, false is returned.
*/
bool
QFile::exists(const QString &fileName)
{
return QFileInfo::exists(fileName);
}
/*!
\fn QString QFile::symLinkTarget() const
\since 4.2
\overload
Returns the absolute path of the file or directory a symlink (or shortcut
on Windows) points to, or a an empty string if the object isn't a symbolic
link.
This name may not represent an existing file; it is only a string.
QFile::exists() returns \c true if the symlink points to an existing file.
\sa fileName(), setFileName()
*/
QString QFile::symLinkTarget() const
{
Q_D(const QFile);
return d->engine()->fileName(QAbstractFileEngine::AbsoluteLinkTarget);
}
/*!
\fn static QString QFile::symLinkTarget(const QString &fileName)
\since 4.2
Returns the absolute path of the file or directory referred to by the
symlink (or shortcut on Windows) specified by \a fileName, or returns an
empty string if the \a fileName does not correspond to a symbolic link.
This name may not represent an existing file; it is only a string.
QFile::exists() returns \c true if the symlink points to an existing file.
*/
QString QFile::symLinkTarget(const QString &fileName)
{
return QFileInfo(fileName).symLinkTarget();
}
/*!
Removes the file specified by fileName().
Returns \c true if the file was successfully removed; otherwise returns \c
false.
The file is closed before it is removed, if it was open.
\sa setFileName()
*/
bool
QFile::remove()
{
Q_D(QFile);
if (d->fileName.isEmpty() &&
!static_cast<QFSFileEngine *>(d->engine())->isUnnamedFile()) {
qWarning("QFile::remove: Empty or null file name");
return false;
}
unsetError();
close();
if (error() == QFile::NoError) {
if (d->engine()->remove()) {
unsetError();
return true;
}
d->setError(QFile::RemoveError, d->fileEngine->errorString());
}
return false;
}
/*!
\overload
Removes the file specified by the \a fileName given.
Returns \c true if the file was successfully removed; otherwise returns
\c false.
\sa remove()
*/
bool
QFile::remove(const QString &fileName)
{
return QFile(fileName).remove();
}
/*!
\since 6.9
Returns \c true if Qt supports moving files to a trash (recycle bin) in the
current operating system using the moveToTrash() function, \c false
otherwise. Note that this function returning \c true does not imply
moveToTrash() will succeed. In particular, this function does not check if
the user has disabled the functionality in their settings.
\sa moveToTrash()
*/
bool QFile::supportsMoveToTrash()
{
return QFileSystemEngine::supportsMoveFileToTrash();
}
/*!
\since 5.15
Moves the file specified by fileName() to the trash. Returns \c true if successful,
and sets the fileName() to the path at which the file can be found within the trash;
otherwise returns \c false.
//! [move-to-trash-common]
The time for this function to run is independent of the size of the file
being trashed. If this function is called on a directory, it may be
proportional to the number of files being trashed. If the current
fileName() points to a symbolic link, this function will move the link to
the trash, possibly breaking it, not the target of the link.
This function uses the Windows and \macos APIs to perform the trashing on
those two operating systems. Elsewhere (Unix systems), this function
implements the \l{FreeDesktop.org Trash specification version 1.0}.
\note When using the FreeDesktop.org Trash implementation, this function
will fail if it is unable to move the files to the trash location by way of
file renames and hardlinks. This condition arises if the file being trashed
resides on a volume (mount point) on which the current user does not have
permission to create the \c{.Trash} directory, or with some unusual
filesystem types or configurations (such as sub-volumes that aren't
themselves mount points).
//! [move-to-trash-common]
\note On systems where the system API doesn't report the location of the
file in the trash, fileName() will be set to the null string once the file
has been moved. On systems that don't have a trash can, this function
always returns \c false (see supportsMoveToTrash()).
\sa supportsMoveToTrash(), remove(), QDir::remove()
*/
bool
QFile::moveToTrash()
{
Q_D(QFile);
if (d->fileName.isEmpty() &&
!static_cast<QFSFileEngine *>(d->engine())->isUnnamedFile()) {
qWarning("QFile::remove: Empty or null file name");
return false;
}
unsetError();
close();
if (error() == QFile::NoError) {
QFileSystemEntry fileEntry(d->fileName);
QFileSystemEntry trashEntry;
QSystemError error;
if (QFileSystemEngine::moveFileToTrash(fileEntry, trashEntry, error)) {
setFileName(trashEntry.filePath());
unsetError();
return true;
}
d->setError(QFile::RenameError, error.toString());
}
return false;
}
/*!
\since 5.15
\overload
Moves the file specified by \a fileName to the trash. Returns \c true if successful,
and sets \a pathInTrash (if provided) to the path at which the file can be found within
the trash; otherwise returns \c false.
\include qfile.cpp move-to-trash-common
\note On systems where the system API doesn't report the path of the file in the
trash, \a pathInTrash will be set to the null string once the file has been moved.
On systems that don't have a trash can, this function always returns false.
*/
bool
QFile::moveToTrash(const QString &fileName, QString *pathInTrash)
{
QFile file(fileName);
if (file.moveToTrash()) {
if (pathInTrash)
*pathInTrash = file.fileName();
return true;
}
return false;
}
/*!
Renames the file currently specified by fileName() to \a newName.
Returns \c true if successful; otherwise returns \c false.
If a file with the name \a newName already exists, rename() returns \c false
(i.e., QFile will not overwrite it).
The file is closed before it is renamed.
If the rename operation fails, Qt will attempt to copy this file's
contents to \a newName, and then remove this file, keeping only
\a newName. If that copy operation fails or this file can't be removed,
the destination file \a newName is removed to restore the old state.
\sa setFileName()
*/
bool
QFile::rename(const QString &newName)
{
Q_D(QFile);
// if this is a QTemporaryFile, the virtual fileName() call here may do something
if (fileName().isEmpty()) {
qWarning("QFile::rename: Empty or null file name");
return false;
}
if (d->fileName == newName) {
d->setError(QFile::RenameError, tr("Destination file is the same file."));
return false;
}
if (!exists()) {
d->setError(QFile::RenameError, tr("Source file does not exist."));
return false;
}
// Keep engine for target alive during the operation
// FIXME: Involve the target engine in the operation
auto targetEngine = QFileSystemEngine::createLegacyEngine(newName);
// If the file exists and it is a case-changing rename ("foo" -> "Foo"),
// compare Ids to make sure it really is a different file.
// Note: this does not take file engines into account.
bool changingCase = false;
QByteArray targetId = QFileSystemEngine::id(QFileSystemEntry(newName));
if (!targetId.isNull()) {
QByteArray fileId = d->fileEngine ?
d->fileEngine->id() :
QFileSystemEngine::id(QFileSystemEntry(d->fileName));
changingCase = (fileId == targetId && d->fileName.compare(newName, Qt::CaseInsensitive) == 0);
if (!changingCase) {
d->setError(QFile::RenameError, tr("Destination file exists"));
return false;
}
#if defined(Q_OS_LINUX) && QT_CONFIG(temporaryfile)
// rename() on Linux simply does nothing when renaming "foo" to "Foo" on a case-insensitive
// FS, such as FAT32. Move the file away and rename in 2 steps to work around.
QTemporaryFileName tfn(d->fileName);
QFileSystemEntry src(d->fileName);
QSystemError error;
for (int attempt = 0; attempt < 16; ++attempt) {
QFileSystemEntry tmp(tfn.generateNext(), QFileSystemEntry::FromNativePath());
// rename to temporary name
if (!QFileSystemEngine::renameFile(src, tmp, error))
continue;
// rename to final name
if (QFileSystemEngine::renameFile(tmp, QFileSystemEntry(newName), error)) {
d->fileEngine->setFileName(newName);
d->fileName = newName;
return true;
}
// We need to restore the original file.
QSystemError error2;
if (QFileSystemEngine::renameFile(tmp, src, error2))
break; // report the original error, below
// report both errors
d->setError(QFile::RenameError,
tr("Error while renaming: %1").arg(error.toString())
+ u'\n'
+ tr("Unable to restore from %1: %2").
arg(QDir::toNativeSeparators(tmp.filePath()), error2.toString()));
return false;
}
d->setError(QFile::RenameError,
tr("Error while renaming: %1").arg(error.toString()));
return false;
#endif // Q_OS_LINUX
}
unsetError();
close();
if (error() == QFile::NoError) {
if (changingCase ? d->engine()->renameOverwrite(newName) : d->engine()->rename(newName)) {
unsetError();
// engine was able to handle the new name so we just reset it
d->fileEngine->setFileName(newName);
d->fileName = newName;
return true;
}
// Engine was unable to rename and the fallback will delete the original file,
// so we have to back out here on case-insensitive file systems:
if (changingCase) {
d->setError(QFile::RenameError, d->fileEngine->errorString());
return false;
}
if (isSequential()) {
d->setError(QFile::RenameError, tr("Will not rename sequential file using block copy"));
return false;
}
#if QT_CONFIG(temporaryfile)
// copy the file to the destination first
if (d->copy(newName, permissions())) {
// succeeded, remove the original
if (!remove()) {
d->setError(QFile::RenameError, tr("Cannot remove source file: %1").arg(errorString()));
QFile out(newName);
// set it back to writable so we can delete it
out.setPermissions(ReadUser | WriteUser);
out.remove(newName);
return false;
}
d->fileEngine->setFileName(newName);
unsetError();
setFileName(newName);
return true;
} else {
// change the error type but keep the string
d->setError(QFile::RenameError, errorString());
}
#else
// copy the error from the engine rename() above
d->setError(QFile::RenameError, d->fileEngine->errorString());
#endif
}
return false;
}
/*!
\overload
Renames the file \a oldName to \a newName. Returns \c true if
successful; otherwise returns \c false.
If a file with the name \a newName already exists, rename() returns \c false
(i.e., QFile will not overwrite it).
\sa rename()
*/
bool
QFile::rename(const QString &oldName, const QString &newName)
{
return QFile(oldName).rename(newName);
}
/*!
Creates a link named \a linkName that points to the file currently specified by
fileName(). What a link is depends on the underlying filesystem (be it a
shortcut on Windows or a symbolic link on Unix). Returns \c true if successful;
otherwise returns \c false.
This function will not overwrite an already existing entity in the file system;
in this case, \c link() will return false and set \l{QFile::}{error()} to
return \l{QFile::}{RenameError}.
\note To create a valid link on Windows, \a linkName must have a \c{.lnk} file extension.
\sa setFileName()
*/
bool
QFile::link(const QString &linkName)
{
Q_D(QFile);
if (fileName().isEmpty()) {
qWarning("QFile::link: Empty or null file name");
return false;
}
// Keep engine for target alive during the operation
// FIXME: Involve the target engine in the operation
auto targetEngine = QFileSystemEngine::createLegacyEngine(linkName);
QFileInfo fi(linkName);
if (d->engine()->link(fi.absoluteFilePath())) {
unsetError();
return true;
}
d->setError(QFile::RenameError, d->fileEngine->errorString());
return false;
}
/*!
\overload
Creates a link named \a linkName that points to the file \a fileName. What a link is
depends on the underlying filesystem (be it a shortcut on Windows
or a symbolic link on Unix). Returns \c true if successful; otherwise
returns \c false.
\sa link()
*/
bool
QFile::link(const QString &fileName, const QString &linkName)
{
return QFile(fileName).link(linkName);
}
#if QT_CONFIG(temporaryfile) // dangerous without QTemporaryFile
bool QFilePrivate::copy(const QString &newName, QFileDevice::Permissions permissions)
{
Q_Q(QFile);
Q_ASSERT(error == QFile::NoError);
Q_ASSERT(!q->isOpen());
// Keep engine for target alive during the operation
// FIXME: Involve the target engine in the operation
auto targetEngine = QFileSystemEngine::createLegacyEngine(newName);
// Some file engines can perform this copy more efficiently (e.g., Windows
// calling CopyFile).
if (engine()->copy(newName))
return true;
if (!q->open(QFile::ReadOnly | QFile::Unbuffered)) {
setError(QFile::CopyError, QFile::tr("Cannot open %1 for input").arg(fileName));
return false;
}
QSaveFile out(newName);
out.setDirectWriteFallback(true);
if (!out.open(QIODevice::WriteOnly | QIODevice::Unbuffered)) {
q->close();
setError(QFile::CopyError, QFile::tr("Cannot open for output: %1").arg(out.errorString()));
return false;
}
// Attempt to do an OS-level data copy
QAbstractFileEngine::TriStateResult r = engine()->cloneTo(out.d_func()->engine());
if (r == QAbstractFileEngine::TriStateResult::Failed) {
q->close();
setError(QFile::CopyError, QFile::tr("Could not copy to %1: %2")
.arg(newName, engine()->errorString()));
return false;
}
while (r == QAbstractFileEngine::TriStateResult::NotSupported) {
// OS couldn't do it, so do a block-level copy
Q_DECL_UNINITIALIZED
char block[4096];
qint64 in = q->read(block, sizeof(block));
if (in == 0)
break; // eof
if (in < 0) {
// Unable to read from the source. Save the error from read() above.
QString s = std::move(errorString);
q->close();
setError(QFile::CopyError, std::move(s));
return false;
}
if (in != out.write(block, in)) {
q->close();
setError(QFile::CopyError, QFile::tr("Failure to write block: %1")
.arg(out.errorString()));
return false;
}
}
// copy the permissions
out.setPermissions(permissions);
q->close();
// final step: commit the copy
if (out.commit())
return true;
setError(out.error(), out.errorString());
return false;
}
/*!
Copies the file named fileName() to \a newName.
This file is closed before it is copied.
\include qfile-copy.qdocinc
\sa setFileName()
*/
bool
QFile::copy(const QString &newName, std::optional<QFileDevice::Permissions> perm)
{
Q_D(QFile);
if (fileName().isEmpty()) {
qWarning("QFile::copy: Empty or null file name");
return false;
}
if (QFile::exists(newName)) {
// ### Race condition. If a file is moved in after this, it /will/ be
// overwritten. On Unix, the proper solution is to use hardlinks:
// return ::link(old, new) && ::remove(old); See also rename().
d->setError(QFile::CopyError, tr("Destination file exists"));
return false;
}
unsetError();
close();
if (error() == QFile::NoError)
return d->copy(newName, perm ? *perm : permissions());
return false;
}
/*!
\overload
Copies the file named \a fileName to \a newName.
\include qfile-copy.qdocinc
\sa rename()
*/
bool
QFile::copy(const QString &fileName, const QString &newName,
std::optional<QFileDevice::Permissions> perm)
{
return QFile(fileName).copy(newName, perm);
}
#endif // QT_CONFIG(temporaryfile)
/*!
Opens the file using \a mode flags, returning \c true if successful;
otherwise returns \c false.
The flags for \a mode must include \l QIODeviceBase::ReadOnly,
\l WriteOnly, or \l ReadWrite. It may also have additional flags,
such as \l Text and \l Unbuffered.
\note In \l{WriteOnly} or \l{ReadWrite}
mode, if the relevant file does not already exist, this function
will try to create a new file before opening it. The file will be
created with mode 0666 masked by the umask on POSIX systems, and
with permissions inherited from the parent directory on Windows.
On Android, it's expected to have access permission to the parent
of the file name, otherwise, it won't be possible to create this
non-existing file.
\sa QT_USE_NODISCARD_FILE_OPEN, setFileName()
*/
bool QFile::open(OpenMode mode)
{
Q_D(QFile);
if (isOpen())
return file_already_open(*this);
// Either Append or NewOnly implies WriteOnly
if (mode & (Append | NewOnly))
mode |= WriteOnly;
unsetError();
if ((mode & (ReadOnly | WriteOnly)) == 0) {
qWarning("QIODevice::open: File access not specified");
return false;
}
// QIODevice provides the buffering, so there's no need to request it from the file engine.
if (d->engine()->open(mode | QIODevice::Unbuffered)) {
QIODevice::open(mode);
if (mode & Append)
seek(size());
return true;
}
QFile::FileError err = d->fileEngine->error();
if (err == QFile::UnspecifiedError)
err = QFile::OpenError;
d->setError(err, d->fileEngine->errorString());
return false;
}
/*!
\overload
If the file does not exist and \a mode implies creating it, it is created
with the specified \a permissions.
On POSIX systems the actual permissions are influenced by the
value of \c umask.
On Windows the permissions are emulated using ACLs. These ACLs may be in non-canonical
order when the group is granted less permissions than others. Files and directories with
such permissions will generate warnings when the Security tab of the Properties dialog
is opened. Granting the group all permissions granted to others avoids such warnings.
\sa QIODevice::OpenMode, setFileName(), QT_USE_NODISCARD_FILE_OPEN
\since 6.3
*/
bool QFile::open(OpenMode mode, QFile::Permissions permissions)
{
Q_D(QFile);
if (isOpen())
return file_already_open(*this);
// Either Append or NewOnly implies WriteOnly
if (mode & (Append | NewOnly))
mode |= WriteOnly;
unsetError();
if ((mode & (ReadOnly | WriteOnly)) == 0) {
qWarning("QIODevice::open: File access not specified");
return false;
}
// QIODevice provides the buffering, so there's no need to request it from the file engine.
if (d->engine()->open(mode | QIODevice::Unbuffered, permissions)) {
QIODevice::open(mode);
if (mode & Append)
seek(size());
return true;
}
QFile::FileError err = d->fileEngine->error();
if (err == QFile::UnspecifiedError)
err = QFile::OpenError;
d->setError(err, d->fileEngine->errorString());
return false;
}
/*!
\overload
Opens the existing file handle \a fh in the given \a mode.
\a handleFlags may be used to specify additional options.
Returns \c true if successful; otherwise returns \c false.
Example:
\snippet code/src_corelib_io_qfile.cpp 3
When a QFile is opened using this function, behaviour of close() is
controlled by the AutoCloseHandle flag.
If AutoCloseHandle is specified, and this function succeeds,
then calling close() closes the adopted handle.
Otherwise, close() does not actually close the file, but only flushes it.
\b{Warning:}
\list 1
\li If \a fh does not refer to a regular file, e.g., it is \c stdin,
\c stdout, or \c stderr, you may not be able to seek(). size()
returns \c 0 in those cases. See QIODevice::isSequential() for
more information.
\li Since this function opens the file without specifying the file name,
you cannot use this QFile with a QFileInfo.
\endlist
\sa close(), QT_USE_NODISCARD_FILE_OPEN
\b{Note for the Windows Platform}
\a fh must be opened in binary mode (i.e., the mode string must contain
'b', as in "rb" or "wb") when accessing files and other random-access
devices. Qt will translate the end-of-line characters if you pass
QIODevice::Text to \a mode. Sequential devices, such as stdin and stdout,
are unaffected by this limitation.
You need to enable support for console applications in order to use the
stdin, stdout and stderr streams at the console. To do this, add the
following declaration to your application's project file:
\snippet code/src_corelib_io_qfile.cpp 4
*/
bool QFile::open(FILE *fh, OpenMode mode, FileHandleFlags handleFlags)
{
Q_D(QFile);
if (isOpen())
return file_already_open(*this);
// Either Append or NewOnly implies WriteOnly
if (mode & (Append | NewOnly))
mode |= WriteOnly;
unsetError();
if ((mode & (ReadOnly | WriteOnly)) == 0) {
qWarning("QFile::open: File access not specified");
return false;
}
// QIODevice provides the buffering, so request unbuffered file engines
if (d->openExternalFile(mode | Unbuffered, fh, handleFlags)) {
QIODevice::open(mode);
if (!(mode & Append) && !isSequential()) {
qint64 pos = (qint64)QT_FTELL(fh);
if (pos != -1) {
// Skip redundant checks in QFileDevice::seek().
QIODevice::seek(pos);
}
}
return true;
}
return false;
}
/*!
\overload
Opens the existing file descriptor \a fd in the given \a mode.
\a handleFlags may be used to specify additional options.
Returns \c true if successful; otherwise returns \c false.
When a QFile is opened using this function, behaviour of close() is
controlled by the AutoCloseHandle flag.
If AutoCloseHandle is specified, and this function succeeds,
then calling close() closes the adopted handle.
Otherwise, close() does not actually close the file, but only flushes it.
\warning If \a fd is not a regular file, e.g, it is 0 (\c stdin),
1 (\c stdout), or 2 (\c stderr), you may not be able to seek(). In
those cases, size() returns \c 0. See QIODevice::isSequential()
for more information.
\warning Since this function opens the file without specifying the file name,
you cannot use this QFile with a QFileInfo.
\sa close(), QT_USE_NODISCARD_FILE_OPEN
*/
bool QFile::open(int fd, OpenMode mode, FileHandleFlags handleFlags)
{
Q_D(QFile);
if (isOpen())
return file_already_open(*this);
// Either Append or NewOnly implies WriteOnly
if (mode & (Append | NewOnly))
mode |= WriteOnly;
unsetError();
if ((mode & (ReadOnly | WriteOnly)) == 0) {
qWarning("QFile::open: File access not specified");
return false;
}
// QIODevice provides the buffering, so request unbuffered file engines
if (d->openExternalFile(mode | Unbuffered, fd, handleFlags)) {
QIODevice::open(mode);
if (!(mode & Append) && !isSequential()) {
qint64 pos = (qint64)QT_LSEEK(fd, QT_OFF_T(0), SEEK_CUR);
if (pos != -1) {
// Skip redundant checks in QFileDevice::seek().
QIODevice::seek(pos);
}
}
return true;
}
return false;
}
/*!
\reimp
*/
bool QFile::resize(qint64 sz)
{
return QFileDevice::resize(sz); // for now
}
/*!
\overload
Sets \a fileName to size (in bytes) \a sz. Returns \c true if
the resize succeeds; false otherwise. If \a sz is larger than \a
fileName currently is the new bytes will be set to 0, if \a sz is
smaller the file is simply truncated.
\warning This function can fail if the file doesn't exist.
\sa resize()
*/
bool
QFile::resize(const QString &fileName, qint64 sz)
{
return QFile(fileName).resize(sz);
}
/*!
\reimp
*/
QFile::Permissions QFile::permissions() const
{
return QFileDevice::permissions(); // for now
}
/*!
\overload
Returns the complete OR-ed together combination of
QFile::Permission for \a fileName.
*/
QFile::Permissions
QFile::permissions(const QString &fileName)
{
return QFile(fileName).permissions();
}
/*!
Sets the permissions for the file to the \a permissions specified.
Returns \c true if successful, or \c false if the permissions cannot be
modified.
\warning This function does not manipulate ACLs, which may limit its
effectiveness.
\sa permissions(), setFileName()
*/
bool QFile::setPermissions(Permissions permissions)
{
return QFileDevice::setPermissions(permissions); // for now
}
/*!
\overload
Sets the permissions for \a fileName file to \a permissions.
*/
bool
QFile::setPermissions(const QString &fileName, Permissions permissions)
{
return QFile(fileName).setPermissions(permissions);
}
/*!
\reimp
*/
qint64 QFile::size() const
{
return QFileDevice::size(); // for now
}
/*!
\fn QFile::QFile(const std::filesystem::path &name)
\since 6.0
Constructs a new file object to represent the file with the given \a name.
\include qfile.cpp qfile-explicit-constructor-note
*/
/*!
\fn QFile::QFile(const std::filesystem::path &name, QObject *parent)
\since 6.0
Constructs a new file object with the given \a parent to represent the
file with the specified \a name.
*/
/*!
\fn std::filesystem::path QFile::filesystemFileName() const
\since 6.0
Returns fileName() as \c{std::filesystem::path}.
*/
/*!
\fn void QFile::setFileName(const std::filesystem::path &name)
\since 6.0
\overload
*/
/*!
\fn bool QFile::rename(const std::filesystem::path &newName)
\since 6.0
\overload
*/
/*!
\fn bool QFile::link(const std::filesystem::path &newName)
\since 6.0
\overload
*/
/*!
\fn bool QFile::copy(const std::filesystem::path &newName)
\since 6.0
\overload
*/
/*!
\fn QFile::Permissions QFile::permissions(const std::filesystem::path &filename)
\since 6.0
\overload
*/
/*!
\fn bool QFile::setPermissions(const std::filesystem::path &filename, Permissions permissionSpec)
\since 6.0
\overload
*/
/*!
\fn bool exists(const std::filesystem::path &fileName)
\since 6.3
\overload
*/
/*!
\fn std::filesystem::path QFile::filesystemSymLinkTarget() const
\since 6.3
Returns symLinkTarget() as \c{std::filesystem::path}.
*/
/*!
\fn std::filesystem::path QFile::filesystemSymLinkTarget(const std::filesystem::path &fileName)
\since 6.3
Returns symLinkTarget() as \c{std::filesystem::path} of \a fileName.
*/
/*!
\fn bool remove(const std::filesystem::path &fileName)
\since 6.3
\overload
*/
/*!
\fn bool moveToTrash(const std::filesystem::path &fileName, QString *pathInTrash)
\since 6.3
\overload
*/
/*!
\fn bool rename(const std::filesystem::path &oldName, const std::filesystem::path &newName)
\since 6.3
\overload
*/
/*!
\fn bool link(const std::filesystem::path &fileName, const std::filesystem::path &newName);
\since 6.3
\overload
*/
/*!
\fn bool copy(const std::filesystem::path &fileName, const std::filesystem::path &newName);
\since 6.3
\overload
*/
/*!
\class QNtfsPermissionCheckGuard
\since 6.6
\inmodule QtCore
\brief The QNtfsPermissionCheckGuard class is a RAII class to manage NTFS
permission checking.
\ingroup io
For performance reasons, QFile, QFileInfo, and related classes do not
perform full ownership and permission (ACL) checking on NTFS file systems
by default. During the lifetime of any instance of this class, that
default is overridden and advanced checking is performed. This provides
a safe and easy way to manage enabling and disabling this change to the
default behavior.
Example:
\snippet ntfsp.cpp raii
This class is available only on Windows.
\section1 qt_ntfs_permission_lookup
Prior to Qt 6.6, the user had to directly manipulate the global variable
\c qt_ntfs_permission_lookup. However, this was a non-atomic global
variable and as such it was prone to data races.
The variable \c qt_ntfs_permission_lookup is therefore deprecated since Qt
6.6.
*/
/*!
\fn QNtfsPermissionCheckGuard::QNtfsPermissionCheckGuard()
Creates a guard and calls the function qEnableNtfsPermissionChecks().
*/
/*!
\fn QNtfsPermissionCheckGuard::~QNtfsPermissionCheckGuard()
Destroys the guard and calls the function qDisableNtfsPermissionChecks().
*/
/*!
\fn bool qEnableNtfsPermissionChecks()
\since 6.6
\threadsafe
\relates QNtfsPermissionCheckGuard
Enables permission checking on NTFS file systems. Returns \c true if the check
was already enabled before the call to this function, meaning that there
are other users.
This function is only available on Windows and makes the direct
manipulation of \l qt_ntfs_permission_lookup obsolete.
This is a low-level function, please consider the RAII class
\l QNtfsPermissionCheckGuard instead.
\note The thread-safety of this function holds only as long as there are no
concurrent updates to \l qt_ntfs_permission_lookup.
*/
/*!
\fn bool qDisableNtfsPermissionChecks()
\since 6.6
\threadsafe
\relates QNtfsPermissionCheckGuard
Disables permission checking on NTFS file systems. Returns \c true if the
check is disabled, meaning that there are no more users.
This function is only available on Windows and makes the direct
manipulation of \l qt_ntfs_permission_lookup obsolete.
This is a low-level function and must (only) be called to match one earlier
call to qEnableNtfsPermissionChecks(). Please consider the RAII class
\l QNtfsPermissionCheckGuard instead.
\note The thread-safety of this function holds only as long as there are no
concurrent updates to \l qt_ntfs_permission_lookup.
*/
/*!
\fn bool qAreNtfsPermissionChecksEnabled()
\since 6.6
\threadsafe
\relates QNtfsPermissionCheckGuard
Checks the status of the permission checks on NTFS file systems. Returns
\c true if the check is enabled.
This function is only available on Windows and makes the direct
manipulation of \l qt_ntfs_permission_lookup obsolete.
\note The thread-safety of this function holds only as long as there are no
concurrent updates to \l qt_ntfs_permission_lookup.
*/
#ifndef QT_NO_DEBUG_STREAM
void QFilePrivate::writeToDebugStream(QDebug &dbg) const
{
Q_Q(const QFile);
dbg.nospace();
dbg << "QFile(" << q->fileName() << ')';
}
#endif
QT_END_NAMESPACE
#ifndef QT_NO_QOBJECT
#include "moc_qfile.cpp"
#endif