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