QSaveFile Class

The QSaveFile class provides an interface for safely writing to files. More…

List of all members, including inherited members

Public Functions

Reimplemented Public Functions

Reimplemented Protected Functions

Detailed Description

QSaveFile writes to a temporary file next to the target and renames it over the target when commit() is called, so readers never see a partially written file. Call commit() when all data has been written. If a write fails, or cancelWriting() is called, commit() fails and the target is left untouched.

QSaveFile file("config.txt");
if (file.open(QIODevice::WriteOnly)) {
    file.write("key=value\n");
    if (!file.commit()) {
        // handle file.errorString()
    }
}

The temporary file is named <target>.XXXXXX and is removed when the object is destroyed without a commit. The permissions of an existing target are preserved; a new target gets 0666 masked by the umask.

See also QFile, QTemporaryFile and QFileDevice.

Differences from Qt

Member Function Documentation

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

Constructs a QSaveFile that will write to the file named name, with no parent.

See also setFileName().

[explicit] QSaveFile::QSaveFile(QObject *parent = nullptr)

Constructs a QSaveFile with no file name and the given parent.

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

Constructs a QSaveFile that will write to the file named name, with the given parent.

[override] QSaveFile::~QSaveFile()

Destroys the object. If the file is still open, it is closed and the temporary file is removed without replacing the target.

See also commit() and cancelWriting().

void QSaveFile::cancelWriting()

Cancels writing the file: sets error() to AbortError and makes a later commit() fail without touching the target. Does nothing if the file is not open.

See also commit().

bool QSaveFile::commit()

Syncs the temporary file to disk, closes it and renames it over the target. Returns true if the target was replaced; otherwise returns false, removes the temporary file and leaves the target untouched. Returns false if the file is not open, a write failed, or cancelWriting() was called. When writing directly to the target (see setDirectWriteFallback()), the file is flushed and closed instead.

See also cancelWriting() and open().

bool QSaveFile::directWriteFallback() const

Returns true if open() may write directly to the target when the temporary file cannot be created; otherwise returns false.

See also setDirectWriteFallback().

QString QSaveFile::fileName() const

Returns the name of the file that will be replaced by commit().

See also setFileName().

[override] bool QSaveFile::open(OpenMode mode)

Reimplements QFileDevice::open().

Opens a temporary file next to the target for writing with the given mode. Returns true on success; otherwise returns false and sets error(). The open fails if mode does not include WriteOnly or includes Append, if no file name is set, if NewOnly is given and the target exists, if ExistingOnly is given and it does not, or if an existing target is not writable. If the temporary file cannot be created and the direct write fallback is enabled, the target is opened and truncated instead.

See also commit() and setDirectWriteFallback().

void QSaveFile::setDirectWriteFallback(bool enabled)

Sets whether open() may fall back to writing directly to the target when the temporary file cannot be created. If enabled is true, the target is truncated and written in place, so the write is no longer atomic. The default is false.

See also directWriteFallback().

void QSaveFile::setFileName(const QString &name)

Sets the name of the file to write. Does nothing if the file is open.

See also fileName().

[override, protected] qint64 QSaveFile::writeData(const char *data, qint64 maxSize)

Reimplements QFileDevice::writeData().

Writes maxSize bytes from data to the temporary file. If the write is short or fails, commit() will fail.