QFile Class

QFile 类提供读写文件的接口。

属性方法
Header:#include
qmake:QT += core
Inherits:QFileDevice
Inherited By:QTemporaryFile

注意: 类中所有函数都是 可重入的.

公共成员类型

类型方法
typedefDecoderFn

公共成员函数

类型方法
QFile(const QString &name, QObject *parent)
QFile(QObject *parent)
QFile(const QString &name)
QFile()
virtual~QFile()
boolcopy(const QString &newName)
boolexists() const
boollink(const QString &linkName)
boolmoveToTrash()
boolopen(FILE *fh, QIODevice::OpenMode mode, QFileDevice::FileHandleFlags handleFlags = DontCloseHandle)
boolopen(int fd, QIODevice::OpenMode mode, QFileDevice::FileHandleFlags handleFlags = DontCloseHandle)
boolremove()
boolrename(const QString &newName)
voidsetFileName(const QString &name)
QStringsymLinkTarget() const

重载公共函数

类型方法
virtual QStringfileName() const override
virtual boolopen(QIODevice::OpenMode mode) override
virtual QFileDevice::Permissionspermissions() const override
virtual boolresize(qint64 sz) override
virtual boolsetPermissions(QFileDevice::Permissions permissions) override
virtual qint64size() const override

静态公共成员

类型方法
boolcopy(const QString &fileName, const QString &newName)
QStringdecodeName(const QByteArray &localFileName)
QStringdecodeName(const char *localFileName)
QByteArrayencodeName(const QString &fileName)
boolexists(const QString &fileName)
boollink(const QString &fileName, const QString &linkName)
boolmoveToTrash(const QString &fileName, QString *pathInTrash = nullptr)
QFileDevice::Permissionspermissions(const QString &fileName)
boolremove(const QString &fileName)
boolrename(const QString &oldName, const QString &newName)
boolresize(const QString &fileName, qint64 sz)
boolsetPermissions(const QString &fileName, QFileDevice::Permissions permissions)
QStringsymLinkTarget(const QString &fileName)

详细描述

QFile 是用于读写文本及二进制的文件及资源的I/O设备。 一个QFile可以单独使用,或者更简单的,可以与 QTextStreamQDataStream 一同使用。

文件名通常在构造时传递,但也可以在随时使用 setFileName()设置。QFile 需要目录分隔符为 '/' 而不是依照操作系统。其他分隔符 (如 '\') 不受支持。

您可以通过 exists() 判断文件是否存在。(更多操作系统相关的操作在 QFileInfoQDir 中提供)

文件通过 open() 打开,通过 close() 关闭,通过 flush() 刷新。数据通常使用 QDataStream or QTextStream 读写,但您也可以使用 由 QIODevice 的继承函数 read(), readLine(), readAll(), write()。单字符的操作也可以使用 getChar(), putChar(), and ungetChar()。

size() 返回文件大小。您可以通过 pos() 获取当前文件位置,或通过 seek() 移动到新的位置(译者注:此句中的“位置”指文件内操作的字节位置)。当您读到文件结尾, atEnd() 返回 true

直接读文件

如下例子逐行地直接读取文本文件:

    QFile file("in.txt");
    if (!file.open(QIODevice::ReadOnly | QIODevice::Text))
        return;

    while (!file.atEnd()) {
        QByteArray line = file.readLine();
        process_line(line);
    }

QIODevice::Text flag传递给 open() ,其告诉Qt将Windows风格的换行符 ("\r\n") 转换为 C++风格的换行符("\n")。默认情况下,QFile 假设为二进制模式读取,不做字节转换。

通过流来读文件

如下例子逐行地通过 QTextStream 读取文本文件:

    QFile file("in.txt");
    if (!file.open(QIODevice::ReadOnly | QIODevice::Text))
        return;

    QTextStream in(&file);
    while (!in.atEnd()) {
        QString line = in.readLine();
        process_line(line);
    }

QTextStream 会特意把8位文件中字节数据转换为QString中16位UTF-16字符。默认情况下,其假设用户使用系统默认编码(例如unix平台上是UTF-8;详情参看 QTextCodec::codecForLocale() )。编码可以通过 QTextStream::setCodec() 改变。

要写入文本,您可以使用左移运算符运算符 operator<<(),在 QTextStream 中,其重载用于讲右侧内容追加的左侧,示例如下:

    QFile file("out.txt");
    if (!file.open(QIODevice::WriteOnly | QIODevice::Text))
        return;

    QTextStream out(&file);
    out << "The magic number is: " << 49 << "\n";

QDataStream 和上文很相似,详情请见相当应类的文档。

当你使用 QFile, QFileInfo 以及 QDir 来访问系统中文件,你可以使用Unicode文件名。在Unix平台,文件名会转换为8位编码。如果您想使用C++标准API (<cstdio><iostream>) 或平台相关API来访问文件而不是使用 QFile,你可以使用 encodeName() 和 decodeName() 来在Unicode文件名和8位文件名间转换。

在Unix平台,有一些特殊的系统文件 (例如 /proc 下的文件) ,对于这些文件,size() 会返回0,但你依然可以读取更多数据;这些数据在你调用 read() 时即时产生。在这种情况下,您便不能使用 atEnd() 来判断是否已经没有更多数据。(因为 atEnd() 通过文件大小是否到达结尾)。然而您可以通过连续调用 readAll(), read() 或 readLine() 指导没有数据来替代此功能。下面的例子使用 QTextStream 逐行读取/proc/modules

    QFile file("/proc/modules");
    if (!file.open(QIODevice::ReadOnly | QIODevice::Text))
        return;

    QTextStream in(&file);
    QString line = in.readLine();
    while (!line.isNull()) {
        process_line(line);
        line = in.readLine();
    }

信号

不像其他 QIODevice 的实现,例如 QTcpSocket,QFile 不会发出 aboutToClose(), bytesWritten(), 及 readyRead() 这些信号。这个实现细节意味着 QFile 不适用于读写某些特定类型的文件,比如Unix上的设备文件。

平台相关信息

文件权限和Unix和Windows上的处理并不相同。在Unix平台上,一个非 可写入 的目录,文件无法创建。但对于Windows并不一定如此,例如 'My Documents' (我的文档)目录通常不可写入,但是在其中依然可以创建文件。

Qt对于文件权限的理解有局限,尤其对于 QFile::setPermissions() 有影响。在Windows上,仅当没有任何 Write* flags被设置时,Qt 会设置旧版的只读 flag。Qt不会操作访问过滤表(access control lists , ACLs)这是的此函数在NTFS卷上基本上没什么用。对于VFAT格式的U盘,倒是有可能可用。POSIX 的 ACLs 也不会被修改。

另请参见 QTextStream, QDataStream, QFileInfo, QDir, 以及 The Qt Resource System

成员类型文档

typedef QFile::DecoderFn

这个类型定义了一个如下形式的函数的指针:

QString myDecoderFunc(const QByteArray &localFileName);

另请参见 setDecodingFunction().

Member Function Documentation

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

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

QFile::QFile(QObject *parent)

Constructs a new file object with the given parent.

QFile::QFile(const QString &name)

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

QFile::QFile()

Constructs a QFile object.

[virtual]QFile::~QFile()

Destroys the file object, closing it if necessary.

bool QFile::copy(const QString &newName)

Copies the file currently specified by fileName() to a file called newName. Returns true if successful; otherwise returns false.

Note that if a file with the name newName already exists, copy() returns false (i.e. QFile will not overwrite it).

The source file is closed before it is copied.

另请参见 setFileName().

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

This is an overloaded function.

Copies the file fileName to newName. Returns true if successful; otherwise returns false.

If a file with the name newName already exists, copy() returns false (i.e., QFile will not overwrite it).

另请参见 rename().

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

This does the reverse of QFile::encodeName() using localFileName.

另请参见 encodeName().

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

This is an overloaded function.

Returns the Unicode version of the given localFileName. See encodeName() for details.

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

Converts fileName to the local 8-bit encoding determined by the user's locale. This is sufficient for file names that the user chooses. File names hard-coded into the application should only use 7-bit ASCII filename characters.

另请参见 decodeName().

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

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

注意: If fileName is a symlink that points to a non-existing file, false is returned.

bool QFile::exists() const

This is an overloaded function.

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

另请参见 fileName() and setFileName().

[override virtual]QString QFile::fileName() const

Reimplements: QFileDevice::fileName() const.

Returns the name set by setFileName() or to the QFile constructors.

另请参见 setFileName() and QFileInfo::fileName().

bool QFile::link(const QString &linkName)

Creates a link named 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 true if successful; otherwise returns false.

This function will not overwrite an already existing entity in the file system; in this case, link() will return false and set error() to return RenameError.

注意: To create a valid link on Windows, linkName must have a .lnk file extension.

另请参见 setFileName().

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

This is an overloaded function.

Creates a link named linkName that points to the file fileName. What a link is depends on the underlying filesystem (be it a shortcut on Windows or a symbolic link on Unix). Returns true if successful; otherwise returns false.

另请参见 link().

bool QFile::moveToTrash()

Moves the file specified by fileName() to the trash. Returns true if successful, and sets the fileName() to the path at which the file can be found within the trash; otherwise returns false.

注意: 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 false.

This function was introduced in Qt 5.15.

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

This is an overloaded function.

Moves the file specified by fileName() to the trash. Returns true if successful, and sets pathInTrash (if provided) to the path at which the file can be found within the trash; otherwise returns false.

注意: On systems where the system API doesn't report the path of the file in the trash, 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.

This function was introduced in Qt 5.15.

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

Reimplements: QIODevice::open(QIODevice::OpenMode mode).

Opens the file using OpenMode mode, returning true if successful; otherwise false.

The mode must be QIODevice::ReadOnly, QIODevice::WriteOnly, or QIODevice::ReadWrite. It may also have additional flags, such as QIODevice::Text and QIODevice::Unbuffered.

注意: In WriteOnly or ReadWrite mode, if the relevant file does not already exist, this function will try to create a new file before opening it.

另请参见 QIODevice::OpenMode and setFileName().

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

This is an overloaded function.

Opens the existing file handle fh in the given mode. handleFlags may be used to specify additional options. Returns true if successful; otherwise returns false.

Example:

#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();
}

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:

  1. If fh does not refer to a regular file, 例如, it is stdin, stdout, or stderr, you may not be able to seek(). size() returns 0 in those cases. See QIODevice::isSequential() for more information.
  2. Since this function opens the file without specifying the file name, you cannot use this QFile with a QFileInfo.

Note for the Windows Platform

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

CONFIG += console

另请参见 close().

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

This is an overloaded function.

Opens the existing file descriptor fd in the given mode. handleFlags may be used to specify additional options. Returns true if successful; otherwise returns 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.

The QFile that is opened using this function is automatically set to be in raw mode; this means that the file input/output functions are slow. If you run into performance issues, you should try to use one of the other open functions.

Warning: If fd is not a regular file, e.g, it is 0 (stdin), 1 (stdout), or 2 (stderr), you may not be able to seek(). In those cases, size() returns 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.

另请参见 close().

[override virtual]QFileDevice::Permissions QFile::permissions() const

Reimplements: QFileDevice::permissions() const.

另请参见 setPermissions().

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

This is an overloaded function.

Returns the complete OR-ed together combination of QFile::Permission for fileName.

bool QFile::remove()

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

The file is closed before it is removed.

另请参见 setFileName().

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

This is an overloaded function.

Removes the file specified by the fileName given.

Returns true if successful; otherwise returns false.

另请参见 remove().

bool QFile::rename(const QString &newName)

Renames the file currently specified by fileName() to newName. Returns true if successful; otherwise returns false.

If a file with the name newName already exists, rename() returns 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 newName, and then remove this file, keeping only newName. If that copy operation fails or this file can't be removed, the destination file newName is removed to restore the old state.

另请参见 setFileName().

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

This is an overloaded function.

Renames the file oldName to newName. Returns true if successful; otherwise returns false.

If a file with the name newName already exists, rename() returns false (i.e., QFile will not overwrite it).

另请参见 rename().

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

Reimplements: QFileDevice::resize(qint64 sz).

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

This is an overloaded function.

Sets fileName to size (in bytes) sz. Returns true if the resize succeeds; false otherwise. If sz is larger than fileName currently is the new bytes will be set to 0, if sz is smaller the file is simply truncated.

Warning: This function can fail if the file doesn't exist.

另请参见 resize().

void QFile::setFileName(const QString &name)

Sets the 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 at the time of the open() call.

Example:

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

Note that the directory separator "/" works for all operating systems supported by Qt.

另请参见 fileName(), QFileInfo, and QDir.

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

Reimplements: QFileDevice::setPermissions(QFileDevice::Permissions permissions).

Sets the permissions for the file to the permissions specified. Returns true if successful, or false if the permissions cannot be modified.

Warning: This function does not manipulate ACLs, which may limit its effectiveness.

另请参见 permissions() and setFileName().

[static]bool QFile::setPermissions(const QString &fileName, QFileDevice::Permissionspermissions)

This is an overloaded function.

Sets the permissions for fileName file to permissions.

[override virtual]qint64 QFile::size() const

Reimplements: QFileDevice::size() const.

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

Returns the absolute path of the file or directory referred to by the symlink (or shortcut on Windows) specified by fileName, or returns an empty string if the fileName does not correspond to a symbolic link.

This name may not represent an existing file; it is only a string. QFile::exists() returns true if the symlink points to an existing file.

This function was introduced in Qt 4.2.

QString QFile::symLinkTarget() const

This is an overloaded function.

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 true if the symlink points to an existing file.

This function was introduced in Qt 4.2.

另请参见 fileName() and setFileName().