En esta página

QFileDevice Class

La clase QFileDevice proporciona una interfaz para leer y escribir en archivos abiertos. Más información...

Encabezado: #include <QFileDevice>
CMake: find_package(Qt6 REQUIRED COMPONENTS Core)
target_link_libraries(mytarget PRIVATE Qt6::Core)
qmake: QT += core
Heredado de: QIODevice
Heredado por:

QFile y QSaveFile

Nota: Todas las funciones de esta clase son reentrantes.

Tipos públicos

enum FileError { NoError, ReadError, WriteError, FatalError, ResourceError, …, CopyError }
enum FileHandleFlag { AutoCloseHandle, DontCloseHandle }
flags FileHandleFlags
enum FileTime { FileAccessTime, FileBirthTime, FileMetadataChangeTime, FileModificationTime }
enum MemoryMapFlag { NoOptions, MapPrivateOption }
flags MemoryMapFlags
enum Permission { ReadOwner, WriteOwner, ExeOwner, ReadUser, WriteUser, …, ExeOther }
flags Permissions

Funciones públicas

virtual ~QFileDevice()
QFileDevice::FileError error() const
virtual QString fileName() const
QDateTime fileTime(QFileDevice::FileTime time) const
bool flush()
int handle() const
uchar *map(qint64 offset, qint64 size, QFileDevice::MemoryMapFlags flags = NoOptions)
virtual QFileDevice::Permissions permissions() const
virtual bool resize(qint64 sz)
bool setFileTime(const QDateTime &newDate, QFileDevice::FileTime fileTime)
virtual bool setPermissions(QFileDevice::Permissions permissions)
bool unmap(uchar *address)
void unsetError()

Funciones públicas reimplementadas

virtual bool atEnd() const override
virtual void close() override
virtual bool isSequential() const override
virtual qint64 pos() const override
virtual bool seek(qint64 pos) override
virtual qint64 size() const override

Funciones protegidas reimplementadas

virtual qint64 readData(char *data, qint64 len) override
virtual qint64 readLineData(char *data, qint64 maxlen) override
virtual qint64 writeData(const char *data, qint64 len) override

Macros

Descripción detallada

QFileDevice es la clase base para dispositivos de E/S capaces de leer y escribir archivos de texto y binarios, así como recursos. QFile ofrece la funcionalidad principal; QFileDevice sirve como clase base para compartir dicha funcionalidad con otros dispositivos de archivos, como QSaveFile, al proporcionar todas las operaciones que se pueden realizar sobre archivos abiertos mediante QFile o QSaveFile.

Véase también QFile y QSaveFile.

Documentación sobre tipos de miembros

enum QFileDevice::FileError

Esta enumeración describe los errores que puede devolver la función error().

ConstanteValorDescripción
QFileDevice::NoError0No se ha producido ningún error.
QFileDevice::ReadError1Se ha producido un error al leer el archivo.
QFileDevice::WriteError2Se ha producido un error al escribir en el archivo.
QFileDevice::FatalError3Se ha producido un error grave.
QFileDevice::ResourceError4Se han agotado los recursos (por ejemplo, demasiados archivos abiertos, falta de memoria, etc.)
QFileDevice::OpenError5No se ha podido abrir el archivo.
QFileDevice::AbortError6La operación se ha interrumpido.
QFileDevice::TimeOutError7Se ha producido un tiempo de espera agotado.
QFileDevice::UnspecifiedError8Se ha producido un error no especificado.
QFileDevice::RemoveError9No se ha podido eliminar el archivo.
QFileDevice::RenameError10No se ha podido cambiar el nombre del archivo.
QFileDevice::PositionError11No se ha podido cambiar la posición en el archivo.
QFileDevice::ResizeError12No se ha podido cambiar el tamaño del archivo.
QFileDevice::PermissionsError13No se ha podido acceder al archivo.
QFileDevice::CopyError14No se ha podido copiar el archivo.

enum QFileDevice::FileHandleFlag
flags QFileDevice::FileHandleFlags

Esta enumeración se utiliza al abrir un archivo para especificar opciones adicionales que solo se aplican a los archivos y no a un objeto genérico de tipo ` QIODevice`.

ConstanteValorDescripción
QFileDevice::AutoCloseHandle0x0001El identificador de archivo pasado a ` open()` debe cerrarse mediante ` close()`; el comportamiento por defecto es que `close` simplemente vacía el archivo y la aplicación es responsable de cerrar el identificador de archivo. Al abrir un archivo por nombre, este indicador se ignora, ya que Qt XML siempre es el propietario del identificador de archivo y debe cerrarlo.
QFileDevice::DontCloseHandle0Si no se cierra explícitamente, el identificador de archivo subyacente queda abierto cuando se destruye el objeto ` QFile `.

El tipo `FileHandleFlags` es un `typedef` para ` QFlags<FileHandleFlag>`. Almacena una combinación OR de valores de `FileHandleFlag`.

enum QFileDevice::FileTime

Esta enumeración es utilizada por las funciones fileTime() y setFileTime().

ConstanteValorDescripción
QFileDevice::FileAccessTime0Momento en que se accedió por última vez al archivo (por ejemplo, para leerlo o escribir en él).
QFileDevice::FileBirthTime1Cuándo se creó el archivo (puede que no sea compatible con UNIX).
QFileDevice::FileMetadataChangeTime2Cuándo se modificaron por última vez los metadatos del archivo.
QFileDevice::FileModificationTime3Cuándo se modificó el archivo por última vez.

Véase también setFileTime(), fileTime() y QFileInfo::fileTime().

enum QFileDevice::MemoryMapFlag
flags QFileDevice::MemoryMapFlags

Esta enumeración describe las opciones especiales que puede utilizar la función map().

ConstanteValorDescripción
QFileDevice::NoOptions0Sin opciones.
QFileDevice::MapPrivateOption0x0001La memoria mapeada será privada, por lo que cualquier modificación no será visible para otros procesos y no se escribirá en el disco. Cualquier modificación de este tipo se perderá cuando se desasigne la memoria. No se especifica si las modificaciones realizadas en el archivo tras la creación de la asignación serán visibles a través de la memoria asignada. Este valor de enumeración se introdujo en Qt 5.4.

El tipo `MemoryMapFlags` es un `typedef` para ` QFlags<MemoryMapFlag>`. Almacena una combinación OR de valores de `MemoryMapFlag`.

enum QFileDevice::Permission
flags QFileDevice::Permissions

La función permission() utiliza esta enumeración para informar de los permisos y la titularidad de un archivo. Los valores se pueden combinar mediante la operación OR para comprobar varios valores de permisos y titularidad.

ConstanteValorDescripción
QFileDevice::ReadOwner0x4000El propietario del archivo puede leerlo.
QFileDevice::WriteOwner0x2000El propietario del archivo puede escribir en él.
QFileDevice::ExeOwner0x1000El propietario del archivo puede ejecutarlo.
QFileDevice::ReadUser0x0400El usuario puede leer el archivo.
QFileDevice::WriteUser0x0200El usuario puede escribir en el archivo.
QFileDevice::ExeUser0x0100El usuario puede ejecutar el archivo.
QFileDevice::ReadGroup0x0040El grupo puede leer el archivo.
QFileDevice::WriteGroup0x0020El grupo puede escribir en el archivo.
QFileDevice::ExeGroup0x0010El grupo puede ejecutar el archivo.
QFileDevice::ReadOther0x0004El archivo es legible para otros.
QFileDevice::WriteOther0x0002Otros pueden escribir en el archivo.
QFileDevice::ExeOther0x0001El archivo es ejecutable para otros usuarios.

Advertencia: debido a las diferencias entre las plataformas compatibles con Qt, la semántica de ReadUser, WriteUser y ExeUser depende de la plataforma: en Unix se devuelven los derechos del propietario del archivo y en Windows se devuelven los derechos del usuario actual. Este comportamiento podría cambiar en una futura versión de Qt.

Nota: En los sistemas de archivos NTFS, la comprobación de la propiedad y los permisos está desactivada por defecto por motivos de rendimiento. Para activarla, incluye la siguiente línea:

extern Q_CORE_EXPORT int qt_ntfs_permission_lookup;

La comprobación de permisos se activa y desactiva incrementando o decrementando en 1 el valor de « qt_ntfs_permission_lookup ».

qt_ntfs_permission_lookup++; // turn checking on
qt_ntfs_permission_lookup--; // turn it off again

Nota: Dado que se trata de una variable global no atómica, solo es seguro incrementar o decrementar ` qt_ntfs_permission_lookup ` antes de que se hayan iniciado otros hilos distintos del hilo principal o después de que todos los hilos distintos del hilo principal hayan finalizado.

Nota: A partir de Qt 6.6, la variable ` qt_ntfs_permission_lookup ` está obsoleta. Utiliza las siguientes alternativas.

La forma más segura y sencilla de gestionar las comprobaciones de permisos es utilizar la clase RAII ` QNtfsPermissionCheckGuard`.

void complexFunction()
{
    QNtfsPermissionCheckGuard permissionGuard;  // check is enabled

    // do complex things here that need permission check enabled

}   // as the guard goes out of scope the check is disabled

Si necesitas un control más detallado, puedes gestionar los permisos con las siguientes funciones:

qAreNtfsPermissionChecksEnabled();   // comprobar el estado
qEnableNtfsPermissionChecks();       // turn checking on
qDisableNtfsPermissionChecks();      // turn it off again

El tipo «Permissions» es una definición de tipo (typedef) para QFlags<Permission>. Almacena una combinación OR de valores de «Permission».

Documentación de las funciones de miembro

[virtual noexcept] QFileDevice::~QFileDevice()

Destruye el dispositivo de archivo, cerrándolo si es necesario.

[override virtual] bool QFileDevice::atEnd() const

Reimplementa: ` QIODevice::atEnd()` const.

Devuelve ` true ` si se ha llegado al final del archivo; en caso contrario, devuelve `false`.

En el caso de los archivos vacíos habituales en Unix (por ejemplo, los que se encuentran en /proc), esta función devuelve true, ya que el sistema de archivos indica que el tamaño de dicho archivo es 0. Por lo tanto, no debes basarte en atEnd() al leer datos de un archivo de este tipo, sino llamar a read() hasta que no se puedan leer más datos.

[override virtual] void QFileDevice::close()

Reimplementa: ` QIODevice::close()`.

Llama a ` QFileDevice::flush()` y cierra el archivo. Se ignoran los errores de `flush`.

Véase también QIODevice::close().

QFileDevice::FileError QFileDevice::error() const

Devuelve el estado de error del archivo.

El estado del dispositivo de E/S devuelve un código de error. Por ejemplo, si open() devuelve false, o si una operación de lectura/escritura devuelve -1, se puede llamar a esta función para averiguar el motivo por el que ha fallado la operación.

Véase también unsetError().

[virtual] QString QFileDevice::fileName() const

Devuelve el nombre del archivo. La implementación por defecto en QFileDevice devuelve una cadena nula.

QDateTime QFileDevice::fileTime(QFileDevice::FileTime time) const

Devuelve la hora del archivo especificada por time. Si no se puede determinar la hora, devuelve QDateTime() (una fecha y hora no válidas).

Véase también setFileTime(), FileTime y QDateTime::isValid().

bool QFileDevice::flush()

Vacíe los datos almacenados en el búfer al archivo. Devuelve « true » si la operación se realiza correctamente; en caso contrario, devuelve « false ».

int QFileDevice::handle() const

Devuelve el identificador del archivo.

Se trata de un número entero positivo pequeño, adecuado para su uso con funciones de la biblioteca de C como fdopen() y fcntl(). En sistemas que utilizan descriptores de archivo para sockets (es decir, sistemas Unix, pero no Windows), el identificador también se puede utilizar con QSocketNotifier.

Si el archivo no está abierto o se produce un error, `handle()` devuelve -1.

Véase también QSocketNotifier.

[override virtual] bool QFileDevice::isSequential() const

Reimplementa: QIODevice::isSequential() const.

Devuelve ` true ` si el archivo solo se puede manipular de forma secuencial; en caso contrario, devuelve ` false`.

La mayoría de los archivos admiten el acceso aleatorio, pero es posible que algunos archivos especiales no lo hagan.

Véase también QIODevice::isSequential().

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

Asigna size bytes del archivo a la memoria a partir de offset. Para que la asignación se realice correctamente, el archivo debe estar abierto, aunque no es necesario que permanezca abierto una vez que se haya asignado la memoria. Cuando se destruye el objeto QFile o se abre un nuevo archivo con este objeto, cualquier asignación que no se haya desasignado se desasignará automáticamente.

La asignación tendrá el mismo modo de apertura que el archivo (lectura y/o escritura), salvo cuando se utilice MapPrivateOption, en cuyo caso siempre será posible escribir en la memoria asignada.

Se pueden pasar opciones de asignación a través de ` flags`.

Devuelve un puntero a la memoria o ` nullptr ` si se produce un error.

Véase también ` unmap()`.

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

Devuelve la combinación completa, unida mediante la operación «OR», de los objetos `QFile::Permission` correspondientes al archivo.

Véase también setPermissions().

[override virtual] qint64 QFileDevice::pos() const

Reimplementa: QIODevice::pos() const.

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

Reimplementa: QIODevice::readData(char *data, qint64 maxSize).

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

Reimplementa: ` QIODevice::readLineData` (`char *data`, `qint64 maxSize`).

[virtual] bool QFileDevice::resize(qint64 sz)

Establece el tamaño del archivo (en bytes) sz. Devuelve true si el cambio de tamaño se realiza con éxito; en caso contrario, devuelve false. Si sz es mayor que el tamaño actual del archivo, los nuevos bytes se establecerán en 0; si sz es menor, el archivo simplemente se trunca.

Advertencia: Esta función puede fallar si el archivo no existe.

Véase también size().

[override virtual] bool QFileDevice::seek(qint64 pos)

Reimplementa: QIODevice::seek(qint64 pos).

En el caso de los dispositivos de acceso aleatorio, esta función establece la posición actual en pos, devolviendo «true» si la operación se realiza correctamente o «false» si se produce un error. En el caso de los dispositivos secuenciales, el comportamiento por defecto es no realizar ninguna acción y devolver «false».

Búsqueda más allá del final de un archivo: si la posición se encuentra más allá del final del archivo, seek() no ampliará inmediatamente el archivo. Si se realiza una escritura en esta posición, el archivo se ampliará. El contenido del archivo entre el final anterior del archivo y los datos recién escritos es INDEFINIDO y varía según las plataformas y los sistemas de archivos.

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

Establece la fecha y hora del archivo especificadas por ` fileTime ` en ` newDate`, devolviendo «true» si la operación se realiza correctamente; en caso contrario, devuelve «false».

Nota: El archivo debe estar abierto para poder utilizar esta función.

Véase también fileTime() y FileTime.

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

Establece los permisos del archivo según lo especificado en « permissions ». Devuelve « true » si la operación se realiza correctamente, o « false » si no es posible modificar los permisos.

Advertencia: Esta función no manipula las ACL, lo que puede limitar su eficacia.

Véase también permissions().

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

Reimplementa: ` QIODevice::size()` const.

Devuelve el tamaño del archivo.

En el caso de los archivos vacíos normales en Unix (por ejemplo, los que se encuentran en /proc), esta función devuelve 0; el contenido de dichos archivos se genera bajo demanda al llamar a read().

bool QFileDevice::unmap(uchar *address)

Desasigna la memoria address.

Devuelve ` true ` si la desasignación se realiza correctamente; en caso contrario, devuelve `false`.

Véase también map().

void QFileDevice::unsetError()

Establece el error del archivo en « QFileDevice::NoError ».

Véase también error().

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

Reimplementa: ` QIODevice::writeData` (const char *data, qint64 maxSize).

Documentación de macros

[since 6.8] QT_NO_USE_NODISCARD_FILE_OPEN

[since 6.8] QT_USE_NODISCARD_FILE_OPEN

Las clases de E/S relacionadas con archivos (como QFile, QSaveFile y QTemporaryFile) disponen de un método open() para abrir el archivo sobre el que actúan. Es importante comprobar el valor de retorno de la llamada a open() antes de proceder a leer o escribir datos en el archivo.

Por este motivo, a partir de Qt 6.8, algunas sobrecargas de ` open() ` se han marcado con el atributo ` [[nodiscard]] `. Dado que este cambio puede generar advertencias en los códigos existentes, el código de usuario puede optar por aplicar o no dicho atributo mediante la definición de determinadas macros:

  • Si se define la macro ` QT_USE_NODISCARD_FILE_OPEN `, las sobrecargas de ` open() ` se marcan como ` [[nodiscard]]`.
  • Si se define la macro ` QT_NO_USE_NODISCARD_FILE_OPEN `, las sobrecargas de ` open() ` no se marcan como ` [[nodiscard]]`.
  • Si no se define ninguna de las dos macros, el valor por defecto hasta Qt 6.9, inclusive, es no tener el atributo. A partir de Qt 6.10, el atributo se aplica automáticamente.
  • Si se definen ambas macros, el programa es inválido.

Estas macros se introdujeron en Qt 6.8.

© 2026 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.