Introduce QFileInfo::birthTime and metadataChangeTime

[ChangeLog][QtCore][QFileInfo] Deprecated created() because it could
return one of three different file times depending on the OS and
filesystem type, without the ability to determine which one is which. It
is replaced by metadataChangeTime() and birthTime().

[ChangeLog][QtCore][QFileInfo] Added QFileInfo::metadataChangeTime(),
which returns the time the file's metadata was last changed, if it is
known, and falling back to the same value as lastModified() otherwise.
On Unix systems, this corresponds to the file's ctime.

[ChangeLog][QtCore][QFileInfo] Added QFileInfo::birthTime(), which
returns the file's birth time if it is known, an invalid QDateTime
otherwise. This function is supported on Windows and on some Unix
systems.

Change-Id: I0031aa609e714ae983c3fffd1467bd8b3e3a593d
Reviewed-by: Lars Knoll <lars.knoll@qt.io>

1 files changed, 40 insertions, 10 deletions

diff --git a/src/corelib/io/qfileinfo.cpp b/src/corelib/io/qfileinfo.cpp
index 77349d511d..bb4eb5aeb2 100644
--- a/src/corelib/io/qfileinfo.cpp
+++ b/src/corelib/io/qfileinfo.cpp
@@ -1300,28 +1300,58 @@ qint64 QFileInfo::size() const
     return d->fileSize;
 }
 
+#if QT_DEPRECATED_SINCE(5, 10)
 /*!
-    Returns the date and local time when the file was created.
+    \deprecated
 
-    On most Unix systems, this function returns the time of the last
-    status change. A status change occurs when the file is created,
-    but it also occurs whenever the user writes or sets inode
-    information (for example, changing the file permissions).
+    Returns the date and time when the file was created, the time its metadata
+    was last changed or the time of last modification, whichever one of the
+    three is available (in that order).
 
-    If neither creation time nor "last status change" time are not
-    available, returns the same as lastModified().
+    This function is deprecated. Instead, use the birthTime() function to get
+    the time the file was created, metadataChangeTime() to get the time its
+    metadata was last changed, or lastModified() to get the time it was last modified.
 
-    \sa lastModified(), lastRead()
+    \sa birthTime(), metadataChangeTime(), lastModified(), lastRead()
 */
 QDateTime QFileInfo::created() const
 {
     return fileTime(QFile::FileCreationTime);
 }
+#endif
+
+/*!
+    \since 5.10
+    Returns the date and time when the file was created / born.
+
+    If the file birth time is not available, this function returns an invalid
+    QDateTime.
+
+    \sa lastModified(), lastRead(), metadataChangeTime()
+*/
+QDateTime QFileInfo::birthTime() const
+{
+    return fileTime(QFile::FileCreationTime);
+}
+
+/*!
+    \since 5.10
+    Returns the date and time when the file metadata was changed. A metadata
+    change occurs when the file is created, but it also occurs whenever the
+    user writes or sets inode information (for example, changing the file
+    permissions).
+
+    \sa lastModified(), lastRead()
+*/
+QDateTime QFileInfo::metadataChangeTime() const
+{
+    return fileTime(QFile::FileCreationTime);
+}
 
 /*!
     Returns the date and local time when the file was last modified.
 
-    \sa created(), lastRead(), fileTime()
+    \sa birthTime(), lastRead(), metadataChangeTime(), fileTime()
 */
 QDateTime QFileInfo::lastModified() const
 {
@@ -1334,7 +1364,7 @@ QDateTime QFileInfo::lastModified() const
     On platforms where this information is not available, returns the
     same as lastModified().
 
-    \sa created(), lastModified(), fileTime()
+    \sa birthTime(), lastModified(), metadataChangeTime(), fileTime()
 */
 QDateTime QFileInfo::lastRead() const
 {