From ffbc2d3dc06017959167feecd60b66891c3b2c7b Mon Sep 17 00:00:00 2001
From: Kai Koehne <kai.koehne@theqtcompany.com>
Date: Wed, 19 Aug 2015 14:56:08 +0200
Subject: Doc: Mention Windows limitations in QFileInfo permission methods
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The limitation is already mentioned in the class documentation, but
IMO is severe enough to be highlighted in the documentation of the
respective methods, too.

Change-Id: I16c68eb41ab9d3a7698d7ef06f747cfd98a8aaff
Reviewed-by: Oswald Buddenhagen <oswald.buddenhagen@theqtcompany.com>
Reviewed-by: Topi Reiniö <topi.reinio@digia.com>
---
 src/corelib/io/qfileinfo.cpp | 16 +++++++++++++++-
 1 file changed, 15 insertions(+), 1 deletion(-)

(limited to 'src/corelib/io')

diff --git a/src/corelib/io/qfileinfo.cpp b/src/corelib/io/qfileinfo.cpp
index 8a86ec5858..51b39b1114 100644
--- a/src/corelib/io/qfileinfo.cpp
+++ b/src/corelib/io/qfileinfo.cpp
@@ -263,6 +263,7 @@ QDateTime &QFileInfoPrivate::getFileTime(QAbstractFileEngine::FileTime request)
     groupId(). You can examine a file's permissions and ownership in a
     single statement using the permission() function.
 
+    \target NTFS permissions
     \note On NTFS file systems, ownership and permissions checking is
     disabled by default for performance reasons. To enable it,
     include the following line:
@@ -893,6 +894,9 @@ QDir QFileInfo::absoluteDir() const
 /*!
     Returns \c true if the user can read the file; otherwise returns \c false.
 
+    \note If the \l{NTFS permissions} check has not been enabled, the result
+    on Windows will merely reflect whether the file exists.
+
     \sa isWritable(), isExecutable(), permission()
 */
 bool QFileInfo::isReadable() const
@@ -911,6 +915,9 @@ bool QFileInfo::isReadable() const
 /*!
     Returns \c true if the user can write to the file; otherwise returns \c false.
 
+    \note If the \l{NTFS permissions} check has not been enabled, the result on
+    Windows will merely reflect whether the file is marked as Read Only.
+
     \sa isReadable(), isExecutable(), permission()
 */
 bool QFileInfo::isWritable() const
@@ -1137,7 +1144,8 @@ QString QFileInfo::readLink() const
     returned.
 
     This function can be time consuming under Unix (in the order of
-    milliseconds).
+    milliseconds). On Windows, it will return an empty string unless
+    the \l{NTFS permissions} check has been enabled.
 
     \sa ownerId(), group(), groupId()
 */
@@ -1217,6 +1225,9 @@ uint QFileInfo::groupId() const
     On systems where files do not have permissions this function
     always returns \c true.
 
+    \note The result might be inaccurate on Windows if the
+    \l{NTFS permissions} check has not been enabled.
+
     Example:
     \snippet code/src_corelib_io_qfileinfo.cpp 10
 
@@ -1240,6 +1251,9 @@ bool QFileInfo::permission(QFile::Permissions permissions) const
 /*!
     Returns the complete OR-ed together combination of
     QFile::Permissions for the file.
+
+    \note The result might be inaccurate on Windows if the
+    \l{NTFS permissions} check has not been enabled.
 */
 QFile::Permissions QFileInfo::permissions() const
 {
-- 
cgit v1.2.3