QFile 类

成员函数文档

QFile::QFile()

构造一个QFile对象。

QFile::QFile(const QString &name)

构造一个新的文件对象来表示给定名称的文件。

[since 6.0]QFile::QFile(const std::filesystem::path &name)

构造一个新的文件对象来表示给定名称的文件。

此函数是在Qt 6.0中引入的。

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

使用给定的parent构造一个新的文件对象。

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

构造一个新的文件对象，该对象使用指定的parent表示具有指定名称的文件。

[since 6.0]QFile::QFile(const std::filesystem::path &name, QObject *parent)

构造一个新的文件对象，该对象使用指定的parent表示具有指定名称的文件。

此函数是在Qt 6.0中引入的。

[virtual noexcept]QFile::~QFile()

销毁文件对象，如果需要则关闭它。

bool QFile::copy(const QString &newName)

将fileName()命名的文件复制到newName。

在复制之前，将关闭此文件。

如果复制的文件是符号链接（symlink），则复制的不是链接本身，而是它所指向的文件。除了权限外，不会复制其他文件元数据。

如果成功则返回 true，否则返回 false。

请注意，如果存在同名文件 newName，copy() 返回 false。这意味着 QFile 不会覆盖它。

另请参阅：setFileName()

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

这是一个重载函数。

将名为 fileName 的文件复制到 newName。

在复制之前，将关闭此文件。

如果复制的文件是符号链接（symlink），则复制的不是链接本身，而是它所指向的文件。除了权限外，不会复制其他文件元数据。

如果成功则返回 true，否则返回 false。

请注意，如果存在同名文件 newName，copy() 返回 false。这意味着 QFile 不会覆盖它。

另请参阅：rename()

[自 6.0 开始] bool QFile::copy(const std::filesystem::path &newName)

这是一个重载函数。

此函数是在Qt 6.0中引入的。

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

使用 localFileName 来执行与 QFile::encodeName() 相反的操作。

另请参阅：encodeName()

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

这是一个重载函数。

返回给定 localFileName 的 Unicode 版本。有关详细信息，请参阅 encodeName()。

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

将 fileName 转换为可用于本机 API 的 8 位编码。在 Windows 上，这是活动 Windows (ANSI) 的代码页编码。在其他平台，这是 UTF-8，在 macOS 上以分解形式（NFD）使用。

另请参阅：decodeName()

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

如果由 fileName 指定的文件存在，则返回 true；否则返回 false。

bool QFile::exists() const

这是一个重载函数。

返回 true，如果由 fileName() 指定的文件存在；否则返回 false。

另请参阅：fileName() 和 setFileName()

[重载虚拟] QString QFile::fileName() const

重新实现: QFileDevice::fileName() const

返回由 setFileName() 设置的名称，或返回 QFile 构造函数设置的名称。

另请参阅 setFileName() 以及 QFileInfo::fileName().

[自 6.0 起存在] std::filesystem::path QFile::filesystemFileName() const

返回fileName() 的 std::filesystem::path。

此函数是在Qt 6.0中引入的。

[自 6.3 起存在] std::filesystem::path QFile::filesystemSymLinkTarget() const

返回symLinkTarget() 的 std::filesystem::path。

此功能自 Qt 6.3 中引入。

[静态，自 6.3 起存在] std::filesystem::path QFile::filesystemSymLinkTarget(const std::filesystem::path &fileName)

返回 fileName 对应的 symLinkTarget() 的 std::filesystem::path。

此功能自 Qt 6.3 中引入。

bool QFile::link(const QString &linkName)

创建一个名为 linkName 的链接，该链接指向由 fileName() 指定的文件。链接的形态取决于底层文件系统（无论是 Windows 上的快捷方式还是 Unix 上的符号链接）。如果成功，则返回 true；否则返回 false。

此函数不会覆盖文件系统中已经存在的实体；在这种情况下，link() 将返回 false 并将 error() 设置为返回 RenameError。

另请参阅：setFileName()

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

这是一个重载函数。

创建一个名为 linkName 的链接，该链接指向文件 fileName。链接的形态取决于底层文件系统（无论是 Windows 上的快捷方式还是 Unix 上的符号链接）。如果成功，则返回 true；否则返回 false。

另请参阅 link().

[自 6.0 起存在] bool QFile::link(const std::filesystem::path &newName)

这是一个重载函数。

此函数是在Qt 6.0中引入的。

bool QFile::moveToTrash()

将 fileName() 指定的文件移动到回收站。如果成功，则返回 true，并将 fileName() 设置为可以在回收站中找到该文件的路径；否则返回 false。

此函数运行的时间与被丢弃的文件的大小无关。如果对目录调用此函数，则可能与其中的文件数量成正比。

此函数使用 Windows 和 macOS API 在这两个操作系统上执行丢弃操作。在其他地方（Unix 系统上），此函数实现了 FreeDesktop.org 丢弃规范版本 1.0。

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

这是一个重载函数。

将由fileName指定的文件移动到垃圾桶。如果成功，则返回true，并将pathInTrash（如果提供）设置为在垃圾桶中可找到文件的路径；否则返回false。

此函数运行的时间与被丢弃的文件的大小无关。如果对目录调用此函数，则可能与其中的文件数量成正比。

此函数使用 Windows 和 macOS API 在这两个操作系统上执行丢弃操作。在其他地方（Unix 系统上），此函数实现了 FreeDesktop.org 丢弃规范版本 1.0。

[重载虚拟] bool QFile::open(QIODeviceBase::OpenMode mode)

重新实现：QIODevice::open(QIODeviceBase::OpenMode模式)。

使用OpenMode mode 打开文件，如果成功则返回true；否则返回false。

模式的必须为QIODevice::ReadOnly、QIODevice::WriteOnly 或 QIODevice::ReadWrite。它还可以有额外的标志，例如 QIODevice::Text 和 QIODevice::Unbuffered。

另请参阅 QIODevice::OpenMode 和 setFileName。

[自6.3以来] bool QFile::open(QIODeviceBase::OpenMode mode, QFileDevice::Permissions permissions)

这是一个重载函数。

如果文件不存在，并且mode表示创建它，则使用指定的permissions创建。

在POSIX系统上，实际权限受umask的值影响。

在Windows上，使用ACLs来模拟权限。当组被授予比其他组更少的权限时，这些ACLs可能是非规范顺序的。具有此类权限的文件和目录在打开属性对话框的安全选项卡时将生成警告。将组授予所有其他组授予的权限可以避免此类警告。

此功能自 Qt 6.3 中引入。

另请参阅 QIODevice::OpenMode 和 setFileName。

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

这是一个重载函数。

以指定模式打开现有的文件句柄fh。可以使用handleFlags指定额外选项。如果成功返回true；否则返回false。

示例

#include <stdio.h>

void printError(const char* msg)
{
    QFile file;
    file.open(stderr, QIODevice::WriteOnly);
    file.write(msg, qstrlen(msg));        // write to stderr
    file.close();
}

当使用此函数通过QFile打开文件时，close()的行为由AutoCloseHandle标志控制。如果指定了AutoCloseHandle，并且此函数成功，则调用close()将关闭已采用的句柄。否则，close()实际上不会关闭文件，而只是刷新它。

警告

1. 如果fh不指向常规文件，例如，它是stdin、stdout或stderr，则可能无法seek()。在这种情况下，size()返回0。有关更多信息，请参阅QIODevice::isSequential()。
2. 注意，由于此函数在打开文件时不指定文件名，因此您不能使用此QFile与QFileInfo一起使用。

Windows平台注意事项

fh在访问文件和其他随机访问设备时必须以二进制模式打开（即模式字符串必须包含'b'，如"rb"或"wb"）。如果将QIODevice::Text传递给mode，Qt会将换行符字符进行转换。此限制不影响诸如stdin和stdout之类的顺序设备。

您需要启用控制台应用程序的支持才能在控制台中使用stdin、stdout和stderr流。为此，请在您的应用程序项目文件中添加以下声明：

CONFIG += console

另请参阅 close。

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

这是一个重载函数。

以指定模式打开现有的文件描述符fd。可以使用handleFlags指定额外选项。如果成功返回true；否则返回false。

当使用此函数通过QFile打开文件时，close()的行为由AutoCloseHandle标志控制。如果指定了AutoCloseHandle，并且此函数成功，则调用close()将关闭已采用的句柄。否则，close()实际上不会关闭文件，而只是刷新它。

另请参阅 close。

[覆盖虚函数] QFileDevice::Permissions QFile::permissions() const

重新实现： QFileDevice::permissions() const。

另请参阅 setPermissions。

[静态] QFileDevice::Permissions QFile::permissions(const QString &fileName)

这是一个重载函数。

返回fileName的QFile::Permission的完整OR组合。

[静态，自6.0以来] QFileDevice::Permissions QFile::permissions(const std::filesystem::path &filename)

这是一个重载函数。

此函数是在Qt 6.0中引入的。

bool QFile::remove()

删除由 fileName() 指定的文件。如果成功，则返回 true；否则返回 false。

删除文件之前将关闭文件。

另请参阅：setFileName()

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

这是一个重载函数。

删除提供的 fileName 指定的文件。

如果成功则返回 true，否则返回 false。

另请参阅 remove()。

bool QFile::rename(const QString &newName)

将当前由 fileName() 指定的文件重命名为 newName。如果成功，则返回 true；否则返回 false。

如果已存在名为 newName 的文件，rename() 返回 false（即，QFile 不会覆盖它）。

重命名文件之前将关闭文件。

如果重命名操作失败，Qt 将尝试将此文件的内容复制到 newName，然后删除此文件，只保留 newName。如果复制操作失败或无法删除此文件，则删除目标文件 newName 以恢复旧状态。

另请参阅：setFileName()

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

这是一个重载函数。

将文件 oldName 重命名为 newName。如果成功，则返回 true；否则返回 false。

如果已存在名为 newName 的文件，rename() 返回 false（即，QFile 不会覆盖它）。

另请参阅：rename()

[since 6.0] bool QFile::rename(const std::filesystem::path &newName)

这是一个重载函数。

此函数是在Qt 6.0中引入的。

[override virtual] bool QFile::resize(qint64 sz)

重新实现: QFileDevice::resize(qint64 sz).

[static] bool QFile::resize(const QString &fileName, qint64 sz)

这是一个重载函数。

将 fileName 设置为（以字节为单位）sz 的大小。如果调整大小成功，则返回 true；否则返回 false。如果 sz 大于 fileName 当前的尺寸，则新字节将设置为 0；如果 sz 较小，则文件将被简单地截断。

另请参阅 resize()。

void QFile::setFileName(const QString &name)

设置文件的 name。名称可以没有路径，相对路径或绝对路径。

不要在文件已打开时调用此函数。

如果文件名没有路径或相对路径，则使用的路径将在 open() 调用时 at the time of the 应用程序当前目录路径。

示例

QFile file;
QDir::setCurrent("/tmp");
file.setFileName("readme.txt");
QDir::setCurrent("/home");
file.open(QIODevice::ReadOnly);      // opens "/home/readme.txt" under Unix

请注意，在 Qt 支持的所有操作系统上 "/" 做为目录分隔符都适用。

另请参阅 fileName()，QFileInfo 和 QDir。

[自 6.0 版本以来] void QFile::setFileName(const std::filesystem::path &name)

这是一个重载函数。

此函数是在Qt 6.0中引入的。

[重载虚函数] bool QFile::setPermissions(QFileDevice::Permissions permissions)

重写: QFileDevice::setPermissions(QFileDevice::Permissions permissions).

将文件的权限设置为目标指定的 permissions。如果成功，返回 true，如果权限无法修改，返回 false。

另请参阅 permissions() 和 setFileName()。

[静态] bool QFile::setPermissions(const QString &fileName, QFileDevice::Permissions permissions)

这是一个重载函数。

将 fileName 文件的权限设置为目标指定的 permissions。

[静态，自 6.0 版本以来] bool QFile::setPermissions(const std::filesystem::path &filename, QFileDevice::Permissions permissionSpec)

这是一个重载函数。

此函数是在Qt 6.0中引入的。

[重载虚函数] qint64 QFile::size() const

重写: QFileDevice::size() const.

[静态] QString QFile::symLinkTarget(const QString &fileName)

返回由 fileName 指定的符号链接（或 Windows 上的快捷方式）引用的文件或目录的绝对路径，或者如果 fileName 不对应符号链接，则返回空字符串。

此名称可能不代表一个存在的文件；它只是一个字符串。如果符号链接指向一个存在的文件，则 QFile::exists() 返回 true。

返回一个符号链接（或 Windows 上的快捷方式）指向的文件或目录的绝对路径，或者如果对象不是符号链接，则返回一个空字符串。

这是一个重载函数。

返回一个符号链接（或 Windows 上的快捷方式）指向的文件或目录的绝对路径，或者如果对象不是符号链接，则返回一个空字符串。

此名称可能不代表一个存在的文件；它只是一个字符串。如果符号链接指向一个存在的文件，则 QFile::exists() 返回 true。

另请参阅：fileName() 和 setFileName()