\inmodule QtCore More...

#include <qfile.h>

Inheritance diagram for QFile:

Collaboration diagram for QFile:

Public Member Functions
	QFile ()
	Constructs a QFile object.

QFILE_MAYBE_EXPLICIT	QFile (const QString &name)

	QFile (QObject *parent)
	Constructs a new file object with the given parent.

	QFile (const QString &name, QObject *parent)
	Constructs a new file object with the given parent to represent the file with the specified name.

	~QFile ()
	Destroys the file object, closing it if necessary.

QString	fileName () const override
	Returns the name of the file as set by setFileName(), rename(), or by the QFile constructors.

void	setFileName (const QString &name)
	Sets the name of the file.

bool	exists () const
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.Returns `true` if the file specified by fileName() exists; otherwise returns `false`.

QString	symLinkTarget () const

bool	remove ()
	Removes the file specified by fileName().

bool	moveToTrash ()

bool	rename (const QString &newName)
	Renames the file currently specified by fileName() to newName.

bool	link (const QString &newName)
	Creates a link named linkName that points to the file currently specified by fileName().

QFILE_MAYBE_NODISCARD bool	open (OpenMode flags) override
	Opens the file using mode flags, returning `true` if successful; otherwise returns `false`.

QFILE_MAYBE_NODISCARD bool	open (OpenMode flags, Permissions permissions)

QFILE_MAYBE_NODISCARD bool	open (FILE *f, OpenMode ioFlags, FileHandleFlags handleFlags=DontCloseHandle)
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.Opens the existing file handle fh in the given mode.

QFILE_MAYBE_NODISCARD bool	open (int fd, OpenMode ioFlags, FileHandleFlags handleFlags=DontCloseHandle)
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.Opens the existing file descriptor fd in the given mode.

qint64	size () const override
	\reimp

bool	resize (qint64 sz) override
	\reimp

Permissions	permissions () const override
	\reimp

bool	setPermissions (Permissions permissionSpec) override
	Sets the permissions for the file to the permissions specified.

Public Member Functions inherited from QFileDevice
	~QFileDevice ()
	Destroys the file device, closing it if necessary.

FileError	error () const
	Returns the file error status.

void	unsetError ()
	Sets the file's error to QFileDevice::NoError.

void	close () override
	Calls QFileDevice::flush() and closes the file.

bool	isSequential () const override
	Returns `true` if the file can only be manipulated sequentially; otherwise returns `false`.

int	handle () const
	Returns the file handle of the file.

qint64	pos () const override
	\reimp

bool	seek (qint64 offset) override
	For random-access devices, this function sets the current position to pos, returning true on success, or false if an error occurred.

bool	atEnd () const override
	Returns `true` if the end of the file has been reached; otherwise returns false.

bool	flush ()
	Flushes any buffered data to the file.

qint64	size () const override
	Returns the size of the file.

uchar *	map (qint64 offset, qint64 size, MemoryMapFlags flags=NoOptions)
	Maps size bytes of the file into memory starting at offset.

bool	unmap (uchar *address)
	Unmaps the memory address.

QDateTime	fileTime (QFileDevice::FileTime time) const

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

Public Member Functions inherited from QIODevice
	QIODevice ()
	Constructs a QIODevice object.

	QIODevice (QObject *parent)
	Constructs a QIODevice object with the given parent.

virtual	~QIODevice ()
	The destructor is virtual, and QIODevice is an abstract base class.

QIODeviceBase::OpenMode	openMode () const
	Returns the mode in which the device has been opened; i.e.

void	setTextModeEnabled (bool enabled)
	If enabled is true, this function sets the \l Text flag on the device; otherwise the \l Text flag is removed.

bool	isTextModeEnabled () const
	Returns `true` if the \l Text flag is enabled; otherwise returns `false`.

bool	isOpen () const
	Returns `true` if the device is open; otherwise returns `false`.

bool	isReadable () const
	Returns `true` if data can be read from the device; otherwise returns false.

bool	isWritable () const
	Returns `true` if data can be written to the device; otherwise returns false.

int	readChannelCount () const

int	writeChannelCount () const

int	currentReadChannel () const

void	setCurrentReadChannel (int channel)

int	currentWriteChannel () const

void	setCurrentWriteChannel (int channel)

virtual bool	open (QIODeviceBase::OpenMode mode)
	Opens the device and sets its OpenMode to mode.

virtual bool	reset ()
	Seeks to the start of input for random-access devices.

virtual qint64	bytesAvailable () const
	Returns the number of bytes that are available for reading.

virtual qint64	bytesToWrite () const
	For buffered devices, this function returns the number of bytes waiting to be written.

qint64	read (char *data, qint64 maxlen)
	Reads at most maxSize bytes from the device into data, and returns the number of bytes read.

QByteArray	read (qint64 maxlen)
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.Reads at most maxSize bytes from the device, and returns the data read as a QByteArray.

QByteArray	readAll ()
	Reads all remaining data from the device, and returns it as a byte array.

qint64	readLine (char *data, qint64 maxlen)
	This function reads a line of ASCII characters from the device, up to a maximum of maxSize - 1 bytes, stores the characters in data, and returns the number of bytes read.

QByteArray	readLine (qint64 maxlen=0)
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.Reads a line from the device, but no more than maxSize characters, and returns the result as a byte array.

bool	readLineInto (QByteArray *result, qint64 maxlen=0)

QByteArrayView	readLineInto (QSpan< char > buffer)

QByteArrayView	readLineInto (QSpan< uchar > buffer)

QByteArrayView	readLineInto (QSpan< std::byte > buffer)
	Reads a line from this device into buffer, and returns the subset of buffer that contains the data read.

virtual bool	canReadLine () const
	Returns `true` if a complete line of data can be read from the device; otherwise returns `false`.

void	startTransaction ()

void	commitTransaction ()

void	rollbackTransaction ()

bool	isTransactionStarted () const

qint64	write (const char *data, qint64 len)
	Writes at most maxSize bytes of data from data to the device.

qint64	write (const char *data)

qint64	write (const QByteArray &data)
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.Writes the content of data to the device.

qint64	peek (char *data, qint64 maxlen)

QByteArray	peek (qint64 maxlen)

qint64	skip (qint64 maxSize)

virtual bool	waitForReadyRead (int msecs)
	Blocks until new data is available for reading and the readyRead() signal has been emitted, or until msecs milliseconds have passed.

virtual bool	waitForBytesWritten (int msecs)
	For buffered devices, this function waits until a payload of buffered written data has been written to the device and the bytesWritten() signal has been emitted, or until msecs milliseconds have passed.

void	ungetChar (char c)
	Puts the character c back into the device, and decrements the current position unless the position is 0.

bool	putChar (char c)
	Writes the character c to the device.

bool	getChar (char *c)
	Reads one character from the device and stores it in c.

QString	errorString () const
	Returns a human-readable description of the last device error that occurred.

Public Member Functions inherited from QObject
Q_INVOKABLE	QObject (QObject *parent=nullptr)
	Constructs an object with parent object parent.

virtual	~QObject ()
	Destroys the object, deleting all its child objects.

virtual bool	event (QEvent *event)
	This virtual function receives events to an object and should return true if the event e was recognized and processed.

virtual bool	eventFilter (QObject watched, QEvent event)
	Filters events if this object has been installed as an event filter for the watched object.

QString	objectName () const

Q_WEAK_OVERLOAD void	setObjectName (const QString &name)
	Sets the object's name to name.

void	setObjectName (QAnyStringView name)
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

QBindable< QString >	bindableObjectName ()

bool	isWidgetType () const
	Returns `true` if the object is a widget; otherwise returns `false`.

bool	isWindowType () const
	Returns `true` if the object is a window; otherwise returns `false`.

bool	isQuickItemType () const
	Returns `true` if the object is a QQuickItem; otherwise returns `false`.

bool	signalsBlocked () const noexcept
	Returns `true` if signals are blocked; otherwise returns `false`.

bool	blockSignals (bool b) noexcept
	If block is true, signals emitted by this object are blocked (i.e., emitting a signal will not invoke anything connected to it).

QThread *	thread () const
	Returns the thread in which the object lives.

bool	moveToThread (QThread *thread QT6_DECL_NEW_OVERLOAD_TAIL)
	Changes the thread affinity for this object and its children and returns `true` on success.

int	startTimer (int interval, Qt::TimerType timerType=Qt::CoarseTimer)
	This is an overloaded function that will start a timer of type timerType and a timeout of interval milliseconds.

int	startTimer (std::chrono::nanoseconds time, Qt::TimerType timerType=Qt::CoarseTimer)

void	killTimer (int id)
	Kills the timer with timer identifier, id.

void	killTimer (Qt::TimerId id)

template<typename T>
T	findChild (QAnyStringView aName, Qt::FindChildOptions options=Qt::FindChildrenRecursively) const
	Returns the child of this object that can be cast into type T and that is called name, or \nullptr if there is no such object.

template<typename T>
QList< T >	findChildren (QAnyStringView aName, Qt::FindChildOptions options=Qt::FindChildrenRecursively) const
	Returns all children of this object with the given name that can be cast to type T, or an empty list if there are no such objects.

template<typename T>
T	findChild (Qt::FindChildOptions options=Qt::FindChildrenRecursively) const
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

template<typename T>
QList< T >	findChildren (Qt::FindChildOptions options=Qt::FindChildrenRecursively) const
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

const QObjectList &	children () const
	Returns a list of child objects.

void	setParent (QObject *parent)
	Makes the object a child of parent.

void	installEventFilter (QObject *filterObj)
	Installs an event filter filterObj on this object.

void	removeEventFilter (QObject *obj)
	Removes an event filter object obj from this object.

QMetaObject::Connection	connect (const QObject sender, const char signal, const char *member, Qt::ConnectionType type=Qt::AutoConnection) const

bool	disconnect (const char signal=nullptr, const QObject receiver=nullptr, const char *member=nullptr) const

bool	disconnect (const QObject receiver, const char member=nullptr) const

void	dumpObjectTree () const
	Dumps a tree of children to the debug output.

void	dumpObjectInfo () const
	Dumps information about signal connections, etc.

bool	setProperty (const char *name, const QVariant &value)
	Sets the value of the object's name property to value.

bool	setProperty (const char *name, QVariant &&value)

QVariant	property (const char *name) const
	Returns the value of the object's name property.

QList< QByteArray >	dynamicPropertyNames () const

QBindingStorage *	bindingStorage ()

const QBindingStorage *	bindingStorage () const

QObject *	parent () const
	Returns a pointer to the parent object.

bool	inherits (const char *classname) const
	Returns `true` if this object is an instance of a class that inherits className or a QObject subclass that inherits className; otherwise returns `false`.

Static Public Member Functions
static QByteArray	encodeName (const QString &fileName)
	Converts fileName to an 8-bit encoding that you can use in native APIs.

static QString	decodeName (const QByteArray &localFileName)
	This does the reverse of QFile::encodeName() using localFileName.

static QString	decodeName (const char *localFileName)
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.Returns the Unicode version of the given localFileName.

static bool	exists (const QString &fileName)
	Returns `true` if the file specified by fileName exists; otherwise returns `false`.

static QString	symLinkTarget (const QString &fileName)

static bool	remove (const QString &fileName)
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.Removes the file specified by the fileName given.

static bool	supportsMoveToTrash () Q_DECL_PURE_FUNCTION

static bool	moveToTrash (const QString &fileName, QString *pathInTrash=nullptr)

static bool	rename (const QString &oldName, const QString &newName)
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.Renames the file oldName to newName.

static bool	link (const QString &fileName, const QString &newName)
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.Creates a link named linkName that points to the file fileName.

static bool	resize (const QString &filename, qint64 sz)
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.Sets fileName to size (in bytes) sz.

static Permissions	permissions (const QString &filename)
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.Returns the complete OR-ed together combination of QFile::Permission for fileName.

static bool	setPermissions (const QString &filename, Permissions permissionSpec)
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.Sets the permissions for fileName file to permissions.

Static Public Member Functions inherited from QObject
static QMetaObject::Connection	connect (const QObject sender, const char signal, const QObject receiver, const char member, Qt::ConnectionType=Qt::AutoConnection)
	\threadsafe

static QMetaObject::Connection	connect (const QObject sender, const QMetaMethod &signal, const QObject receiver, const QMetaMethod &method, Qt::ConnectionType type=Qt::AutoConnection)

template<typename Func1, typename Func2>
static QMetaObject::Connection	connect (const typename QtPrivate::FunctionPointer< Func1 >::Object sender, Func1 signal, const typename QtPrivate::ContextTypeForFunctor< Func2 >::ContextType context, Func2 &&slot, Qt::ConnectionType type=Qt::AutoConnection)

template<typename Func1, typename Func2>
static QMetaObject::Connection	connect (const typename QtPrivate::FunctionPointer< Func1 >::Object *sender, Func1 signal, Func2 &&slot)

static bool	disconnect (const QObject sender, const char signal, const QObject receiver, const char member)
	\threadsafe

static bool	disconnect (const QObject sender, const QMetaMethod &signal, const QObject receiver, const QMetaMethod &member)

static bool	disconnect (const QMetaObject::Connection &)
	Disconnect a connection.

template<typename Func1, typename Func2>
static bool	disconnect (const typename QtPrivate::FunctionPointer< Func1 >::Object sender, Func1 signal, const typename QtPrivate::FunctionPointer< Func2 >::Object receiver, Func2 slot)

template<typename Func1>
static bool	disconnect (const typename QtPrivate::FunctionPointer< Func1 >::Object sender, Func1 signal, const QObject receiver, void **zero)

Protected Member Functions
	QFile (QFilePrivate &dd, QObject *parent=nullptr)

Protected Member Functions inherited from QFileDevice
	QFileDevice ()
	\macro QT_USE_NODISCARD_FILE_OPEN \macro QT_NO_USE_NODISCARD_FILE_OPEN

	QFileDevice (QObject *parent)

	QFileDevice (QFileDevicePrivate &dd, QObject *parent=nullptr)

qint64	readData (char *data, qint64 maxlen) override
	\reimp

qint64	writeData (const char *data, qint64 len) override
	\reimp

qint64	readLineData (char *data, qint64 maxlen) override
	\reimp

Protected Member Functions inherited from QIODevice
	QIODevice (QIODevicePrivate &dd, QObject *parent=nullptr)

virtual qint64	skipData (qint64 maxSize)

void	setOpenMode (QIODeviceBase::OpenMode openMode)
	Sets the OpenMode of the device to openMode.

void	setErrorString (const QString &errorString)
	Sets the human readable description of the last device error that occurred to str.

Protected Member Functions inherited from QObject
QObject *	sender () const
	Returns a pointer to the object that sent the signal, if called in a slot activated by a signal; otherwise it returns \nullptr.

int	senderSignalIndex () const

int	receivers (const char *signal) const
	Returns the number of receivers connected to the signal.

bool	isSignalConnected (const QMetaMethod &signal) const

virtual void	timerEvent (QTimerEvent *event)
	This event handler can be reimplemented in a subclass to receive timer events for the object.

virtual void	childEvent (QChildEvent *event)
	This event handler can be reimplemented in a subclass to receive child events.

virtual void	customEvent (QEvent *event)
	This event handler can be reimplemented in a subclass to receive custom events.

virtual void	connectNotify (const QMetaMethod &signal)

virtual void	disconnectNotify (const QMetaMethod &signal)

	QObject (QObjectPrivate &dd, QObject *parent=nullptr)

Protected Member Functions inherited from QIODeviceBase
	~QIODeviceBase ()=default

Friends
class	QTemporaryFile

Additional Inherited Members
Public Types inherited from QFileDevice
enum	FileError { NoError = 0 , ReadError = 1 , WriteError = 2 , FatalError = 3 , ResourceError = 4 , OpenError = 5 , AbortError = 6 , TimeOutError = 7 , UnspecifiedError = 8 , RemoveError = 9 , RenameError = 10 , PositionError = 11 , ResizeError = 12 , PermissionsError = 13 , CopyError = 14 }
	This enum describes the errors that may be returned by the error() function. More...

enum	FileTime { FileAccessTime , FileBirthTime , FileMetadataChangeTime , FileModificationTime }

enum	Permission { ReadOwner = 0x4000 , WriteOwner = 0x2000 , ExeOwner = 0x1000 , ReadUser = 0x0400 , WriteUser = 0x0200 , ExeUser = 0x0100 , ReadGroup = 0x0040 , WriteGroup = 0x0020 , ExeGroup = 0x0010 , ReadOther = 0x0004 , WriteOther = 0x0002 , ExeOther = 0x0001 }
	This enum is used by the permission() function to report the permissions and ownership of a file. More...

enum	FileHandleFlag { AutoCloseHandle = 0x0001 , DontCloseHandle = 0 }
	This enum is used when opening a file to specify additional options which only apply to files and not to a generic QIODevice. More...

enum	MemoryMapFlag { NoOptions = 0 , MapPrivateOption = 0x0001 }

Public Types inherited from QIODeviceBase
enum	OpenModeFlag { NotOpen = 0x0000 , ReadOnly = 0x0001 , WriteOnly = 0x0002 , ReadWrite = ReadOnly \| WriteOnly , Append = 0x0004 , Truncate = 0x0008 , Text = 0x0010 , Unbuffered = 0x0020 , NewOnly = 0x0040 , ExistingOnly = 0x0080 }
	This enum is used with QIODevice::open() to describe the mode in which a device is opened. More...

Public Slots inherited from QObject
void	deleteLater ()
	\threadsafe

Signals inherited from QIODevice
void	readyRead ()
	This signal is emitted once every time new data is available for reading from the device's current read channel.

void	channelReadyRead (int channel)

void	bytesWritten (qint64 bytes)
	This signal is emitted every time a payload of data has been written to the device's current write channel.

void	channelBytesWritten (int channel, qint64 bytes)

void	aboutToClose ()
	This signal is emitted when the device is about to close.

void	readChannelFinished ()

Signals inherited from QObject
void	destroyed (QObject *=nullptr)
	This signal is emitted immediately before the object obj is destroyed, after any instances of QPointer have been notified, and cannot be blocked.

void	objectNameChanged (const QString &objectName, QPrivateSignal)
	This signal is emitted after the object's name has been changed.

Protected Attributes inherited from QObject
QScopedPointer< QObjectData >	d_ptr

Properties inherited from QObject
QString	objectName
	the name of this object

Related Symbols inherited from QObject
template< class T > T	qobject_cast (const QObject *object)
	Returns the given object cast to type T if the object is of type T (or of a subclass); otherwise returns \nullptr.

template< typename T > T	qFindChildqFindChildren (const QObject *obj, const QString &name)()

template< typename T > QList< T >	qFindChildrenqFindChildren (const QObject *obj, const QString &name)()

	QObjectList
	\macro Q_CLASSINFO(Name, Value)

Detailed Description

\inmodule QtCore

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

\reentrant

QFile is an I/O device for reading and writing text and binary files and \l{The Qt Resource System}{resources}. A QFile may be used by itself or, more conveniently, with a QTextStream or QDataStream.

The file name is usually passed in the constructor, but it can be set at any time using setFileName(). QFile expects the file separator to be '/' regardless of operating system. The use of other separators (e.g., '\') is not supported.

You can check for a file's existence using exists(), and remove a file using remove(). (More advanced file system related operations are provided by QFileInfo and QDir.)

The file is opened with open(), closed with close(), and flushed with flush(). Data is usually read and written using QDataStream or QTextStream, but you can also call the QIODevice-inherited functions read(), readLine(), readAll(), write(). QFile also inherits getChar(), putChar(), and ungetChar(), which work one character at a time.

The size of the file is returned by size(). You can get the current file position using pos(), or move to a new file position using seek(). If you've reached the end of the file, atEnd() returns true.

Definition at line 94 of file qfile.h.

Constructor & Destructor Documentation

◆ QFile() [1/5]

QFile::QFile ( )

Constructs a QFile object.

Definition at line 217 of file qfile.cpp.

◆ QFile() [2/5]

QFile::QFile ( const QString & name )

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

! [qfile-explicit-constructor-note]

Note: In versions up to and including Qt 6.8, this constructor is implicit, for backward compatibility. Starting from Qt 6.9 this constructor is unconditionally {explicit}. Users can force this constructor to be {explicit} even in earlier versions of Qt by defining the {QT_EXPLICIT_QFILE_CONSTRUCTION_FROM_PATH} macro before including any Qt header. ! [qfile-explicit-constructor-note]

Definition at line 240 of file qfile.cpp.

◆ QFile() [3/5]

QFile::QFile ( QObject * parent )

explicit

Constructs a new file object with the given parent.

Definition at line 224 of file qfile.cpp.

◆ QFile() [4/5]

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

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

Definition at line 250 of file qfile.cpp.

◆ ~QFile()

QFile::~QFile ( )

Destroys the file object, closing it if necessary.

Definition at line 268 of file qfile.cpp.

◆ QFile() [5/5]

QFile::QFile	(	QFilePrivate &	dd,
		QObject *	parent = nullptr )

protected

Definition at line 259 of file qfile.cpp.

Member Function Documentation

◆ decodeName() [1/2]

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

inlinestatic

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.Returns the Unicode version of the given localFileName.

See encodeName() for details.

Definition at line 168 of file qfile.h.

◆ decodeName() [2/2]

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

inlinestatic

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

See also: encodeName()

Definition at line 164 of file qfile.h.

◆ encodeName()

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

inlinestatic

Converts fileName to an 8-bit encoding that you can use in native APIs.

On Windows, the encoding is the one from active Windows (ANSI) codepage. On other platforms, this is UTF-8, for \macos in decomposed form (NFD).

See also: decodeName()

Definition at line 160 of file qfile.h.

◆ exists() [1/2]

bool QFile::exists ( ) const

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.Returns true if the file specified by fileName() exists; otherwise returns false.

See also: fileName(), setFileName()

Definition at line 352 of file qfile.cpp.

◆ exists() [2/2]

bool QFile::exists ( const QString & fileName )

static

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

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

Definition at line 369 of file qfile.cpp.

◆ fileName()

QString QFile::fileName ( ) const

overridevirtual

Returns the name of the file as set by setFileName(), rename(), or by the QFile constructors.

See also: setFileName(), rename(), QFileInfo::fileName()

Reimplemented from QFileDevice.

Definition at line 278 of file qfile.cpp.

◆ link() [1/2]

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

static

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.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.

See also: link()

Definition at line 761 of file qfile.cpp.

◆ link() [2/2]

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 \l{QFile::}{error()} to return \l{QFile::}{RenameError}.

Note: To create a valid link on Windows, linkName must have a {.lnk} file extension.

See also: setFileName()

Definition at line 733 of file qfile.cpp.

◆ moveToTrash() [1/2]

bool QFile::moveToTrash ( )

\since 5.15

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

! [move-to-trash-common] The time for this function to run is independent of the size of the file being trashed. If this function is called on a directory, it may be proportional to the number of files being trashed. If the current fileName() points to a symbolic link, this function will move the link to the trash, possibly breaking it, not the target of the link.

This function uses the Windows and \macos APIs to perform the trashing on those two operating systems. Elsewhere (Unix systems), this function implements the \l{FreeDesktop.org Trash specification version 1.0}.

Note

When using the FreeDesktop.org Trash implementation, this function will fail if it is unable to move the files to the trash location by way of file renames and hardlinks. This condition arises if the file being trashed resides on a volume (mount point) on which the current user does not have permission to create the {.Trash} directory, or with some unusual filesystem types or configurations (such as sub-volumes that aren't themselves mount points). ! [move-to-trash-common]

\note 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 \c false (see supportsMoveToTrash()).

\sa supportsMoveToTrash(), remove(), QDir::remove()

Definition at line 507 of file qfile.cpp.

◆ moveToTrash() [2/2]

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

static

Since: 5.15 This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

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.

move-to-trash-common

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

Definition at line 547 of file qfile.cpp.

◆ open() [1/4]

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

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.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:} \list 1

If fh does not refer to a regular file, e.g., 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.
Since this function opens the file without specifying the file name, you cannot use this QFile with a QFileInfo. \endlist

See also: close(), QT_USE_NODISCARD_FILE_OPEN

{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

Definition at line 1019 of file qfile.cpp.

◆ open() [2/4]

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

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.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.

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.; Since this function opens the file without specifying the file name, you cannot use this QFile with a QFileInfo.

See also: close(), QT_USE_NODISCARD_FILE_OPEN

Definition at line 1071 of file qfile.cpp.

◆ open() [3/4]

bool QFile::open ( OpenMode mode )

override

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

The flags for mode must include \l QIODeviceBase::ReadOnly, \l WriteOnly, or \l ReadWrite. It may also have additional flags, such as \l Text and \l Unbuffered.

Note: In \l{WriteOnly} or \l{ReadWrite} mode, if the relevant file does not already exist, this function will try to create a new file before opening it. The file will be created with mode 0666 masked by the umask on POSIX systems, and with permissions inherited from the parent directory on Windows. On Android, it's expected to have access permission to the parent of the file name, otherwise, it won't be possible to create this non-existing file.

See also: QT_USE_NODISCARD_FILE_OPEN, setFileName()

Definition at line 904 of file qfile.cpp.

◆ open() [4/4]

QFILE_MAYBE_NODISCARD bool QFile::open	(	OpenMode	flags,
		Permissions	permissions )

◆ permissions() [1/2]

QFile::Permissions QFile::permissions ( ) const

overridevirtual

\reimp

Reimplemented from QFileDevice.

Definition at line 1130 of file qfile.cpp.

◆ permissions() [2/2]

QFile::Permissions QFile::permissions ( const QString & filename )

static

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.Returns the complete OR-ed together combination of QFile::Permission for fileName.

Definition at line 1143 of file qfile.cpp.

◆ remove() [1/2]

bool QFile::remove ( )

Removes the file specified by fileName().

Returns true if successful; otherwise returns false.

The file is closed before it is removed.

See also: setFileName()

Definition at line 420 of file qfile.cpp.

◆ remove() [2/2]

bool QFile::remove ( const QString & fileName )

static

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.Removes the file specified by the fileName given.

Returns true if successful; otherwise returns false.

See also: remove()

Definition at line 451 of file qfile.cpp.

◆ rename() [1/2]

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.

See also: setFileName()

Definition at line 576 of file qfile.cpp.

◆ rename() [2/2]

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

static

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.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).

See also: rename()

Definition at line 711 of file qfile.cpp.

◆ resize() [1/2]

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

static

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.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.

See also: resize()

Definition at line 1122 of file qfile.cpp.

◆ resize() [2/2]

bool QFile::resize ( qint64 sz )

overridevirtual

\reimp

Reimplemented from QFileDevice.

Definition at line 1103 of file qfile.cpp.

◆ setFileName()

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.

See also: fileName(), QFileInfo, QDir

Since: 6.0 This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Definition at line 303 of file qfile.cpp.

◆ setPermissions() [1/2]

bool QFile::setPermissions	(	const QString &	filename,
		Permissions	permissionSpec )

static

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.Sets the permissions for fileName file to permissions.

Definition at line 1171 of file qfile.cpp.

◆ setPermissions() [2/2]

bool QFile::setPermissions ( Permissions permissions )

overridevirtual

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.

See also: permissions(), setFileName()

Reimplemented from QFileDevice.

Definition at line 1159 of file qfile.cpp.

◆ size()

qint64 QFile::size ( ) const

overridevirtual

\reimp

Reimplemented from QIODevice.

Definition at line 1179 of file qfile.cpp.

◆ supportsMoveToTrash()

bool QFile::supportsMoveToTrash ( )

static

Since: 6.9

Returns true if Qt supports moving files to a trash (recycle bin) in the current operating system using the moveToTrash() function, false otherwise. Note that this function returning true does not imply moveToTrash() will succeed. In particular, this function does not check if the user has disabled the functionality in their settings.

See also: moveToTrash()

Definition at line 467 of file qfile.cpp.

◆ symLinkTarget() [1/2]

QString QFile::symLinkTarget ( ) const

Since: 4.2 This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

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.

See also: fileName(), setFileName()

Definition at line 388 of file qfile.cpp.

◆ symLinkTarget() [2/2]

QString QFile::symLinkTarget ( const QString & fileName )

static

Since: 4.2

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.

Definition at line 405 of file qfile.cpp.

Friends And Related Symbol Documentation

◆ QTemporaryFile

friend class QTemporaryFile

friend

Definition at line 328 of file qfile.h.

The documentation for this class was generated from the following files:

qtbase/src/corelib/io/qfile.h (8379d1e90a3296b3be961878ee31f93ec672f883)
qtbase/src/corelib/io/qfile.cpp (675d6fd5588c65928224756ada41a9c294db608a)

Public Member Functions

Static Public Member Functions

Protected Member Functions

Friends

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

◆ QFile() [1/5]

◆ QFile() [2/5]

◆ QFile() [3/5]

◆ QFile() [4/5]

◆ ~QFile()

◆ QFile() [5/5]

Member Function Documentation

◆ decodeName() [1/2]

◆ decodeName() [2/2]

◆ encodeName()

◆ exists() [1/2]

◆ exists() [2/2]

◆ fileName()

◆ link() [1/2]

◆ link() [2/2]

◆ moveToTrash() [1/2]

◆ moveToTrash() [2/2]

◆ open() [1/4]

◆ open() [2/4]

◆ open() [3/4]

◆ open() [4/4]

◆ permissions() [1/2]

◆ permissions() [2/2]

◆ remove() [1/2]

◆ remove() [2/2]

◆ rename() [1/2]

◆ rename() [2/2]

◆ resize() [1/2]

◆ resize() [2/2]

◆ setFileName()

◆ setPermissions() [1/2]

◆ setPermissions() [2/2]

◆ size()

◆ supportsMoveToTrash()

◆ symLinkTarget() [1/2]

◆ symLinkTarget() [2/2]

Friends And Related Symbol Documentation

◆ QTemporaryFile