QFileDevice Class

The QFileDevice class is the base class of devices that read and write files. More…

List of all members, including inherited members

Public Types

Public Functions

Reimplemented Public Functions

Static Public Members

Protected Functions

Reimplemented Protected Functions

Detailed Description

QFileDevice implements the file-descriptor based reading, writing and seeking shared by QFile, QSaveFile and QTemporaryFile. It is not instantiated directly. Data is read and written straight through the operating system, without an additional buffer.

The last failure is available from error() and errorString().

See also QFile, QSaveFile, QTemporaryFile and QIODevice.

Differences from Qt

Member Type Documentation

enum QFileDevice::FileError

Identifies the kind of error that last occurred on a file device.

enum QFileDevice::FileHandleFlag

How QFile::open() treats a file handle or descriptor it is given.

typedef QFileDevice::FileHandleFlags

A QFlags of FileHandleFlag values.

enum QFileDevice::FileTime

Selects one of the time stamps of a file.

This function was introduced in 5.10.

See also fileTime() and setFileTime().

enum QFileDevice::MemoryMapFlag

Options of map().

This function was introduced in 4.4.

typedef QFileDevice::MemoryMapFlags

A QFlags of MemoryMapFlag values.

typedef QFileDevice::Permission

The permission bits of a file, the same type as QFileInfo::Permission, so that values can be passed between the two classes.

typedef QFileDevice::Permissions

A QFlags combination of Permission values, the same type as QFileInfo::Permissions.

Member Function Documentation

[protected] QFileDevice::QFileDevice()

Constructs a file device with no parent. The device is not open.

[explicit, protected] QFileDevice::QFileDevice(QObject *parent)

Constructs a file device with the given parent. The device is not open.

[override] QFileDevice::~QFileDevice()

Destroys the file device, removing the mappings that map() created. Subclasses close the file in their own destructors; a descriptor that is still open here is closed unless it was opened with DontCloseHandle.

[override] bool QFileDevice::atEnd() const

Reimplements QIODevice::atEnd().

Returns true if the file is open and the position is at the end of the file with no buffered data left; otherwise returns false.

[override] qint64 QFileDevice::bytesAvailable() const

Reimplements QIODevice::bytesAvailable().

Returns the number of bytes between the current position and the end of the file, plus any buffered look-ahead data.

[override] bool QFileDevice::canReadLine() const

Reimplements QIODevice::canReadLine().

Returns true if the look-ahead buffer holds a complete line or the file is not at its end; otherwise returns false.

[override] void QFileDevice::close()

Reimplements QIODevice::close().

Closes the file and its descriptor. Does nothing if the file is not open.

FileError QFileDevice::error() const

Returns the file error status. The returned error is NoError if no error has occurred since the file was opened or unsetError() was called.

See also unsetError() and errorString().

QString QFileDevice::fileName() const

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

See also QFile::setFileName().

QDateTime QFileDevice::fileTime(FileTime time) const

Returns the time stamp time of the file, of the open descriptor or of the file named fileName(). Returns an invalid QDateTime if the file does not exist or the time is not available, such as a birth time on a file system that does not record it.

This function was introduced in 5.10.

See also setFileTime() and QFileInfo::lastModified().

bool QFileDevice::flush()

Flushes the file's pending data to disk by calling fsync() on the descriptor. Returns true if successful, or if the file is not open or does not support synchronizing; otherwise returns false.

See also close().

int QFileDevice::handle() const

Returns the native file descriptor of the open file, or -1 if the file is not open.

uchar * QFileDevice::map(qint64 offset, qint64 size, MemoryMapFlags flags = NoOptions)

Maps size bytes of the file, starting at offset, into memory and returns the address, or nullptr if it fails. The file must be open, and the range must lie within it. The memory is writable if the file is open for writing or flags contains MapPrivateOption. The mapping stays valid after close() until unmap() is called or the object is destroyed.

This function was introduced in 4.4.

See also unmap().

[protected] bool QFileDevice::openHandle(int fd, std::FILE *fh, OpenMode mode, FileHandleFlags handleFlags)

Adopts the open descriptor fd, or the stream fh if it is not nullptr, in mode. With AutoCloseHandle in handleFlags, close() closes it too. Subclasses call this from their open() overloads.

See also openPath().

[protected] bool QFileDevice::openPath(const QString &path, OpenMode mode)

Opens the file at path in the given mode and stores its descriptor. Returns true on success. Otherwise sets error() and errorString() and returns false.

Append and Truncate imply WriteOnly. The file is created if it does not exist, unless ExistingOnly is given. NewOnly fails if the file already exists. Opening a device that is already open fails with OpenError.

Subclasses call this function from their open() reimplementations.

See also close().

[protected] bool QFileDevice::openPath(const QString &path, OpenMode mode, Permissions createPermissions)

This is an overloaded function.

Opens the file at path in the given mode like the other overload. If this creates the file, it is created with the access permissions createPermissions, less what the umask of the process takes away; the permissions of a file that exists already are left alone.

This function was introduced in 6.3.

[virtual] Permissions QFileDevice::permissions() const

Returns the permissions of the file: of the open descriptor, or of the file named fileName() if the device is not open. Returns no permissions if the file does not exist.

See also setPermissions() and QFileInfo::permissions().

[override] qint64 QFileDevice::pos() const

Reimplements QIODevice::pos().

Returns the current file position, or 0 if the file is not open.

[override, protected] qint64 QFileDevice::readData(char *data, qint64 maxSize)

Reimplements QIODevice::readData().

Reads up to maxSize bytes from the file descriptor into data, retrying when interrupted. Returns the number of bytes read, or -1 on error, in which case error() is set to ReadError.

[override, protected] qint64 QFileDevice::readLineData(char *data, qint64 maxSize)

Reimplements QIODevice::readLineData().

Reads a chunk of up to maxSize bytes into data, ending at the first newline, and leaves the file position just after it. Returns the number of bytes read.

bool QFileDevice::resize(qint64 sz)

Sets the file size to sz bytes. Returns true if the file was resized successfully; returns false if the file is not open or the operation fails. If sz is larger than the file, the extra bytes read as zero; if it is smaller, the file is cut.

See also size().

[override] bool QFileDevice::seek(qint64 offset)

Reimplements QIODevice::seek().

For random-access devices, this function sets the current position to offset, measured from the start of the file. Returns true on success. Returns false if the file is not open, offset is negative, or the position cannot be changed, in which case error() is set to PositionError.

[protected] void QFileDevice::setFileError(FileError e, const QString &text)

Sets the file error to e and the error string to text.

See also error() and setErrorString().

bool QFileDevice::setFileTime(const QDateTime &newDate, FileTime fileTime)

Sets the time stamp fileTime of the file to newDate. Returns true if successful; otherwise sets error() to UnspecifiedError and returns false. Only FileAccessTime and FileModificationTime can be changed, and newDate must be valid.

This function was introduced in 5.10.

See also fileTime().

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

Sets the permissions of the file to permissions. Returns true if successful; otherwise sets error() to PermissionsError and returns false. The owner bits are set if either the Owner or the User flag is given.

See also permissions().

[override] qint64 QFileDevice::size() const

Reimplements QIODevice::size().

Returns the size of the file in bytes. If the file is not open, the size of the file at fileName() is returned. Returns 0 if the size cannot be determined.

bool QFileDevice::unmap(uchar *address)

Removes the mapping at address, which map() returned. Returns true if successful.

This function was introduced in 4.4.

See also map().

void QFileDevice::unsetError()

Sets the file's error to NoError. The error string is not cleared.

See also error().

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

Reimplements QIODevice::writeData().

Writes up to maxSize bytes from data to the file descriptor, retrying on partial writes. Returns the number of bytes written, or -1 if nothing could be written, in which case error() is set to WriteError.

Member Variable Documentation

[static, constexpr] Permission QFileDevice::ExeGroup

The file is executable by its group.

[static, constexpr] Permission QFileDevice::ExeOther

The file is executable by anyone.

[static, constexpr] Permission QFileDevice::ExeOwner

The file is executable by its owner.

[static, constexpr] Permission QFileDevice::ExeUser

The file is executable by the user. On POSIX systems this is the owner.

[static, constexpr] Permission QFileDevice::ReadGroup

The file is readable by its group.

[static, constexpr] Permission QFileDevice::ReadOther

The file is readable by anyone.

[static, constexpr] Permission QFileDevice::ReadOwner

The file is readable by its owner.

[static, constexpr] Permission QFileDevice::ReadUser

The file is readable by the user. On POSIX systems this is the owner.

[static, constexpr] Permission QFileDevice::WriteGroup

The file is writable by its group.

[static, constexpr] Permission QFileDevice::WriteOther

The file is writable by anyone.

[static, constexpr] Permission QFileDevice::WriteOwner

The file is writable by its owner.

[static, constexpr] Permission QFileDevice::WriteUser

The file is writable by the user. On POSIX systems this is the owner.