Merge branch 'egil/file-info-opt-utc/OTP-7687'

* egil/file-info-opt-utc/OTP-7687: (39 commits)
  Remove time_t specific test in prim_file_SUITE
  Update prim_file.beam and prim_zip.beam
  Add types for posixtime_to_universaltime and the reverse
  Set BASEYEAR to 1902
  Set lower limit of years handled to 1601
  Emulate localtime, gmtime and mktime to enable negative time_t
  Document file:*_file_info/2
  Fix compiler warning in unix_efile.c
  Change name of bif universaltime_to_seconds/1
  Change options to prim_file:*_file_info/*
  Remove dead code
  Catch errors from prim_file:*_file_info
  Testcase for utc <-> seconds conversion
  Fix negative time in seconds_to_universaltime/1
  Remove OS taint from datetime conversion
  Add utc <-> seconds conversions bifs
  Let prim_file validate ctime in file_info
  Teach #file_info spec unix epochs for file times
  Add file_info_opt tests in prim_file_SUITE
  unix_efile: Zero is a valid number in utime
  ...

Conflicts:
	erts/emulator/beam/erl_time_sup.c
	erts/emulator/sys/win32/erl_win_sys.h
	erts/emulator/sys/win32/sys_time.c

1 files changed, 40 insertions, 12 deletions

diff --git a/lib/kernel/doc/src/file.xml b/lib/kernel/doc/src/file.xml
index 719cbba2b8..772eff13cc 100644
--- a/lib/kernel/doc/src/file.xml
+++ b/lib/kernel/doc/src/file.xml
@@ -150,6 +150,9 @@
       <name name="mode"/>
     </datatype>
     <datatype>
+      <name name="file_info_option"/>
+    </datatype>
+    <datatype>
       <name name="sendfile_option"/>
     </datatype>
    </datatypes>
@@ -412,7 +415,7 @@
       <name>file_info(Filename) -> {ok, FileInfo} | {error, Reason}</name>
       <fsummary>Get information about a file (deprecated)</fsummary>
       <desc>
-        <p>This function is obsolete. Use <c>read_file_info/1</c>
+        <p>This function is obsolete. Use <c>read_file_info/1,2</c>
           instead.</p>
       </desc>
     </func>
@@ -1189,6 +1192,7 @@
     </func>
     <func>
       <name name="read_file_info" arity="1"/>
+      <name name="read_file_info" arity="2"/>
       <fsummary>Get information about a file</fsummary>
       <desc>
         <p>Retrieves information about a file. Returns
@@ -1200,6 +1204,20 @@
           from which the function is called:</p>
         <code type="none">
 -include_lib("kernel/include/file.hrl").</code>
+		<p>The time type returned in <c>atime</c>, <c>mtime</c> and <c>ctime</c>
+			is dependent on the time type set in <c>Opts :: {time, Type}</c>.
+			Type <c>local</c> will return local time, <c>universal</c> will
+			return universal time and <c>posix</c> will return seconds since
+			or before unix time epoch which is 1970-01-01 00:00 UTC. 
+			Default is <c>{time, local}</c>.
+		</p> 
+		<note>
+          <p>
+			  Since file times is stored in posix time on most OS it is
+			  faster to query file information with the <c>posix</c> option.
+		  </p> 
+        </note>
+        
         <p>The record <c>file_info</c> contains the following fields.</p>
         <taglist>
           <tag><c>size = integer()</c></tag>
@@ -1214,15 +1232,15 @@
           <item>
             <p>The current system access to the file.</p>
           </item>
-          <tag><c>atime = <seealso marker="#type-date_time">date_time()</seealso></c></tag>
+          <tag><c>atime = <seealso marker="#type-date_time">date_time()</seealso> | integer() </c></tag> 
           <item>
-            <p>The last (local) time the file was read.</p>
+            <p>The last time the file was read.</p>
           </item>
-          <tag><c>mtime = <seealso marker="#type-date_time">date_time()</seealso></c></tag>
+          <tag><c>mtime = <seealso marker="#type-date_time">date_time()</seealso> | integer() </c></tag> 
           <item>
-            <p>The last (local) time the file was written.</p>
+            <p>The last time the file was written.</p>
           </item>
-          <tag><c>ctime = <seealso marker="#type-date_time">date_time()</seealso></c></tag>
+          <tag><c>ctime = <seealso marker="#type-date_time">date_time()</seealso> | integer() </c></tag> 
           <item>
             <p>The interpretation of this time field depends on
               the operating system. On Unix, it is the last time
@@ -1378,9 +1396,11 @@
     </func>
     <func>
       <name name="read_link_info" arity="1"/>
+      <name name="read_link_info" arity="2"/>
       <fsummary>Get information about a link or file</fsummary>
       <desc>
-        <p>This function works like <c>read_file_info/1</c>, except that
+		  <p>This function works like 
+			 <seealso marker="#read_file_info/2">read_file_info/1,2</seealso> except that
           if <c><anno>Name</anno></c> is a symbolic link, information about
           the link will be returned in the <c>file_info</c> record and
           the <c>type</c> field of the record will be set to
@@ -1691,6 +1711,7 @@
     </func>
     <func>
       <name name="write_file_info" arity="2"/>
+      <name name="write_file_info" arity="3"/>
       <fsummary>Change information about a file</fsummary>
       <desc>
         <p>Change file information. Returns <c>ok</c> if successful,
@@ -1701,18 +1722,25 @@
           from which the function is called:</p>
         <code type="none">
 -include_lib("kernel/include/file.hrl").</code>
+		<p>The time type set in <c>atime</c>, <c>mtime</c> and <c>ctime</c>
+			is dependent on the time type set in <c>Opts :: {time, Type}</c>.
+			Type <c>local</c> will interpret the time set as local, <c>universal</c> will
+			interpret it as universal time and <c>posix</c> must be seconds since
+			or before unix time epoch which is 1970-01-01 00:00 UTC.
+			Default is <c>{time, local}</c>.
+		</p>
         <p>The following fields are used from the record, if they are
           given.</p>
         <taglist>
-          <tag><c>atime = <seealso marker="#type-date_time">date_time()</seealso></c></tag>
+          <tag><c>atime = <seealso marker="#type-date_time">date_time()</seealso> | integer()</c></tag>
           <item>
-            <p>The last (local) time the file was read.</p>
+            <p>The last time the file was read.</p>
           </item>
-          <tag><c>mtime = <seealso marker="#type-date_time">date_time()</seealso></c></tag>
+          <tag><c>mtime = <seealso marker="#type-date_time">date_time()</seealso> | integer()</c></tag>
           <item>
-            <p>The last (local) time the file was written.</p>
+            <p>The last time the file was written.</p>
           </item>
-          <tag><c>ctime = <seealso marker="#type-date_time">date_time()</seealso></c></tag>
+          <tag><c>ctime = <seealso marker="#type-date_time">date_time()</seealso> | integer()</c></tag>
           <item>
             <p>On Unix, any value give for this field will be ignored
               (the "ctime" for the file will be set to the current