include/QtCore/qfile.h

0001 // Copyright (C) 2020 The Qt Company Ltd.
0002 // Copyright (C) 2016 Intel Corporation.
0003 // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR LGPL-3.0-only OR GPL-2.0-only OR GPL-3.0-only
0004 // Qt-Security score:significant reason:default
0005
0006 #ifndef QFILE_H
0007 #define QFILE_H
0008
0009 #include <QtCore/qfiledevice.h>
0010 #include <QtCore/qstring.h>
0011 #include <stdio.h>
0012
0013 #ifdef open
0014 #error qfile.h must be included before any header file that defines open
0015 #endif
0016
0017 QT_BEGIN_NAMESPACE
0018
0019 #if defined(Q_OS_WIN) || defined(Q_QDOC)
0020
0021 #if QT_DEPRECATED_SINCE(6,6)
0022 QT_DEPRECATED_VERSION_X_6_6("Use QNtfsPermissionCheckGuard RAII class instead.")
0023 Q_CORE_EXPORT extern int qt_ntfs_permission_lookup;      // defined in qfilesystemengine_win.cpp
0024 #endif
0025
0026 Q_CORE_EXPORT bool qEnableNtfsPermissionChecks() noexcept;
0027 Q_CORE_EXPORT bool qDisableNtfsPermissionChecks() noexcept;
0028 Q_CORE_EXPORT bool qAreNtfsPermissionChecksEnabled() noexcept;
0029
0030 class QNtfsPermissionCheckGuard
0031 {
0032     Q_DISABLE_COPY_MOVE(QNtfsPermissionCheckGuard)
0033 public:
0034     Q_NODISCARD_CTOR
0035     QNtfsPermissionCheckGuard()
0036     {
0037         qEnableNtfsPermissionChecks();
0038     }
0039
0040     ~QNtfsPermissionCheckGuard()
0041     {
0042         qDisableNtfsPermissionChecks();
0043     }
0044 };
0045 #endif // Q_OS_WIN
0046
0047 #if QT_CONFIG(cxx17_filesystem)
0048 namespace QtPrivate {
0049 // Both std::filesystem::path and QString (without QT_NO_CAST_FROM_ASCII) can be implicitly
0050 // constructed from string literals so we force the std::fs::path parameter to only
0051 // accept std::fs::path with no implicit conversions.
0052 // ### Qt7: use Q_WEAK_OVERLOAD
0053 template<typename T>
0054 using ForceFilesystemPath = typename std::enable_if_t<std::is_same_v<std::filesystem::path, T>, int>;
0055 }
0056 #endif // QT_CONFIG(cxx17_filesystem)
0057
0058 class QTemporaryFile;
0059 class QFilePrivate;
0060
0061 // ### Qt 7: remove this, and make constructors always explicit.
0062 #if (QT_VERSION >= QT_VERSION_CHECK(6, 9, 0)) || defined(QT_EXPLICIT_QFILE_CONSTRUCTION_FROM_PATH)
0063 #  define QFILE_MAYBE_EXPLICIT explicit
0064 #else
0065 #  define QFILE_MAYBE_EXPLICIT Q_IMPLICIT
0066 #endif
0067
0068 class Q_CORE_EXPORT QFile : public QFileDevice
0069 {
0070 #ifndef QT_NO_QOBJECT
0071     Q_OBJECT
0072 #endif
0073     Q_DECLARE_PRIVATE(QFile)
0074
0075 public:
0076     QFile();
0077     QFILE_MAYBE_EXPLICIT QFile(const QString &name);
0078 #ifdef Q_QDOC
0079     QFILE_MAYBE_EXPLICIT QFile(const std::filesystem::path &name);
0080 #elif QT_CONFIG(cxx17_filesystem)
0081     template<typename T, QtPrivate::ForceFilesystemPath<T> = 0>
0082     QFILE_MAYBE_EXPLICIT QFile(const T &name) : QFile(QtPrivate::fromFilesystemPath(name))
0083     {
0084     }
0085 #endif // QT_CONFIG(cxx17_filesystem)
0086
0087 #ifndef QT_NO_QOBJECT
0088     explicit QFile(QObject *parent);
0089     QFile(const QString &name, QObject *parent);
0090
0091 #ifdef Q_QDOC
0092     QFile(const std::filesystem::path &path, QObject *parent);
0093 #elif QT_CONFIG(cxx17_filesystem)
0094     template<typename T, QtPrivate::ForceFilesystemPath<T> = 0>
0095     QFile(const T &path, QObject *parent) : QFile(QtPrivate::fromFilesystemPath(path), parent)
0096     {
0097     }
0098 #endif // QT_CONFIG(cxx17_filesystem)
0099 #endif // !QT_NO_QOBJECT
0100     ~QFile();
0101
0102     QString fileName() const override;
0103 #if QT_CONFIG(cxx17_filesystem) || defined(Q_QDOC)
0104     std::filesystem::path filesystemFileName() const
0105     { return QtPrivate::toFilesystemPath(fileName()); }
0106 #endif
0107     void setFileName(const QString &name);
0108 #ifdef Q_QDOC
0109     void setFileName(const std::filesystem::path &name);
0110 #elif QT_CONFIG(cxx17_filesystem)
0111     template<typename T, QtPrivate::ForceFilesystemPath<T> = 0>
0112     void setFileName(const T &name)
0113     {
0114         setFileName(QtPrivate::fromFilesystemPath(name));
0115     }
0116 #endif // QT_CONFIG(cxx17_filesystem)
0117
0118 #if defined(Q_OS_DARWIN)
0119     // Mac always expects filenames in UTF-8... and decomposed...
0120     static inline QByteArray encodeName(const QString &fileName)
0121     {
0122         return fileName.normalized(QString::NormalizationForm_D).toUtf8();
0123     }
0124     static QString decodeName(const QByteArray &localFileName)
0125     {
0126         // note: duplicated in qglobal.cpp (qEnvironmentVariable)
0127         return QString::fromUtf8(localFileName).normalized(QString::NormalizationForm_C);
0128     }
0129     static inline QString decodeName(const char *localFileName)
0130     {
0131         return QString::fromUtf8(localFileName).normalized(QString::NormalizationForm_C);
0132     }
0133 #else
0134     static inline QByteArray encodeName(const QString &fileName)
0135     {
0136         return fileName.toLocal8Bit();
0137     }
0138     static QString decodeName(const QByteArray &localFileName)
0139     {
0140         return QString::fromLocal8Bit(localFileName);
0141     }
0142     static inline QString decodeName(const char *localFileName)
0143     {
0144         return QString::fromLocal8Bit(localFileName);
0145     }
0146 #endif
0147
0148     bool exists() const;
0149     static bool exists(const QString &fileName);
0150 #ifdef Q_QDOC
0151     static bool exists(const std::filesystem::path &fileName);
0152 #elif QT_CONFIG(cxx17_filesystem)
0153     template<typename T, QtPrivate::ForceFilesystemPath<T> = 0>
0154     static bool exists(const T &fileName)
0155     {
0156         return exists(QtPrivate::fromFilesystemPath(fileName));
0157     }
0158 #endif // QT_CONFIG(cxx17_filesystem)
0159
0160     QString symLinkTarget() const;
0161     static QString symLinkTarget(const QString &fileName);
0162 #ifdef Q_QDOC
0163     std::filesystem::path filesystemSymLinkTarget() const;
0164     static std::filesystem::path filesystemSymLinkTarget(const std::filesystem::path &fileName);
0165 #elif QT_CONFIG(cxx17_filesystem)
0166     std::filesystem::path filesystemSymLinkTarget() const
0167     {
0168         return QtPrivate::toFilesystemPath(symLinkTarget());
0169     }
0170     template<typename T, QtPrivate::ForceFilesystemPath<T> = 0>
0171     static std::filesystem::path filesystemSymLinkTarget(const T &fileName)
0172     {
0173         return QtPrivate::toFilesystemPath(symLinkTarget(QtPrivate::fromFilesystemPath(fileName)));
0174     }
0175 #endif // QT_CONFIG(cxx17_filesystem)
0176
0177     bool remove();
0178     static bool remove(const QString &fileName);
0179 #ifdef Q_QDOC
0180     static bool remove(const std::filesystem::path &fileName);
0181 #elif QT_CONFIG(cxx17_filesystem)
0182     template<typename T, QtPrivate::ForceFilesystemPath<T> = 0>
0183     static bool remove(const T &fileName)
0184     {
0185         return remove(QtPrivate::fromFilesystemPath(fileName));
0186     }
0187 #endif // QT_CONFIG(cxx17_filesystem)
0188
0189     Q_DECL_PURE_FUNCTION static bool supportsMoveToTrash();
0190     bool moveToTrash();
0191     static bool moveToTrash(const QString &fileName, QString *pathInTrash = nullptr);
0192 #ifdef Q_QDOC
0193     static bool moveToTrash(const std::filesystem::path &fileName, QString *pathInTrash = nullptr);
0194 #elif QT_CONFIG(cxx17_filesystem)
0195     template<typename T, QtPrivate::ForceFilesystemPath<T> = 0>
0196     static bool moveToTrash(const T &fileName, QString *pathInTrash = nullptr)
0197     {
0198         return moveToTrash(QtPrivate::fromFilesystemPath(fileName), pathInTrash);
0199     }
0200 #endif // QT_CONFIG(cxx17_filesystem)
0201
0202     bool rename(const QString &newName);
0203     static bool rename(const QString &oldName, const QString &newName);
0204 #ifdef Q_QDOC
0205     bool rename(const std::filesystem::path &newName);
0206     static bool rename(const std::filesystem::path &oldName,
0207                        const std::filesystem::path &newName);
0208 #elif QT_CONFIG(cxx17_filesystem)
0209     template<typename T, QtPrivate::ForceFilesystemPath<T> = 0>
0210     bool rename(const T &newName)
0211     {
0212         return rename(QtPrivate::fromFilesystemPath(newName));
0213     }
0214     template<typename T, QtPrivate::ForceFilesystemPath<T> = 0>
0215     static bool rename(const T &oldName, const T &newName)
0216     {
0217         return rename(QtPrivate::fromFilesystemPath(oldName),
0218                       QtPrivate::fromFilesystemPath(newName));
0219     }
0220 #endif // QT_CONFIG(cxx17_filesystem)
0221
0222     bool link(const QString &newName);
0223     static bool link(const QString &fileName, const QString &newName);
0224 #ifdef Q_QDOC
0225     bool link(const std::filesystem::path &newName);
0226     static bool link(const std::filesystem::path &fileName,
0227                      const std::filesystem::path &newName);
0228 #elif QT_CONFIG(cxx17_filesystem)
0229     template<typename T, QtPrivate::ForceFilesystemPath<T> = 0>
0230     bool link(const T &newName)
0231     {
0232         return link(QtPrivate::fromFilesystemPath(newName));
0233     }
0234     template<typename T, QtPrivate::ForceFilesystemPath<T> = 0>
0235     static bool link(const T &fileName, const T &newName)
0236     {
0237         return link(QtPrivate::fromFilesystemPath(fileName),
0238                     QtPrivate::fromFilesystemPath(newName));
0239     }
0240 #endif // QT_CONFIG(cxx17_filesystem)
0241
0242 #if QT_CONFIG(temporaryfile)
0243     bool copy(const QString &newName);
0244     static bool copy(const QString &fileName, const QString &newName);
0245 #endif
0246 #ifdef Q_QDOC
0247     bool copy(const std::filesystem::path &newName);
0248     static bool copy(const std::filesystem::path &fileName,
0249                      const std::filesystem::path &newName);
0250 #elif QT_CONFIG(cxx17_filesystem) && QT_CONFIG(temporaryfile)
0251     template<typename T, QtPrivate::ForceFilesystemPath<T> = 0>
0252     bool copy(const T &newName)
0253     {
0254         return copy(QtPrivate::fromFilesystemPath(newName));
0255     }
0256     template<typename T, QtPrivate::ForceFilesystemPath<T> = 0>
0257     static bool copy(const T &fileName, const T &newName)
0258     {
0259         return copy(QtPrivate::fromFilesystemPath(fileName),
0260                     QtPrivate::fromFilesystemPath(newName));
0261     }
0262 #endif // QT_CONFIG(cxx17_filesystem)
0263
0264     QFILE_MAYBE_NODISCARD bool open(OpenMode flags) override;
0265     QFILE_MAYBE_NODISCARD bool open(OpenMode flags, Permissions permissions);
0266     QFILE_MAYBE_NODISCARD bool open(FILE *f, OpenMode ioFlags, FileHandleFlags handleFlags=DontCloseHandle);
0267     QFILE_MAYBE_NODISCARD bool open(int fd, OpenMode ioFlags, FileHandleFlags handleFlags=DontCloseHandle);
0268
0269     qint64 size() const override;
0270
0271     bool resize(qint64 sz) override;
0272     static bool resize(const QString &filename, qint64 sz);
0273
0274     Permissions permissions() const override;
0275     static Permissions permissions(const QString &filename);
0276     bool setPermissions(Permissions permissionSpec) override;
0277     static bool setPermissions(const QString &filename, Permissions permissionSpec);
0278 #ifdef Q_QDOC
0279     static Permissions permissions(const std::filesystem::path &filename);
0280     static bool setPermissions(const std::filesystem::path &filename, Permissions permissionSpec);
0281 #elif QT_CONFIG(cxx17_filesystem)
0282     template<typename T,  QtPrivate::ForceFilesystemPath<T> = 0>
0283     static Permissions permissions(const T &filename)
0284     {
0285         return permissions(QtPrivate::fromFilesystemPath(filename));
0286     }
0287     template<typename T, QtPrivate::ForceFilesystemPath<T> = 0>
0288     static bool setPermissions(const T &filename, Permissions permissionSpec)
0289     {
0290         return setPermissions(QtPrivate::fromFilesystemPath(filename), permissionSpec);
0291     }
0292 #endif // QT_CONFIG(cxx17_filesystem)
0293
0294 protected:
0295 #ifdef QT_NO_QOBJECT
0296     QFile(QFilePrivate &dd);
0297 #else
0298     QFile(QFilePrivate &dd, QObject *parent = nullptr);
0299 #endif
0300
0301 private:
0302     friend class QTemporaryFile;
0303     Q_DISABLE_COPY(QFile)
0304 };
0305
0306 QT_END_NAMESPACE
0307
0308 #endif // QFILE_H