From c688fc9f51f15c956b1e9aaeea820882605119de Mon Sep 17 00:00:00 2001 From: Mate Barany Date: Wed, 18 Oct 2023 16:18:38 +0200 Subject: [PATCH] Create class documentation for QNtfsPermissionCheckGuard MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ...and document the related functions as well. Fixes: QTBUG-116350 Change-Id: I038d59f6af46b29e2123bc8b6c24ff4ffea78bbf Reviewed-by: Marc Mutz Reviewed-by: Kai Köhne (cherry picked from commit fa79b56bd82df6852aab6819dc31b359ee7b24e7) Reviewed-by: Qt Cherry-pick Bot --- src/corelib/io/qfile.cpp | 101 +++++++++++++++++++++++ src/corelib/io/qfile.h | 2 +- src/corelib/io/qfilesystemengine_win.cpp | 18 ---- 3 files changed, 102 insertions(+), 19 deletions(-) diff --git a/src/corelib/io/qfile.cpp b/src/corelib/io/qfile.cpp index ec67ca6f483..136906a80d5 100644 --- a/src/corelib/io/qfile.cpp +++ b/src/corelib/io/qfile.cpp @@ -1250,6 +1250,107 @@ qint64 QFile::size() const */ +/*! + \class QNtfsPermissionCheckGuard + \since 6.6 + \inmodule QtCore + \brief The QNtfsPermissionCheckGuard class is a RAII class to manage NTFS + permission checking. + + \ingroup io + + For performance reasons, QFile, QFileInfo, and related classes do not + perform full ownership and permission (ACL) checking on NTFS file systems + by default. During the lifetime of any instance of this class, that + default is overridden and advanced checking is performed. This provides + a safe and easy way to manage enabling and disabling this change to the + default behavior. + + Example: + + \snippet ntfsp.cpp raii + + This class is available only on Windows. + + \section1 qt_ntfs_permission_lookup + + Prior to Qt 6.6, the user had to directly manipulate the global variable + \c qt_ntfs_permission_lookup. However, this was a non-atomic global + variable and as such it was prone to data races. + + The variable \c qt_ntfs_permission_lookup is therefore deprecated since Qt + 6.6. +*/ + +/*! + \fn QNtfsPermissionCheckGuard::QNtfsPermissionCheckGuard() + + Creates a guard and calls the function qEnableNtfsPermissionChecks(). +*/ + +/*! + \fn QNtfsPermissionCheckGuard::~QNtfsPermissionCheckGuard() + + Destroys the guard and calls the function qDisableNtfsPermissionChecks(). +*/ + + +/*! + \fn bool qEnableNtfsPermissionChecks() + \since 6.6 + \threadsafe + \relates QNtfsPermissionCheckGuard + + Enables permission checking on NTFS file systems. Returns \c true if the check + was already enabled before the call to this function, meaning that there + are other users. + + This function is only available on Windows and makes the direct + manipulation of \l qt_ntfs_permission_lookup obsolete. + + This is a low-level function, please consider the RAII class + \l QNtfsPermissionCheckGuard instead. + + \note The thread-safety of this function holds only as long as there are no + concurrent updates to \l qt_ntfs_permission_lookup. +*/ + +/*! + \fn bool qDisableNtfsPermissionChecks() + \since 6.6 + \threadsafe + \relates QNtfsPermissionCheckGuard + + Disables permission checking on NTFS file systems. Returns \c true if the + check is disabled, meaning that there are no more users. + + This function is only available on Windows and makes the direct + manipulation of \l qt_ntfs_permission_lookup obsolete. + + This is a low-level function and must (only) be called to match one earlier + call to qEnableNtfsPermissionChecks(). Please consider the RAII class + \l QNtfsPermissionCheckGuard instead. + + \note The thread-safety of this function holds only as long as there are no + concurrent updates to \l qt_ntfs_permission_lookup. +*/ + +/*! + \fn bool qAreNtfsPermissionChecksEnabled() + \since 6.6 + \threadsafe + \relates QNtfsPermissionCheckGuard + + Checks the status of the permission checks on NTFS file systems. Returns + \c true if the check is enabled. + + This function is only available on Windows and makes the direct + manipulation of \l qt_ntfs_permission_lookup obsolete. + + \note The thread-safety of this function holds only as long as there are no + concurrent updates to \l qt_ntfs_permission_lookup. +*/ + QT_END_NAMESPACE #ifndef QT_NO_QOBJECT diff --git a/src/corelib/io/qfile.h b/src/corelib/io/qfile.h index 839a2b51fee..1d18dd55c03 100644 --- a/src/corelib/io/qfile.h +++ b/src/corelib/io/qfile.h @@ -26,7 +26,7 @@ namespace std { QT_BEGIN_NAMESPACE -#ifdef Q_OS_WIN +#if defined(Q_OS_WIN) || defined(Q_QDOC) #if QT_DEPRECATED_SINCE(6,6) QT_DEPRECATED_VERSION_X_6_6("Use QNtfsPermissionCheckGuard RAII class instead.") diff --git a/src/corelib/io/qfilesystemengine_win.cpp b/src/corelib/io/qfilesystemengine_win.cpp index 3abbfa3536d..67378e2b5db 100644 --- a/src/corelib/io/qfilesystemengine_win.cpp +++ b/src/corelib/io/qfilesystemengine_win.cpp @@ -390,12 +390,6 @@ static QBasicAtomicInt qt_ntfs_permission_lookup_v2 = Q_BASIC_ATOMIC_INITIALIZER QT_WARNING_PUSH QT_WARNING_DISABLE_DEPRECATED -/*! - \internal - - Returns true if the check was previously enabled. -*/ - bool qEnableNtfsPermissionChecks() noexcept { return qt_ntfs_permission_lookup_v2.fetchAndAddRelaxed(1) @@ -403,12 +397,6 @@ QT_IF_DEPRECATED_SINCE(6, 6, /*nothing*/, + qt_ntfs_permission_lookup) != 0; } -/*! - \internal - - Returns true if the check is disabled, i.e. there are no more users. -*/ - bool qDisableNtfsPermissionChecks() noexcept { return qt_ntfs_permission_lookup_v2.fetchAndSubRelaxed(1) @@ -416,12 +404,6 @@ QT_IF_DEPRECATED_SINCE(6, 6, /*nothing*/, + qt_ntfs_permission_lookup) == 1; } -/*! - \internal - - Returns true if the check is enabled. -*/ - bool qAreNtfsPermissionChecksEnabled() noexcept { return qt_ntfs_permission_lookup_v2.loadRelaxed()