From 969d3d2633311bfbc26abc07706f914daf4e29fc Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Kristian=20K=C3=B6hntopp?= <kk@php.net>
Date: Tue, 15 Aug 2000 20:22:01 +0000
Subject: [PATCH] Added some clarification regarding filetimes as some people
 in de.comp.lang.php started building last modification time footers based on
 ctimes.

git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@30331 c90b9560-bf6c-de11-be94-00142212c4b1
---
 functions/filesystem.xml | 30 ++++++++++++++++++++++++++++++
 1 file changed, 30 insertions(+)

diff --git a/functions/filesystem.xml b/functions/filesystem.xml
index 154cacfba7..7b43e6f85e 100644
--- a/functions/filesystem.xml
+++ b/functions/filesystem.xml
@@ -690,6 +690,17 @@ $fcontents = join( '', file( 'http://www.php.net' ) );
      The results of this function are cached. See
      <function>clearstatcache</function> for more details.
     </simpara>
+    
+    <simpara>
+     Note: The atime of a file is supposed to change whenever
+     the data blocks of a file are being read. This can be
+     costly performancewise when an appliation regularly
+     accesses a very large number of files or directories. Some
+     Unix filesystems can be mounted with atime updates disabled
+     to increase the performance of such applications; USENET
+     news spools are a common example. On such filesystems
+     this function will be useless.
+    </simpara>
 
    </refsect1>
   </refentry>
@@ -716,6 +727,19 @@ $fcontents = join( '', file( 'http://www.php.net' ) );
      The results of this function are cached. See
      <function>clearstatcache</function> for more details.
     </para>
+    <para>Note: In most Unix filesystem, a file is considered
+     changed, when it's Inode data is changed, that is, when
+     the permissions, the owner, the group or other metadata
+     from the Inode is written to. See also 
+     <function>filemtime()</function> (this is what you want to use
+     when you want to create "Last Modified" footers on web pages) and 
+     <function>fileatime()</function>.
+    </para>
+    <para>Note: In some Unix texts the ctime of a file is being
+     referred to as the creation time of the file. This is wrong.
+     There is no creation time for Unix files in most Unix 
+     filesystems.
+    </para>
    </refsect1>
   </refentry>
 
@@ -798,6 +822,12 @@ $fcontents = join( '', file( 'http://www.php.net' ) );
      The results of this function are cached. See
      <function>clearstatcache</function> for more details.
     </para>
+    <para>Note: This function returns the time when the data
+     blocks of a file were being written to, that is, the time
+     when the content of the file was changed. Use
+     <function>date()</function> on the result of this function
+     to get a printable modification date for use in page footers.
+    </para>
    </refsect1>
   </refentry>