QFile Class

Documentación de las funciones miembro

QFile::QFile()

Construye un objeto QFile.

[explicit] QFile::QFile(QObject *parent)

Crea un nuevo objeto de archivo con la dirección parent.

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

Construye un nuevo objeto de archivo para representar el archivo con la dirección name.

[explicit, since 6.0] QFile::QFile(const std::filesystem::path &name)

Construye un nuevo objeto archivo para representar el archivo con la dirección name.

Esta función se introdujo en Qt 6.0.

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

Construye un nuevo objeto de archivo con el parent dado para representar el archivo con el name especificado.

[since 6.0] QFile::QFile(const std::filesystem::path &name, QObject *parent)

Construye un nuevo objeto de archivo con el parent dado para representar el archivo con el name especificado.

Esta función se introdujo en Qt 6.0.

[virtual noexcept] QFile::~QFile()

Destruye el objeto archivo, cerrándolo si es necesario.

bool QFile::copy(const QString &newName)

Copia el archivo fileName() en newName.

Este fichero se cierra antes de ser copiado.

Si el fichero copiado es un enlace simbólico (symlink), se copia el fichero al que hace referencia, no el propio enlace. A excepción de los permisos, que se copian, no se copia ningún otro metadato del archivo.

Devuelve true si se ha realizado correctamente; en caso contrario, devuelve false.

Tenga en cuenta que si ya existe un archivo con el nombre newName, copy() devuelve false. Esto significa que QFile no lo sobrescribirá.

Véase también setFileName().

[since 6.0] bool QFile::copy(const std::filesystem::path &newName)

Esta función se introdujo en Qt 6.0.

[static] bool QFile::copy(const QString &fileName, const QString &newName)

Copia el fichero fileName en newName.

Si el archivo copiado es un enlace simbólico (symlink), se copia el archivo al que hace referencia, no el propio enlace. A excepción de los permisos, que se copian, no se copia ningún otro metadato del archivo.

Devuelve true si se ha realizado correctamente; en caso contrario, devuelve false.

Tenga en cuenta que si ya existe un archivo con el nombre newName, copy() devuelve false. Esto significa que QFile no lo sobrescribirá.

Véase también rename().

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

Esto hace lo contrario de QFile::encodeName() utilizando localFileName.

Véase también encodeName().

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

Devuelve la versión Unicode de localFileName. Véase encodeName() para más detalles.

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

Convierte fileName a una codificación de 8 bits que puede utilizar en las API nativas. En Windows, la codificación es la de la página de códigos activa de Windows (ANSI). En otras plataformas, es UTF-8, para macOS en forma descompuesta (NFD).

Véase también decodeName().

[static] bool QFile::exists(const QString &fileName)

Devuelve true si el archivo especificado por fileName existe; en caso contrario devuelve false.

bool QFile::exists() const

Devuelve true si el archivo especificado por fileName() existe; en caso contrario devuelve false.

Véase también fileName() y setFileName().

[override virtual] QString QFile::fileName() const

Reimplementa: QFileDevice::fileName() const.

Devuelve el nombre del fichero tal y como fue establecido por setFileName(), rename(), o por los constructores QFile.

Véase también setFileName(), rename(), y QFileInfo::fileName().

[since 6.0] std::filesystem::path QFile::filesystemFileName() const

Devuelve fileName() como std::filesystem::path.

Esta función se introdujo en Qt 6.0.

[since 6.3] std::filesystem::path QFile::filesystemSymLinkTarget() const

Devuelve symLinkTarget() como std::filesystem::path.

Esta función se introdujo en Qt 6.3.

[static, since 6.3] std::filesystem::path QFile::filesystemSymLinkTarget(const std::filesystem::path &fileName)

Devuelve symLinkTarget() como std::filesystem::path de fileName.

Esta función se introdujo en Qt 6.3.

bool QFile::link(const QString &linkName)

Crea un enlace llamado linkName que apunta al archivo especificado actualmente por fileName(). Lo que es un enlace depende del sistema de archivos subyacente (ya sea un acceso directo en Windows o un enlace simbólico en Unix). Devuelve true si tiene éxito; en caso contrario devuelve false.

Esta función no sobrescribirá una entidad ya existente en el sistema de ficheros; en este caso, link() devolverá false y configurará error() para que devuelva RenameError.

Véase también setFileName().

[since 6.0] bool QFile::link(const std::filesystem::path &newName)

Esta función se introdujo en Qt 6.0.

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

Crea un enlace llamado linkName que apunta al archivo fileName. Lo que es un enlace depende del sistema de archivos subyacente (ya sea un acceso directo en Windows o un enlace simbólico en Unix). Devuelve true si tiene éxito; en caso contrario devuelve false.

Véase también link().

bool QFile::moveToTrash()

Mueve el fichero especificado por fileName() a la papelera. Devuelve true si tiene éxito, y establece fileName() a la ruta en la que se puede encontrar el archivo dentro de la papelera; en caso contrario devuelve false.

El tiempo que tarda en ejecutarse esta función es independiente del tamaño del fichero que se está tirando a la papelera. Si se llama a esta función en un directorio, puede ser proporcional al número de ficheros que se estén tirando a la papelera. Si el fileName() actual apunta a un enlace simbólico, esta función moverá el enlace a la papelera, posiblemente rompiéndolo, no el objetivo del enlace.

Esta función utiliza las APIs de Windows y macOS para realizar el trashing en esos dos sistemas operativos. En otros casos (sistemas Unix), esta función implementa la especificación FreeDesktop.org Trash versión 1.0.

Véase también supportsMoveToTrash(), remove(), y QDir::remove().

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

Mueve el archivo especificado por fileName a la papelera. Devuelve true si tiene éxito, y establece pathInTrash (si se proporciona) a la ruta en la que el archivo se puede encontrar dentro de la papelera; de lo contrario devuelve false.

El tiempo que tarda esta función en ejecutarse es independiente del tamaño del fichero que se está tirando a la papelera. Si se llama a esta función en un directorio, puede ser proporcional al número de ficheros que se estén tirando a la papelera. Si el fileName() actual apunta a un enlace simbólico, esta función moverá el enlace a la papelera, posiblemente rompiéndolo, no el objetivo del enlace.

Esta función utiliza las APIs de Windows y macOS para realizar el trashing en esos dos sistemas operativos. En otros casos (sistemas Unix), esta función implementa la especificación FreeDesktop.org Trash versión 1.0.

[override virtual] bool QFile::open(QIODeviceBase::OpenMode mode)

Reimplementa: QIODevice::open(modo QIODeviceBase::OpenMode).

Abre el archivo utilizando las banderas mode, devolviendo true si tiene éxito; en caso contrario devuelve false.

Las banderas para mode deben incluir QIODeviceBase::ReadOnly, WriteOnly, o ReadWrite. También puede tener banderas adicionales, como Text y Unbuffered.

Véase también QT_USE_NODISCARD_FILE_OPEN y setFileName().

[since 6.3] bool QFile::open(QIODeviceBase::OpenMode mode, QFileDevice::Permissions permissions)

Si el fichero no existe y mode implica crearlo, se crea con el permissions especificado.

En los sistemas POSIX, los permisos reales dependen del valor de umask.

En Windows, los permisos se emulan mediante ACL. Estas ACLs pueden estar en orden no canónico cuando al grupo se le conceden menos permisos que a otros. Los archivos y directorios con tales permisos generarán advertencias cuando se abra la pestaña Seguridad del cuadro de diálogo Propiedades. Conceder al grupo todos los permisos concedidos a los demás evita dichas advertencias.

Esta función se introdujo en Qt 6.3.

Véase también QIODevice::OpenMode, setFileName(), y QT_USE_NODISCARD_FILE_OPEN.

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

Abre el manejador de archivo existente fh en el mode dado. handleFlags puede usarse para especificar opciones adicionales. Devuelve true si tiene éxito; en caso contrario devuelve false.

Ejemplo:

#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();
}

Cuando un QFile es abierto usando esta función, el comportamiento de close() es controlado por la bandera AutoCloseHandle. Si se especifica AutoCloseHandle, y esta función tiene éxito, entonces al llamar a close() se cierra el handle adoptado. En caso contrario, close() no cierra el fichero, sino que sólo lo vacía.

Advertencia:

1. Si fh no se refiere a un archivo normal, por ejemplo, es stdin, stdout, o stderr, es posible que no pueda seek(). size() devuelve 0 en esos casos. Consulte QIODevice::isSequential() para obtener más información.
2. Dado que esta función abre el archivo sin especificar el nombre del archivo, no puede utilizar QFile con QFileInfo.

Nota para la plataforma Windows

fh debe abrirse en modo binario (es decir, la cadena de modo debe contener 'b', como en "rb" o "wb") cuando se accede a archivos y otros dispositivos de acceso aleatorio. Qt traducirá los caracteres de fin de línea si pasas QIODevice::Text a mode. Los dispositivos secuenciales, como stdin y stdout, no se ven afectados por esta limitación.

Para poder utilizar los flujos stdin, stdout y stderr en la consola, es necesario habilitar la compatibilidad con aplicaciones de consola. Para ello, añada la siguiente declaración al archivo de proyecto de su aplicación:

CONFIG += console

Véase también close() y QT_USE_NODISCARD_FILE_OPEN.

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

Abre el descriptor de archivo existente fd en la dirección mode. handleFlags puede utilizarse para especificar opciones adicionales. Devuelve true si tiene éxito; en caso contrario devuelve false.

Cuando se abre un QFile utilizando esta función, el comportamiento de close() está controlado por la bandera AutoCloseHandle. Si se especifica AutoCloseHandle, y esta función tiene éxito, entonces al llamar a close() se cierra el handle adoptado. En caso contrario, close() no cierra el fichero, sino que sólo lo vacía.

Véase también close() y QT_USE_NODISCARD_FILE_OPEN.

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

Reimplementa: QFileDevice::permissions() const.

Ver también setPermissions().

[static] QFileDevice::Permissions QFile::permissions(const QString &fileName)

Devuelve la combinación completa OR-ed together de QFile::Permission para fileName.

[static, since 6.0] QFileDevice::Permissions QFile::permissions(const std::filesystem::path &filename)

Esta función se introdujo en Qt 6.0.

bool QFile::remove()

Elimina el archivo especificado por fileName().

Devuelve true si el archivo se ha eliminado correctamente; en caso contrario, devuelve false.

El archivo se cierra antes de ser eliminado, si estaba abierto.

Véase también setFileName().

[static] bool QFile::remove(const QString &fileName)

Elimina el archivo especificado en fileName.

Devuelve true si el archivo se ha eliminado correctamente; en caso contrario, devuelve false.

Véase también remove().

bool QFile::rename(const QString &newName)

Cambia el nombre del archivo especificado por fileName() a newName. Devuelve true si tiene éxito; en caso contrario, devuelve false.

Si ya existe un archivo con el nombre newName, rename() devuelve false (es decir, QFile no lo sobrescribirá).

El fichero se cierra antes de renombrarlo.

Si la operación de renombrado falla, Qt intentará copiar el contenido de este archivo a newName, y luego eliminará este archivo, manteniendo sólo newName. Si esa operación de copia falla o este archivo no puede ser eliminado, el archivo de destino newName es eliminado para restaurar el estado anterior.

Véase también setFileName().

[since 6.0] bool QFile::rename(const std::filesystem::path &newName)

Esta función se introdujo en Qt 6.0.

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

Cambia el nombre del archivo oldName a newName. Devuelve true si tiene éxito; en caso contrario devuelve false.

Si ya existe un archivo con el nombre newName, rename() devuelve false (es decir, QFile no lo sobrescribirá).

Véase también rename().

[override virtual] bool QFile::resize(qint64 sz)

Reimplementa: QFileDevice::resize(qint64 sz).

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

Establece fileName al tamaño (en bytes) sz. Devuelve true si el redimensionamiento tiene éxito; false en caso contrario. Si sz es mayor que fileName los nuevos bytes se pondrán a 0, si sz es menor el fichero simplemente se truncará.

Véase también resize().

void QFile::setFileName(const QString &name)

Establece la dirección name del archivo. El nombre puede no tener ruta, tener una ruta relativa o una ruta absoluta.

No llame a esta función si el fichero ya ha sido abierto.

Si el nombre del fichero no tiene ruta o tiene una ruta relativa, la ruta utilizada será la ruta del directorio actual de la aplicación en el momento de la llamada a open( ).

Ejemplo:

QFile file;
QDir::setCurrent("/tmp");
file.setFileName("readme.txt");
QDir::setCurrent("/home");
file.open(QIODevice::ReadOnly);      // opens "/home/readme.txt" under Unix

Tenga en cuenta que el separador de directorios "/" funciona para todos los sistemas operativos soportados por Qt.

Véase también fileName(), QFileInfo, y QDir.

[since 6.0] void QFile::setFileName(const std::filesystem::path &name)

Esta función se introdujo en Qt 6.0.

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

Reimplementa: QFileDevice::setPermissions(QFileDevice::Permisos permissions).

Establece los permisos para el archivo al permissions especificado. Devuelve true si tiene éxito, o false si los permisos no pueden ser modificados.

Véase también permissions() y setFileName().

[static] bool QFile::setPermissions(const QString &fileName, QFileDevice::Permissions permissions)

Establece los permisos del archivo fileName en permissions.

[static, since 6.0] bool QFile::setPermissions(const std::filesystem::path &filename, QFileDevice::Permissions permissionSpec)

Esta función se introdujo en Qt 6.0.

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

Reimplementa: QFileDevice::size() const.

[static, since 6.9] bool QFile::supportsMoveToTrash()

Devuelve true si Qt soporta mover archivos a una papelera (papelera de reciclaje) en el sistema operativo actual usando la función moveToTrash(), false en caso contrario. Tenga en cuenta que el hecho de que esta función devuelva true no implica que moveToTrash() vaya a tener éxito. En particular, esta función no comprueba si el usuario ha desactivado la funcionalidad en su configuración.

Esta función se introdujo en Qt 6.9.

Véase también moveToTrash().

[static] QString QFile::symLinkTarget(const QString &fileName)

Devuelve la ruta absoluta del archivo o directorio al que hace referencia el enlace simbólico (o acceso directo en Windows) especificado por fileName, o devuelve una cadena vacía si fileName no corresponde a un enlace simbólico.

Este nombre no puede representar un archivo existente; es sólo una cadena. QFile::exists() devuelve true si el enlace simbólico apunta a un archivo existente.

QString QFile::symLinkTarget() const

Devuelve la ruta absoluta del archivo o directorio al que apunta un enlace simbólico (o acceso directo en Windows), o una cadena vacía si el objeto no es un enlace simbólico.

Este nombre no puede representar un archivo existente; es sólo una cadena. QFile::exists() devuelve true si el enlace simbólico apunta a un archivo existente.

Véase también fileName() y setFileName().