QFile Class

メンバ関数のドキュメント

QFile::QFile()

QFile オブジェクトを生成します。

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

指定されたparent を使用して、新しいファイルオブジェクトを作成します。

[explicit] QFile::QFile(const QString &name)

指定されたname を持つファイルを表す新しいファイルオブジェクトを生成します。

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

指定されたname を持つファイルを表す新しいファイルオブジェクトを構築します。

この関数は Qt 6.0 で導入されました。

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

指定されたparent を使用して、指定されたname を持つファイルを表す新しいファイルオブジェクトを作成します。

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

指定されたparent を使用して、指定されたname を持つファイルを表す新しいファイルオブジェクトを作成します。

この関数は Qt 6.0 で導入されました。

[virtual noexcept] QFile::~QFile()

ファイルオブジェクトを破棄し、必要に応じてファイルを閉じます。

bool QFile::copy(const QString &newName, std::optional<QFileDevice::Permissions> perm = std::nullopt)

fileName() という名前のファイルをnewName にコピーします。

このファイルは、コピーされる前に閉じられます。

Qt 6.12 以降、呼び出し時に権限perm を指定できるようになりました。指定されない場合は、元のファイルの権限がコピーされます。新しいファイルは、指定された権限で作成されます。

コピーされるファイルがシンボリックリンク (symlink) の場合、リンク自体ではなく、そのリンクが指すファイルがコピーされます。権限を除き、その他のファイルメタデータはコピーされません。

成功した場合は `true ` を返し、失敗した場合は `false` を返します。

なお、newName という名前のファイルがすでに存在する場合、copy()はfalse を返します。これは、QFile がそのファイルを上書きしないことを意味します。ただし、この操作はアトミックではありません。チェックとコピーの間に、別のプロセスがnewName という名前のファイルを作成する可能性があります。その場合、ファイルは上書きされます。

setFileName()も参照してください 。

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

この関数は Qt 6.0 で導入されました。

[static] bool QFile::copy(const QString &fileName, const QString &newName, std::optional<QFileDevice::Permissions> perm = std::nullopt)

fileName という名前のファイルをnewName にコピーします。

Qt 6.12 以降、呼び出し時にperm の権限を指定できるようになりました。指定されない場合は、元のファイルの権限がコピーされます。新しいファイルは、指定された権限で作成されます。

コピー先のファイルがシンボリックリンク（symlink）である場合、リンク自体ではなく、そのリンクが指すファイルがコピーされます。権限を除き、その他のファイルメタデータはコピーされません。

成功した場合は `true ` を返し、失敗した場合は `false` を返します。

なお、newName という名前のファイルがすでに存在する場合、copy()はfalse を返します。これは、QFile がそのファイルを上書きしないことを意味します。ただし、この操作は原子的ではありません。チェックとコピーの間に、別のプロセスがnewName という名前のファイルを作成する可能性があります。その場合、ファイルは上書きされます。

rename()も参照してください 。

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

これは、localFileName を使用して、QFile::encodeName() の逆の処理を行います。

encodeName()も参照してください 。

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

指定されたlocalFileName のUnicodeバージョンを返します。詳細については、encodeName()を参照してください。

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

fileName を、ネイティブAPIで使用可能な8ビットエンコーディングに変換します。Windowsでは、アクティブなWindows（ANSI）コードページに基づくエンコーディングが使用されます。その他のプラットフォームではUTF-8が使用され、macOSでは分解形式（NFD）で処理されます。

decodeName()も参照してください 。

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

fileName で指定されたファイルが存在する場合、true を返します。存在しない場合は、false を返します。

bool QFile::exists() const

fileName() で指定されたファイルが存在する場合、true を返します。存在しない場合は、false を返します。

fileName() およびsetFileName()も参照してください 。

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

QFileDevice::fileName() const を再実装します。

setFileName()、rename()、またはQFile のコンストラクタによって設定されたファイル名を返します。

setFileName()、rename()、およびQFileInfo::fileName()も参照してください 。

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

fileName() をstd::filesystem::path として返します。

この関数は Qt 6.0 で導入されました。

[since 6.3] std::filesystem::path QFile::filesystemSymLinkTarget() const

symLinkTarget() を、std::filesystem::path として返します。

この関数は Qt 6.3 で導入されました。

[static, since 6.3] std::filesystem::path QFile::filesystemSymLinkTarget(const std::filesystem::path &fileName)

fileName のstd::filesystem::path としてsymLinkTarget()を返します。

この関数は Qt 6.3 で導入されました。

bool QFile::link(const QString &linkName)

linkName という名前のリンクを作成し、fileName() で現在指定されているファイルを指すようにします。リンクの具体的な形式は、基盤となるファイルシステムによって異なります（Windows ではショートカット、Unix ではシンボリックリンクなど）。成功した場合はtrue を返し、そうでない場合はfalse を返します。

この関数は、ファイルシステム上にすでに存在するエンティティを上書きすることはありません。その場合、link() はfalseを返し、error()がRenameError を返すように設定されます。

関連項目： setFileName()。

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

この関数は Qt 6.0 で導入されました。

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

linkName という名前のリンクを作成し、fileName というファイルを指すようにします。リンクの具体的な形式は、基盤となるファイルシステムによって異なります（Windows ではショートカット、Unix ではシンボリックリンクなど）。成功した場合はtrue を返し、失敗した場合はfalse を返します。

link()も参照してください 。

bool QFile::moveToTrash()

fileName() で指定されたファイルをゴミ箱に移動します。成功した場合はtrue を返し、fileName() を、ゴミ箱内のそのファイルのパスに設定します。失敗した場合はfalse を返します。

この関数の実行時間は、ゴミ箱に移動されるファイルのサイズには依存しません。ディレクトリに対してこの関数が呼び出された場合、実行時間はゴミ箱に移動されるファイルの数に比例する可能性があります。現在のfileName()がシンボリックリンクを指している場合、この関数はリンク自体をゴミ箱に移動します（これによりリンクが破損する可能性があります）。リンク先のファイルは移動されません。

この関数は、Windows および macOS では、それぞれのオペレーティングシステムの API を使用してゴミ箱への移動を行います。それ以外の環境（Unix 系システム）では、この関数はFreeDesktop.org Trash 仕様バージョン 1.0 を実装しています。

supportsMoveToTrash()、remove()、およびQDir::remove()も参照してください 。

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

fileName で指定されたファイルをゴミ箱に移動します。成功した場合はtrue を返し、pathInTrash （指定されている場合）を、ゴミ箱内のファイルの保存パスに設定します。それ以外の場合はfalse を返します。

この関数の実行時間は、ゴミ箱に移動されるファイルのサイズとは無関係です。ディレクトリに対してこの関数が呼び出された場合、実行時間はゴミ箱に移動されるファイルの数に比例する可能性があります。現在のfileName() がシンボリックリンクを指している場合、この関数はリンク自体をゴミ箱に移動し（これによりリンクが破損する可能性があります）、リンク先のファイルは移動しません。

この関数は、Windows および macOS では、それぞれのオペレーティングシステムの API を使用してゴミ箱への移動を行います。それ以外の環境（Unix 系システム）では、この関数はFreeDesktop.org Trash 仕様バージョン 1.0 を実装しています。

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

QIODevice::open （QIODeviceBase::OpenMode mode）を再実装します。

mode フラグを使用してファイルを開き、成功した場合は `true ` を返し、失敗した場合は `false` を返します。

mode のフラグには、QIODeviceBase::ReadOnly 、WriteOnly 、またはReadWrite を含める必要があります。また、Text やUnbuffered などの追加のフラグを含めることもできます。

QT_USE_NODISCARD_FILE_OPEN およびsetFileName()も参照してください 。

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

ファイルが存在せず、mode によってその作成が必要となる場合、指定されたpermissions でファイルが作成されます。

POSIX システムでは、実際の権限はumask の値によって影響を受けます。

Windows では、権限は ACL を使用してエミュレートされます。グループに他のユーザーよりも少ない権限が付与されている場合、これらの ACL の順序は標準的な順序とは異なる場合があります。このような権限が設定されたファイルやディレクトリについては、「プロパティ」ダイアログの [セキュリティ] タブを開いた際に警告が表示されます。グループに他のユーザーに付与されているすべての権限を付与することで、このような警告を回避できます。

この関数は Qt 6.3 で導入されました。

QIODevice::OpenMode 、setFileName()、およびQT_USE_NODISCARD_FILE_OPENも参照してください 。

bool QFile::open(FILE *fh, QIODeviceBase::OpenMode mode, QFileDevice::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()の動作はAutoCloseHandleフラグによって制御されます。AutoCloseHandleが指定されており、この関数が成功した場合、close()を呼び出すと、そのハンドルが閉じられます。そうでない場合、close()はファイルを実際に閉じるのではなく、単にフラッシュするだけです。

警告:

1. fh が通常のファイルを指していない場合（例：stdin 、stdout 、またはstderr など）、seek()を実行できない可能性があります。そのような場合、size()は0 を返します。詳細については、QIODevice::isSequential()を参照してください。
2. この関数はファイル名を指定せずにファイルを開くため、このQFile をQFileInfo と組み合わせて使用することはできません。

Windowsプラットフォームに関する注意

fh ファイルやその他のランダムアクセスデバイスにアクセスする際は、バイナリモード（つまり、モード文字列に「rb」や「wb」のように「b」が含まれている必要がある）で開く必要があります。mode に QIODevice::Text を渡すと、Qt は改行文字を変換します。stdin や stdout などのシーケンシャルデバイスは、この制限の影響を受けません。

コンソールで stdin、stdout、stderr ストリームを使用するには、コンソールアプリケーションのサポートを有効にする必要があります。これを行うには、アプリケーションのプロジェクトファイルに次の宣言を追加してください:

CONFIG += console

close() およびQT_USE_NODISCARD_FILE_OPENも参照してください 。

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

既存のファイルディスクリプタfd を、指定されたmode で開きます。追加のオプションを指定するには、handleFlags を使用できます。成功した場合はtrue を返し、失敗した場合はfalse を返します。

この関数を使用してQFile が開かれた場合、close()の動作はAutoCloseHandleフラグによって制御されます。AutoCloseHandleが指定されており、かつこの関数が成功した場合、close()を呼び出すと、引き継がれたハンドルが閉じられます。そうでない場合、close()は実際にはファイルを閉じず、単にフラッシュするだけです。

close() およびQT_USE_NODISCARD_FILE_OPENも参照してください 。

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

QFileDevice::permissions() const を再実装します。

setPermissions()も参照してください 。

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

fileName に対する QFile::Permission の組み合わせをすべて OR 演算で結合した結果を返します。

[static, since 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()も参照してください 。

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

この関数は Qt 6.0 で導入されました。

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

ファイル「oldName 」の名前を「newName 」に変更します。成功した場合は「true 」を返し、失敗した場合は「false 」を返します。

newName という名前のファイルがすでに存在する場合、rename() はfalse を返します（つまり、QFile は上書きされません）。

rename()も参照してください 。

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

QFileDevice::resize （qint64 sz）を再実装します。

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

fileName をsize（バイト単位）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 。

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

この関数は Qt 6.0 で導入されました。

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

QFileDevice::setPermissions （QFileDevice::Permissions の権限）を再実装します。

ファイルのアクセス権を、指定されたpermissions に設定します。成功した場合はtrue を返し、アクセス権を変更できない場合はfalse を返します。

関連項目: permissions() およびsetFileName()。

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

fileName ファイルの権限をpermissions に設定します。

[static, since 6.0] bool QFile::setPermissions(const std::filesystem::path &filename, QFileDevice::Permissions permissionSpec)

この関数は Qt 6.0 で導入されました。

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

QFileDevice::size() const を再実装します。

[static, since 6.9] bool QFile::supportsMoveToTrash()

Qt XMLが、moveToTrash()関数を使用して現在のオペレーティングシステム上でファイルをゴミ箱（リサイクルビン）に移動することをサポートしている場合はtrue を返し、そうでない場合はfalse を返します。なお、この関数がtrue を返したとしても、moveToTrash()が成功することを意味するわけではありません。特に、この関数は、ユーザーが設定でこの機能を無効にしているかどうかを検証しません。

この関数は Qt 6.9 で導入されました。

moveToTrash()も参照してください 。

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

fileName で指定されたシンボリックリンク（Windows ではショートカット）が指すファイルまたはディレクトリの絶対パスを返します。fileName がシンボリックリンクに対応していない場合は、空の文字列を返します。

この名前は既存のファイルを表すものではなく、単なる文字列です。QFile::exists() は、シンボリックリンクが既存のファイルを指している場合にのみ、true を返します。

QString QFile::symLinkTarget() const

シンボリックリンク（Windows ではショートカット）が指すファイルまたはディレクトリの絶対パスを返します。オブジェクトがシンボリックリンクでない場合は、空の文字列を返します。

この名前は、必ずしも既存のファイルを表すとは限りません。これは単なる文字列にすぎません。QFile::exists() は、シンボリックリンクが既存のファイルを指している場合に、true を返します。

fileName() およびsetFileName()も参照してください 。