QFile Class

Documentation des fonctions membres

QFile::QFile()

Crée un objet QFile.

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

Crée un nouvel objet fichier avec l'parent on fournie.

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

Crée un nouvel objet fichier pour représenter le fichier dont l'name on est indiquée.

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

Crée un nouvel objet fichier pour représenter le fichier dont l'name est indiquée.

Cette fonction a été introduite dans Qt 6.0.

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

Crée un nouvel objet fichier avec l'parent tion fournie pour représenter le fichier dont l'name tion est spécifiée.

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

Crée un nouvel objet fichier avec l'parent fournie pour représenter le fichier dont l'name est spécifiée.

Cette fonction a été introduite dans Qt 6.0.

[virtual noexcept] QFile::~QFile()

Détruit l'objet fichier, en le fermant si nécessaire.

bool QFile::copy(const QString &newName, std::optional<QFileDevice::Permissions> perm = std::nullopt)

Copie le fichier nommé « fileName » () vers « newName ».

Ce fichier est fermé avant d'être copié.

Depuis Qt 6.12, les droits d'accès perm peuvent être spécifiés lors de l'appel. S'ils ne sont pas fournis, les droits d'accès du fichier d'origine sont copiés. Le nouveau fichier sera créé avec les droits d'accès indiqués.

Si le fichier copié est un lien symbolique (symlink), c’est le fichier auquel il fait référence qui est copié, et non le lien lui-même. À l’exception des droits d’accès, aucune autre métadonnée du fichier n’est copiée.

Renvoie ` true ` en cas de succès ; sinon, renvoie ` false`.

Notez que si un fichier nommé newName existe déjà, copy() renvoie false. Cela signifie que QFile ne le remplacera pas. Cependant, l’opération n’est pas atomique. Il est possible qu’un autre processus crée un fichier nommé newName entre la vérification et la copie. Dans ce cas, le fichier sera remplacé.

Voir également setFileName().

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

Cette fonction a été introduite dans Qt 6.0.

[static] bool QFile::copy(const QString &fileName, const QString &newName, std::optional<QFileDevice::Permissions> perm = std::nullopt)

Copie le fichier nommé « fileName » vers « newName ».

Depuis Qt 6.12, les droits d'accès perm peuvent être spécifiés lors de l'appel. S'ils ne sont pas fournis, les droits d'accès du fichier d'origine sont copiés. Le nouveau fichier est créé avec les droits d'accès indiqués.

Si le fichier copié est un lien symbolique (symlink), c’est le fichier auquel il fait référence qui est copié, et non le lien lui-même. À l’exception des droits d’accès, aucune autre métadonnée du fichier n’est copiée.

Renvoie ` true ` en cas de succès ; sinon, renvoie ` false`.

Notez que si un fichier portant le nom newName existe déjà, copy() renvoie false. Cela signifie que QFile ne le remplacera pas. Cependant, l’opération n’est pas atomique. Il est possible qu’un autre processus crée un fichier portant le nom newName entre la vérification et la copie. Dans ce cas, le fichier sera remplacé.

Voir également rename().

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

Cette fonction effectue l'opération inverse de QFile::encodeName() en utilisant localFileName.

Voir également encodeName().

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

Renvoie la version Unicode de l'localFileName donné. Voir encodeName() pour plus de détails.

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

Convertit fileName en un encodage 8 bits que vous pouvez utiliser dans les API natives. Sous Windows, l'encodage correspond à celui de la page de codes active de Windows (ANSI). Sur les autres plateformes, il s'agit de l'UTF-8, sous forme décomposée (NFD) pour macOS.

Voir également decodeName().

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

Renvoie true si le fichier spécifié par fileName existe ; sinon, renvoie false.

bool QFile::exists() const

Renvoie « true » si le fichier spécifié par ` fileName()` existe ; sinon, renvoie « false ».

Voir également fileName() et setFileName().

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

Réimplémente : ` QFileDevice::fileName()` const.

Renvoie le nom du fichier tel qu’il a été défini par setFileName(), rename() ou par les constructeurs QFile.

Voir également setFileName(), rename() et QFileInfo::fileName().

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

Renvoie fileName() sous la forme std::filesystem::path.

Cette fonction a été introduite dans Qt 6.0.

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

Renvoie symLinkTarget() sous la forme std::filesystem::path.

Cette fonction a été introduite dans Qt 6.3.

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

Renvoie symLinkTarget() sous la forme std::filesystem::path de fileName.

Cette fonction a été introduite dans Qt 6.3.

bool QFile::link(const QString &linkName)

Crée un lien nommé « linkName » pointant vers le fichier actuellement spécifié par « fileName() ». La nature de ce lien dépend du système de fichiers sous-jacent (qu'il s'agisse d'un raccourci sous Windows ou d'un lien symbolique sous Unix). Renvoie « true » en cas de réussite ; sinon, renvoie « false ».

Cette fonction n’écrasera pas une entité déjà existante dans le système de fichiers ; dans ce cas, ` link() ` renverra `false` et définira ` error()` pour qu’elle renvoie ` RenameError`.

Voir aussi setFileName().

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

Cette fonction a été introduite dans Qt 6.0.

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

Crée un lien nommé « linkName » pointant vers le fichier « fileName ». La nature de ce lien dépend du système de fichiers sous-jacent (il peut s'agir d'un raccourci sous Windows ou d'un lien symbolique sous Unix). Renvoie « true » en cas de succès ; sinon, renvoie « false ».

Voir également link().

bool QFile::moveToTrash()

Déplace le fichier spécifié par fileName() vers la corbeille. Renvoie true en cas de succès, et définit fileName() sur le chemin d'accès du fichier dans la corbeille ; sinon, renvoie false.

Le temps d’exécution de cette fonction est indépendant de la taille du fichier envoyé à la corbeille. Si cette fonction est appelée sur un répertoire, ce temps peut être proportionnel au nombre de fichiers envoyés à la corbeille. Si la valeur actuelle de ` fileName()` pointe vers un lien symbolique, cette fonction enverra le lien vers la corbeille, ce qui peut le rendre inaccessible, mais pas la cible du lien.

Cette fonction utilise les API Windows et macOS pour effectuer le déplacement vers la corbeille sur ces deux systèmes d’exploitation. Ailleurs (sur les systèmes Unix), cette fonction implémente la spécification « Trash » de FreeDesktop.org, version 1.0.

Voir également supportsMoveToTrash(), remove() et QDir::remove().

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

Déplace le fichier spécifié par fileName vers la corbeille. Renvoie true en cas de réussite, et définit pathInTrash (si fourni) sur le chemin d’accès du fichier dans la corbeille ; sinon, renvoie false.

Le temps d'exécution de cette fonction est indépendant de la taille du fichier envoyé à la corbeille. Si cette fonction est appelée sur un répertoire, ce temps peut être proportionnel au nombre de fichiers envoyés à la corbeille. Si l'fileName() actuel pointe vers un lien symbolique, cette fonction déplacera le lien vers la corbeille, ce qui risque de le rompre, et non la cible du lien.

Cette fonction utilise les API Windows et macOS pour effectuer le déplacement vers la corbeille sur ces deux systèmes d’exploitation. Ailleurs (sur les systèmes Unix), cette fonction implémente la spécification « Trash » de FreeDesktop.org, version 1.0.

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

Réimplémente : QIODevice::open(mode QIODeviceBase::OpenMode).

Ouvre le fichier à l'aide des indicateurs mode et renvoie true en cas de succès ; sinon, renvoie false.

Les indicateurs pour mode doivent inclure QIODeviceBase::ReadOnly, WriteOnly ou ReadWrite. Ils peuvent également comporter des indicateurs supplémentaires, tels que Text et Unbuffered.

Voir également QT_USE_NODISCARD_FILE_OPEN et setFileName().

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

Si le fichier n'existe pas et que la valeur de ` mode ` implique sa création, il est créé avec les permissions s spécifiées.

Sur les systèmes POSIX, les droits d’accès réels dépendent de la valeur de ` umask`.

Sous Windows, les droits d’accès sont émulés à l’aide d’ACL. Ces ACL peuvent ne pas respecter l’ordre canonique lorsque le groupe se voit accorder moins de droits que les autres. Les fichiers et répertoires dotés de tels droits généreront des avertissements lors de l’ouverture de l’onglet « Sécurité » de la boîte de dialogue « Propriétés ». Accorder au groupe tous les droits accordés aux autres permet d’éviter ces avertissements.

Cette fonction a été introduite dans Qt 6.3.

Voir également QIODevice::OpenMode, setFileName() et QT_USE_NODISCARD_FILE_OPEN.

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

Ouvre le descripteur de fichier existant fh dans l'mode spécifié. La fonction handleFlags peut être utilisée pour spécifier des options supplémentaires. Renvoie true en cas de succès ; sinon, renvoie false.

Exemple :

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

Lorsqu’un fichier QFile est ouvert à l’aide de cette fonction, le comportement de close() est contrôlé par l’indicateur AutoCloseHandle. Si AutoCloseHandle est spécifié et que cette fonction aboutit, l’appel de close() ferme le descripteur adopté. Sinon, close() ne ferme pas réellement le fichier, mais se contente de le vider.

Avertissement :

1. Si ` fh ` ne fait pas référence à un fichier ordinaire (par exemple, s’il s’agit de ` stdin`, ` stdout` ou ` stderr`), il se peut que vous ne puissiez pas appeler ` seek()`. Dans ces cas-là, ` size()` renvoie ` 0 `. Voir ` QIODevice::isSequential()` pour plus d’informations.
2. Comme cette fonction ouvre le fichier sans spécifier de nom de fichier, vous ne pouvez pas utiliser cette QFile avec une QFileInfo.

Remarque concernant la plate-forme Windows

fh doit être ouvert en mode binaire (c'est-à-dire que la chaîne de mode doit contenir un « b », comme dans « rb » ou « wb ») lors de l'accès à des fichiers et à d'autres périphériques à accès aléatoire. Qt convertira les caractères de fin de ligne si vous passez QIODevice::Text à ` mode`. Les périphériques séquentiels, tels que `stdin` et `stdout`, ne sont pas concernés par cette limitation.

Vous devez activer la prise en charge des applications console afin de pouvoir utiliser les flux stdin, stdout et stderr sur la console. Pour ce faire, ajoutez la déclaration suivante au fichier de projet de votre application :

CONFIG += console

Voir également ` close()` et ` QT_USE_NODISCARD_FILE_OPEN`.

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

Ouvre le descripteur de fichier existant fd dans le fichier mode spécifié. La fonction handleFlags peut être utilisée pour spécifier des options supplémentaires. Renvoie true en cas de succès ; sinon, renvoie false.

Lorsqu’un fichier QFile est ouvert à l’aide de cette fonction, le comportement de la fonction close() est contrôlé par l’indicateur AutoCloseHandle. Si AutoCloseHandle est spécifié et que cette fonction aboutit, l’appel de close() ferme le descripteur adopté. Sinon, close() ne ferme pas réellement le fichier, mais se contente de le vider.

Voir également close() et QT_USE_NODISCARD_FILE_OPEN.

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

Réimplémente : QFileDevice::permissions() const.

Voir aussi setPermissions().

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

Renvoie la combinaison complète, via l'opérateur « OR », des QFile::Permission pour fileName.

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

Cette fonction a été introduite dans Qt 6.0.

bool QFile::remove()

Supprime le fichier spécifié par la fonction ` fileName()`.

Renvoie true si le fichier a été supprimé avec succès ; sinon, renvoie false.

Le fichier est fermé avant d'être supprimé, s'il était ouvert.

Voir également setFileName().

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

Supprime le fichier spécifié par l'fileName.

Renvoie ` true ` si le fichier a été supprimé avec succès ; sinon, renvoie ` false`.

Voir également remove().

bool QFile::rename(const QString &newName)

Renomme le fichier actuellement spécifié par ` fileName()` en ` newName`. Renvoie ` true ` en cas de succès ; sinon, renvoie ` false`.

Si un fichier portant le nom newName existe déjà, la fonction rename() renvoie false (c'est-à-dire que QFile ne l'écrasera pas).

Le fichier est fermé avant d’être renommé.

Si l’opération de renommage échoue, Qt tentera de copier le contenu de ce fichier vers newName, puis supprimera ce fichier, ne conservant que newName. Si cette opération de copie échoue ou si ce fichier ne peut pas être supprimé, le fichier de destination newName est supprimé afin de rétablir l’état antérieur.

Voir également setFileName().

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

Cette fonction a été introduite dans Qt 6.0.

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

Renomme le fichier « oldName » en « newName ». Renvoie « true » en cas de succès ; sinon, renvoie « false ».

Si un fichier nommé « newName » existe déjà, la fonction rename() renvoie « false » (c'est-à-dire que « QFile » ne le remplacera pas).

Voir également rename().

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

Réimplémente : QFileDevice::resize(qint64 sz).

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

Définit la taille (en octets) de fileName à sz. Renvoie true si le redimensionnement réussit ; false dans le cas contraire. Si sz est supérieur à la taille actuelle de fileName, les nouveaux octets seront mis à 0 ; si sz est inférieur, le fichier est simplement tronqué.

Voir aussi resize().

void QFile::setFileName(const QString &name)

Définit l'name e du fichier. Le nom peut être un nom sans chemin, un chemin relatif ou un chemin absolu.

N'appelez pas cette fonction si le fichier est déjà ouvert.

Si le nom du fichier ne comporte pas de chemin d'accès ou comporte un chemin d'accès relatif, le chemin utilisé sera celui du répertoire courant de l'application au moment de l'appel à la fonction open().

Exemple :

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

Notez que le séparateur de répertoires « / » fonctionne sur tous les systèmes d’exploitation pris en charge par Qt.

Voir également fileName(), QFileInfo et QDir.

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

Cette fonction a été introduite dans Qt 6.0.

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

Réimplémente : QFileDevice::setPermissions(autorisations QFileDevice::Permissions).

Définit les droits d'accès du fichier selon les permissions spécifiées. Renvoie true en cas de succès, ou false si les droits d'accès ne peuvent pas être modifiés.

Voir également permissions() et setFileName().

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

Définit les droits d'accès du fichier « fileName » sur « permissions ».

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

Cette fonction a été introduite dans Qt 6.0.

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

Réimplémente : QFileDevice::size() const.

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

Renvoie « true » si Qt prend en charge le déplacement de fichiers vers la corbeille (recycle bin) du système d'exploitation actuel à l'aide de la fonction ` moveToTrash()`, et « false » dans le cas contraire. Notez que le fait que cette fonction renvoie « true » n'implique pas que la fonction ` moveToTrash()` aboutira. En particulier, cette fonction ne vérifie pas si l'utilisateur a désactivé cette fonctionnalité dans ses paramètres.

Cette fonction a été introduite dans Qt 6.9.

Voir également moveToTrash().

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

Renvoie le chemin absolu du fichier ou du répertoire auquel renvoie le lien symbolique (ou le raccourci sous Windows) spécifié par ` fileName`, ou renvoie une chaîne vide si ` fileName ` ne correspond pas à un lien symbolique.

Ce nom ne représente pas nécessairement un fichier existant ; il s'agit uniquement d'une chaîne de caractères. La fonction QFile::exists() renvoie true si le lien symbolique pointe vers un fichier existant.

QString QFile::symLinkTarget() const

Renvoie le chemin absolu du fichier ou du répertoire vers lequel pointe un lien symbolique (ou un raccourci sous Windows), ou une chaîne vide si l'objet n'est pas un lien symbolique.

Ce nom ne représente pas nécessairement un fichier existant ; il s'agit uniquement d'une chaîne de caractères. La fonction ` QFile::exists()` renvoie ` true ` si le lien symbolique pointe vers un fichier existant.

Voir également fileName() et setFileName().