Index: doc/src/sgml/func.sgml
===================================================================
RCS file: /projects/cvsroot/pgsql/doc/src/sgml/func.sgml,v
retrieving revision 1.276
diff -C3 -r1.276 func.sgml
*** doc/src/sgml/func.sgml	2 Aug 2005 16:11:56 -0000	1.276
--- doc/src/sgml/func.sgml	7 Aug 2005 13:45:47 -0000
***************
*** 5047,5053 ****
         <row>
          <entry><literal><function>current_date</function></literal></entry>
          <entry><type>date</type></entry>
!         <entry>Today's date; see <xref linkend="functions-datetime-current">
          </entry>
          <entry></entry>
          <entry></entry>
--- 5047,5053 ----
         <row>
          <entry><literal><function>current_date</function></literal></entry>
          <entry><type>date</type></entry>
!         <entry>Today's date; see <xref linkend="functions-datetime-current-xact">
          </entry>
          <entry></entry>
          <entry></entry>
***************
*** 5056,5062 ****
         <row>
          <entry><literal><function>current_time</function></literal></entry>
          <entry><type>time with time zone</type></entry>
!         <entry>Time of day; see <xref linkend="functions-datetime-current">
          </entry>
          <entry></entry>
          <entry></entry>
--- 5056,5062 ----
         <row>
          <entry><literal><function>current_time</function></literal></entry>
          <entry><type>time with time zone</type></entry>
!         <entry>Time of day; see <xref linkend="functions-datetime-current-xact">
          </entry>
          <entry></entry>
          <entry></entry>
***************
*** 5065,5071 ****
         <row>
          <entry><literal><function>current_timestamp</function></literal></entry>
          <entry><type>timestamp with time zone</type></entry>
!         <entry>Date and time; see <xref linkend="functions-datetime-current">
          </entry>
          <entry></entry>
          <entry></entry>
--- 5065,5071 ----
         <row>
          <entry><literal><function>current_timestamp</function></literal></entry>
          <entry><type>timestamp with time zone</type></entry>
!         <entry>Date and time; see <xref linkend="functions-datetime-current-xact">
          </entry>
          <entry></entry>
          <entry></entry>
***************
*** 5121,5126 ****
--- 5121,5134 ----
         </row>
  
         <row>
+         <entry><literal><function>gettime</function>()</literal></entry>
+         <entry><type>timestamp with time zone</type></entry>
+         <entry>Current system date and time; see <xref linkend="functions-datetime-current-system"></entry>
+         <entry></entry>
+         <entry></entry>
+        </row>
+ 
+        <row>
          <entry><literal><function>isfinite</function>(<type>timestamp</type>)</literal></entry>
          <entry><type>boolean</type></entry>
          <entry>Test for finite time stamp (not equal to infinity)</entry>
***************
*** 5155,5161 ****
         <row>
          <entry><literal><function>localtime</function></literal></entry>
          <entry><type>time</type></entry>
!         <entry>Time of day; see <xref linkend="functions-datetime-current">
          </entry>
          <entry></entry>
          <entry></entry>
--- 5163,5169 ----
         <row>
          <entry><literal><function>localtime</function></literal></entry>
          <entry><type>time</type></entry>
!         <entry>Time of day; see <xref linkend="functions-datetime-current-xact">
          </entry>
          <entry></entry>
          <entry></entry>
***************
*** 5164,5170 ****
         <row>
          <entry><literal><function>localtimestamp</function></literal></entry>
          <entry><type>timestamp</type></entry>
!         <entry>Date and time; see <xref linkend="functions-datetime-current">
          </entry>
          <entry></entry>
          <entry></entry>
--- 5172,5178 ----
         <row>
          <entry><literal><function>localtimestamp</function></literal></entry>
          <entry><type>timestamp</type></entry>
!         <entry>Date and time; see <xref linkend="functions-datetime-current-xact">
          </entry>
          <entry></entry>
          <entry></entry>
***************
*** 5174,5180 ****
          <entry><literal><function>now</function>()</literal></entry>
          <entry><type>timestamp with time zone</type></entry>
          <entry>Current date and time (equivalent to
!          <function>current_timestamp</function>); see <xref linkend="functions-datetime-current">
          </entry>
          <entry></entry>
          <entry></entry>
--- 5182,5188 ----
          <entry><literal><function>now</function>()</literal></entry>
          <entry><type>timestamp with time zone</type></entry>
          <entry>Current date and time (equivalent to
!          <function>current_timestamp</function>); see <xref linkend="functions-datetime-current-xact">
          </entry>
          <entry></entry>
          <entry></entry>
***************
*** 5183,5189 ****
         <row>
          <entry><literal><function>timeofday</function>()</literal></entry>
          <entry><type>text</type></entry>
!         <entry>Current date and time; see <xref linkend="functions-datetime-current">
          </entry>
          <entry></entry>
          <entry></entry>
--- 5191,5197 ----
         <row>
          <entry><literal><function>timeofday</function>()</literal></entry>
          <entry><type>text</type></entry>
!         <entry>Current system date and time (textual representation); see <xref linkend="functions-datetime-current-system">
          </entry>
          <entry></entry>
          <entry></entry>
***************
*** 5769,5777 ****
      <secondary>current</secondary>
     </indexterm>
  
!    <para>
!     The following functions are available to obtain the current date and/or
!     time:
  <synopsis>
  CURRENT_DATE
  CURRENT_TIME
--- 5777,5788 ----
      <secondary>current</secondary>
     </indexterm>
  
!    <sect3 id="functions-datetime-current-xact">
!     <title>Transaction Time</title>
! 
!     <para>
!      The following functions are available to determine the date/time as at the start of the current transaction:
! 
  <synopsis>
  CURRENT_DATE
  CURRENT_TIME
***************
*** 5811,5818 ****
       </para>
      </note>
  
!    <para>
!     Some examples:
  <screen>
  SELECT CURRENT_TIME;
  <lineannotation>Result: </lineannotation><computeroutput>14:39:53.662522-05</computeroutput>
--- 5822,5829 ----
       </para>
      </note>
  
!     <para>
!      Some examples:
  <screen>
  SELECT CURRENT_TIME;
  <lineannotation>Result: </lineannotation><computeroutput>14:39:53.662522-05</computeroutput>
***************
*** 5829,5882 ****
  SELECT LOCALTIMESTAMP;
  <lineannotation>Result: </lineannotation><computeroutput>2001-12-23 14:39:53.662522</computeroutput>
  </screen>
!    </para>
! 
!    <para>
!     The function <function>now()</function> is the traditional
!     <productname>PostgreSQL</productname> equivalent to
!     <function>CURRENT_TIMESTAMP</function>.
!    </para>
  
!    <para>
!     It is important to know that
!     <function>CURRENT_TIMESTAMP</function> and related functions return
!     the start time of the current transaction; their values do not
!     change during the transaction. This is considered a feature:
!     the intent is to allow a single transaction to have a consistent
!     notion of the <quote>current</quote> time, so that multiple
!     modifications within the same transaction bear the same
!     time stamp.
!    </para>
  
-    <note>
      <para>
!      Other database systems may advance these values more
!      frequently.
      </para>
-    </note>
  
!    <para>
!     There is also the function <function>timeofday()</function> which
!     returns the wall-clock time and advances during transactions.  For
!     historical reasons <function>timeofday()</function> returns a
!     <type>text</type> string rather than a <type>timestamp</type>
!     value:
! <screen>
! SELECT timeofday();
! <lineannotation>Result: </lineannotation><computeroutput>Sat Feb 17 19:07:32.000126 2001 EST</computeroutput>
! </screen>
!    </para>
  
!    <para>
!     All the date/time data types also accept the special literal value
!     <literal>now</literal> to specify the current date and time.  Thus,
!     the following three all return the same result:
! <programlisting>
! SELECT CURRENT_TIMESTAMP;
! SELECT now();
! SELECT TIMESTAMP 'now';  -- incorrect for use with DEFAULT
! </programlisting>
!    </para>
  
      <tip>
       <para>
--- 5840,5886 ----
  SELECT LOCALTIMESTAMP;
  <lineannotation>Result: </lineannotation><computeroutput>2001-12-23 14:39:53.662522</computeroutput>
  </screen>
!     </para>
  
!     <para>
!      The function <function>now()</function> is the traditional
!      <productname>PostgreSQL</productname> equivalent to
!      <function>CURRENT_TIMESTAMP</function>.
!     </para>
  
      <para>
!      It is important to know that
!      <function>CURRENT_TIMESTAMP</function> and related functions return
!      the start time of the current transaction; their values do not
!      change during the transaction. This is considered a feature:
!      the intent is to allow a single transaction to have a consistent
!      notion of the <quote>current</quote> time, so that multiple
!      modifications within the same transaction bear the same
!      time stamp.
      </para>
  
!     <note>
!      <para>
!       Other database systems may advance these values more
!       frequently.
!      </para>
!     </note>
  
!     <para>
!      If you want to access the current time without regard to the current
!      transaction, refer to the functions in <xref linkend="functions-datetime-current-system">.
!     </para>
! 
!     <para>
!      All the date/time data types also accept the special literal value
!      <literal>now</literal> to specify the current date and time.  Thus,
!      the following three all return the same result:
!  <programlisting>
!  SELECT CURRENT_TIMESTAMP;
!  SELECT now();
!  SELECT TIMESTAMP 'now';  -- incorrect for use with DEFAULT
!  </programlisting>
!     </para>
  
      <tip>
       <para>
***************
*** 5890,5895 ****
--- 5894,5934 ----
        behavior of defaulting to the time of row insertion.
       </para>
      </tip>
+    </sect3>
+ 
+    <sect3 id="functions-datetime-current-system">
+     <title>System Time</title>
+ 
+     <para>
+      The following functions are available to determine the current system time directly:
+ 
+ <synopsis>
+ gettime()
+ timeofday()
+ </synopsis>
+     </para>
+ 
+     <para>
+      <function>gettime()</function> returns type <type>timestamp with time zone</type> at the maximum available precision.
+     </para>
+ 
+     <para>
+      <function>timeofday()</function> returns a long textual representation of the current time type <type>text</type>.
+     </para>
+ 
+     <para>
+      Usage examples:
+ <screen>
+ SELECT gettime();
+ <lineannotation>Result: </lineannotation><computeroutput>2005-08-07 21:22:43.495743+10</computeroutput>
+ 
+ SELECT timeofday();
+ <lineannotation>Result: </lineannotation><computeroutput>Sat Feb 17 19:07:32.000126 2001 EST</computeroutput>
+ </screen>
+     </para>
+ 
+    </sect3>
+ 
    </sect2>
   </sect1>
  