qfile.cpp

Go to the documentation of this file.

// 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