内容

• 公共类型
• 公共函数
• 重实现公共函数
• 静态公共成员
• 详细描述
• 直接读取文件
• 使用流读取文件
• 信号
• 平台具体问题

QFile 类

The QFile class provides an interface for reading from and writing to files. 更多...

头：	#include <QFile>
qmake:	QT += core
继承：	QFileDevice
继承者：	QTemporaryFile

• 所有成员列表，包括继承成员
• 过时成员

注意： 此类的所有函数 可重入 .

公共类型

typedef

DecoderFn

公共函数

	QFile ()
	QFile (const QString & name )
	QFile (QObject * parent )
	QFile (const QString & name , QObject * parent )
	~QFile ()
bool	copy (const QString & newName )
bool	exists () const
bool	link (const QString & linkName )
bool	open (FILE * fh , OpenMode mode , FileHandleFlags handleFlags = DontCloseHandle)
bool	open (int fd , OpenMode mode , FileHandleFlags handleFlags = DontCloseHandle)
bool	remove ()
bool	rename (const QString & newName )
void	setFileName (const QString & name )
QString	symLinkTarget () const

重实现公共函数

virtual QString	fileName () const
virtual bool	open (OpenMode mode )
virtual Permissions	permissions () const
virtual bool	resize (qint64 sz )
virtual bool	setPermissions (Permissions permissions )
virtual qint64	size () const

• 16 public functions inherited from QFileDevice
• 43 公共函数继承自 QIODevice
• 32 公共函数继承自 QObject

静态公共成员

bool	copy (const QString & fileName , const QString & newName )
QString	decodeName (const QByteArray & localFileName )
QString	decodeName (const char * localFileName )
QByteArray	encodeName (const QString & fileName )
bool	exists (const QString & fileName )
bool	link (const QString & fileName , const QString & linkName )
权限	permissions (const QString & fileName )
bool	remove (const QString & fileName )
bool	rename (const QString & oldName , const QString & newName )
bool	resize (const QString & fileName , qint64 sz )
bool	setPermissions (const QString & fileName , Permissions permissions )
QString	symLinkTarget (const QString & fileName )

• 11 静态公共成员继承自 QObject

额外继承成员

• 1 特性继承自 QObject
• 1 公共槽继承自 QObject
• 6 信号继承自 QIODevice
• 2 信号继承自 QObject
• 3 保护函数继承自 QFileDevice
• 5 保护函数继承自 QIODevice
• 9 保护函数继承自 QObject

详细描述

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

QFile is an I/O device for reading and writing text and binary files and resources 。 QFile 可以单独使用，或更方便一起使用与 QTextStream or QDataStream .

通常在构造函数中传递文件名，但可以随时设置它使用 setFileName (). QFile expects the file separator to be '/' regardless of operating system. The use of other separators (e.g., '\') is not supported.

可以检查文件是否存在使用 exists ()，和移除文件使用 remove ()。(更高级的文件系统相关操作的提供由 QFileInfo and QDir )。

打开文件采用 open ()，关闭采用 close ()，和刷新采用 flush ()。数据的读写通常是使用 QDataStream or QTextStream ，但也可以调用 QIODevice 继承函数 read (), readLine (), readAll (), write (). QFile 还继承 getChar (), putChar ()，和 ungetChar ()，每次操控一字符。

文件大小的返回是通过 size ()。可以获取当前文件位置使用 pos ()，或移至新文件位置使用 seek ()。若已到达 EOF (文件末尾)， atEnd () 返回 true .

直接读取文件

以下范例逐行读取文本文件：

    QFile file("in.txt");
    if (!file.open(QIODevice::ReadOnly | QIODevice::Text))
        return;
    while (!file.atEnd()) {
        QByteArray line = file.readLine();
        process_line(line);
    }
					

The QIODevice::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.

使用流读取文件

下一范例使用 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 位数据转换成 16 位 Unicode QString . By default, it assumes that the user system's local 8-bit encoding is used (e.g., UTF-8 on most unix based operating systems; see QTextCodec::codecForLocale () for details). This can be changed using QTextStream::setCodec ().

要写入文本，可以使用操作符 <<()，重载以接受 QTextStream 在左侧和各种数据类型 (包括 QString ) 在右侧：

    QFile file("out.txt");
    if (!file.open(QIODevice::WriteOnly | QIODevice::Text))
        return;
    QTextStream out(&file);
    out << "The magic number is: " << 49 << "\n";
					

QDataStream 类似，可以使用操作符 <<() 写入数据，和使用操作符 >>() 读回它。见类文档编制，了解细节。

When you use QFile , QFileInfo ，和 QDir to access the file system with Qt, you can use Unicode file names. On Unix, these file names are converted to an 8-bit encoding. If you want to use standard C++ APIs ( <cstdio> or <iostream> ) or platform-specific APIs to access files instead of QFile , you can use the encodeName () 和 decodeName () functions to convert between Unicode file names and 8-bit file names.

在 Unix，有一些特殊系统文件 (如在 /proc ) 其中 size () 将始终返回 0，仍然可以从这种文件读取更多数据；直接生成数据是为响应调用 read ()。在此情况下，不管怎样，不可以使用 atEnd () 以确定是否有更多数据要读取 (由于 atEnd () 将返回 true 对于声明拥有大小 0 的文件)。相反，应该调用 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 does not emit the aboutToClose (), bytesWritten ()，或 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.

平台具体问题

文件权限的处理是不同的，在像 Unix 系统和 Windows。在非 writable 目录像 Unix 系统，无法创建文件。在 Windows 并不始终如此，例如，"我的文档" 目录通常不可写，但可以在其中创建文件仍然是可能的。

Qt 对文件权限的理解是有限的，这尤其影响 QFile::setPermissions () 函数。在 Windows，Qt 将只设置遗留只读标志，且仅当未传递 Write* 标志时。Qt 不操纵 ACL (访问控制列表)，这使得此函数对 NTFS 卷几乎无用。它仍然可以用于使用 VFAT 文件系统的 U 盘。也不操纵 POSIX ACL。

另请参阅 QTextStream , QDataStream , QFileInfo , QDir ，和 Qt 资源系统 .

成员类型文档编制

typedef QFile:: DecoderFn

这是采用以下签名的函数指针的 typedef：

QString myDecoderFunc(const QByteArray &localFileName);
					

另请参阅 setDecodingFunction ().

成员函数文档编制

QFile:: QFile ()

构造 QFile 对象。

QFile:: QFile (const QString & name )

构造新文件对象以表示文件采用给定 name .

QFile:: QFile ( QObject * parent )

构造新文件对象采用给定 parent .

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

构造新文件对象采用给定 parent 表示文件采用指定 name .

QFile:: ~QFile ()

销毁文件对象，关闭它若有必要。

bool QFile:: copy (const QString & newName )

拷贝目前指定的文件通过 fileName () 到文件称为 newName 。返回 true 若成功；否则返回 false .

注意：若文件采用名称 newName 已存在，copy() 返回 false (即 QFile 不会覆写它)。

关闭源文件在拷贝它之前。

另请参阅 setFileName ().

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

这是重载函数。

拷贝文件 fileName to newName 。返回 true 若成功；否则返回 false .

若文件采用名称 newName already exists, copy () 返回 false (即， QFile 不会覆写它)。

另请参阅 rename ().

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

这做反向 QFile::encodeName () 使用 localFileName .

另请参阅 encodeName ().

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

这是重载函数。

返回 Unicode 版本为给定 localFileName 。见 encodeName () 了解细节。

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

转换 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 )

返回 true 若文件指定通过 fileName 存在；否则返回 false .

注意： 若 fileName 是指向不存在文件的符号链接，返回 false。

bool QFile:: exists () const

这是重载函数。

返回 true 若文件指定通过 fileName () 存在；否则返回 false .

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

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

重实现自 QFileDevice::fileName ().

返回名称设置通过 setFileName () 或到 QFile 构造函数。

另请参阅 setFileName () 和 QFileInfo::fileName ().

bool QFile:: link (const QString & linkName )

创建链接命名 linkName 指向文件目前指定通过 fileName ()。链接是什么从属底层文件系统 (不管是 Windows 快捷方式，还是 Unix 符号链接)。返回 true 若成功；否则返回 false .

此函数不会覆写文件系统中已存在的实体；在此情况下， link() 将返回 false 并设置 error() to return RenameError .

注意： 要在 Windows 创建有效链接， linkName 必须拥有 .lnk 文件扩展名。

另请参阅 setFileName ().

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

这是重载函数。

创建链接命名 linkName 指向文件 fileName 。链接是什么从属底层文件系统 (不管是 Windows 快捷方式，还是 Unix 符号链接)。返回 true 若成功；否则返回 false .

另请参阅 link ().

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

重实现自 QIODevice::open ().

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

The mode 必须为 QIODevice::ReadOnly , QIODevice::WriteOnly ，或 QIODevice::ReadWrite 。它还可以拥有额外标志，譬如 QIODevice::Text and QIODevice::Unbuffered .

注意： 在 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 , OpenMode mode , FileHandleFlags handleFlags = DontCloseHandle)

这是重载函数。

打开现有文件句柄 fh 以给定 mode . 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 () is controlled by the AutoCloseHandle flag. If AutoCloseHandle is specified, and this function succeeds, then calling close () 会关闭采纳句柄。否则， close () 不会实际关闭文件，而仅刷新它。

警告：

1. 若 fh 不是指常规文件，如，它是 stdin , stdout ，或 stderr ，可能无法 seek (). size () 返回 0 在此情况下。见 QIODevice::isSequential () 了解更多信息。
2. 由于此函数打开文件不用指定文件名，所以，无法使用此 QFile 采用 QFileInfo .

Windows 平台注意事项

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 。顺序设备 (譬如：stdin 和 stdout) 不受此局限性的影响。

需要启用对控制台应用程序的支持，为在控制台使用 stdin (标准输入)、stdout (标准输出) 及 stderr (标准错误) 流。要做到这，把以下声明添加到应用程序工程文件：

CONFIG += console
					

另请参阅 close ().

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

这是重载函数。

打开现有文件描述符 fd 以给定 mode . handleFlags 可以用于指定额外选项。返回 true 若成功；否则返回 false .

当 QFile 是使用此函数打开的，行为对于 close () is controlled by the AutoCloseHandle flag. If AutoCloseHandle is specified, and this function succeeds, then calling close () 会关闭采纳句柄。否则， close () 不会实际关闭文件，而仅刷新它。

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.

警告： 若 fd 不是常规文件，如为 0 ( stdin ), 1 ( stdout )，或 2 ( stderr )，可能无法 seek ()。在此情况下， size () 返回 0 。见 QIODevice::isSequential () 了解更多信息。

警告： 由于此函数打开文件不用指定文件名，所以，无法使用此 QFile 采用 QFileInfo .

另请参阅 close ().

[虚拟] Permissions QFile:: permissions () const

重实现自 QFileDevice::permissions ().

另请参阅 setPermissions ().

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

这是重载函数。

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

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 to newName 。返回 true 若成功；否则返回 false .

若文件采用名称 newName already exists, rename () 返回 false (即， QFile 不会覆写它)。

另请参阅 rename ().

[虚拟] bool QFile:: resize ( qint64 sz )

重实现自 QFileDevice::resize ().

[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 () 调用。

范例：

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 .

[虚拟] bool QFile:: setPermissions ( Permissions permissions )

重实现自 QFileDevice::setPermissions ().

将文件权限设为 permissions 指定。返回 true 若成功，或 false 若权限不能被修改。

警告： 此函数不操纵 ACL (访问控制列表)，这可能限制其有效性。

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

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

这是重载函数。

设置权限为 fileName 文件到 permissions .

[虚拟] qint64 QFile:: size () const

重实现自 QIODevice::size ().

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

返回符号链接 (或 Windows 快捷方式) 引用文件 (或目录) 的绝对路径指定通过 fileName ，或返回空字符串若 fileName 不对应于符号链接。

此名称可能不表示现有文件；它只是字符串。 QFile::exists () 返回 true 若符号链接指向现有文件。

该函数在 Qt 4.2 引入。

QString QFile:: symLinkTarget () const

这是重载函数。

返回符号链接 (或 Windows 快捷方式) 指向文件 (或目录) 的绝对路径，或空字符串若对象不是符号链接。

此名称可能不表示现有文件；它只是字符串。 QFile::exists () 返回 true 若符号链接指向现有文件。

该函数在 Qt 4.2 引入。

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