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: |
- Lista de todos los miembros, incluidos los heredados
- QFileDevice forma parte de Entrada/Salida y Redes.
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
(since 6.8) | QT_NO_USE_NODISCARD_FILE_OPEN |
(since 6.8) | QT_USE_NODISCARD_FILE_OPEN |
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().
| Constante | Valor | Descripción |
|---|---|---|
QFileDevice::NoError | 0 | No se ha producido ningún error. |
QFileDevice::ReadError | 1 | Se ha producido un error al leer el archivo. |
QFileDevice::WriteError | 2 | Se ha producido un error al escribir en el archivo. |
QFileDevice::FatalError | 3 | Se ha producido un error grave. |
QFileDevice::ResourceError | 4 | Se han agotado los recursos (por ejemplo, demasiados archivos abiertos, falta de memoria, etc.) |
QFileDevice::OpenError | 5 | No se ha podido abrir el archivo. |
QFileDevice::AbortError | 6 | La operación se ha interrumpido. |
QFileDevice::TimeOutError | 7 | Se ha producido un tiempo de espera agotado. |
QFileDevice::UnspecifiedError | 8 | Se ha producido un error no especificado. |
QFileDevice::RemoveError | 9 | No se ha podido eliminar el archivo. |
QFileDevice::RenameError | 10 | No se ha podido cambiar el nombre del archivo. |
QFileDevice::PositionError | 11 | No se ha podido cambiar la posición en el archivo. |
QFileDevice::ResizeError | 12 | No se ha podido cambiar el tamaño del archivo. |
QFileDevice::PermissionsError | 13 | No se ha podido acceder al archivo. |
QFileDevice::CopyError | 14 | No 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`.
| Constante | Valor | Descripción |
|---|---|---|
QFileDevice::AutoCloseHandle | 0x0001 | El 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::DontCloseHandle | 0 | Si 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().
| Constante | Valor | Descripción |
|---|---|---|
QFileDevice::FileAccessTime | 0 | Momento en que se accedió por última vez al archivo (por ejemplo, para leerlo o escribir en él). |
QFileDevice::FileBirthTime | 1 | Cuándo se creó el archivo (puede que no sea compatible con UNIX). |
QFileDevice::FileMetadataChangeTime | 2 | Cuándo se modificaron por última vez los metadatos del archivo. |
QFileDevice::FileModificationTime | 3 | Cuá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().
| Constante | Valor | Descripción |
|---|---|---|
QFileDevice::NoOptions | 0 | Sin opciones. |
QFileDevice::MapPrivateOption | 0x0001 | La 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.
| Constante | Valor | Descripción |
|---|---|---|
QFileDevice::ReadOwner | 0x4000 | El propietario del archivo puede leerlo. |
QFileDevice::WriteOwner | 0x2000 | El propietario del archivo puede escribir en él. |
QFileDevice::ExeOwner | 0x1000 | El propietario del archivo puede ejecutarlo. |
QFileDevice::ReadUser | 0x0400 | El usuario puede leer el archivo. |
QFileDevice::WriteUser | 0x0200 | El usuario puede escribir en el archivo. |
QFileDevice::ExeUser | 0x0100 | El usuario puede ejecutar el archivo. |
QFileDevice::ReadGroup | 0x0040 | El grupo puede leer el archivo. |
QFileDevice::WriteGroup | 0x0020 | El grupo puede escribir en el archivo. |
QFileDevice::ExeGroup | 0x0010 | El grupo puede ejecutar el archivo. |
QFileDevice::ReadOther | 0x0004 | El archivo es legible para otros. |
QFileDevice::WriteOther | 0x0002 | Otros pueden escribir en el archivo. |
QFileDevice::ExeOther | 0x0001 | El 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: |
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 againNota: 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 disabledSi 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 againEl 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
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.