Document timeofday(), mention start-of-transaction vs. current-time

semantics, a few other small improvements.

diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml
index e7d825b51811cacebcfa7dfbe45f0829b7ecfc88..de7ef9c0324a9fde7b8691258b654b5c40648070 100644 (file)
--- a/doc/src/sgml/func.sgml
+++ b/doc/src/sgml/func.sgml
@@ -1,4 +1,4 @@
-
+
 
 
  Functions and Operators
@@ -2197,6 +2197,17 @@ reasonable at all for that matter.
    
        
 
+       
+   timeofday()
+   text
+   
+    returns high-precision date and time; see also 
+    linkend="functions-datetime-current">below
+   
+   timeofday()
+   Wed Feb 21 17:01:13.000126 2001 EST
+       
+
        
    timestamp(date)
    timestamp
@@ -2627,7 +2638,8 @@ SELECT date_trunc('year', TIMESTAMP '2001-02-16 20:38:40');
    Current Date/Time
 
    
-    The following functions are available to select the current date and/or time:
+    The following functions are available to obtain the current date and/or
+    time:
 
 CURRENT_TIME
 CURRENT_DATE
@@ -2641,13 +2653,13 @@ CURRENT_TIMESTAMP
    
 
 SELECT CURRENT_TIME;
-19:07:13
+19:07:32
 
 SELECT CURRENT_DATE;
 2001-02-17
 
 SELECT CURRENT_TIMESTAMP;
-2001-02-17 19:07:32+00
+2001-02-17 19:07:32-05
 
    
 
@@ -2655,9 +2667,42 @@ SELECT CURRENT_TIMESTAMP;
     The function now() is the traditional
     Postgres equivalent to
     CURRENT_TIMESTAMP.
-    Postgres furthermore has special
-    date/time constants that can be used to specify the
-    current time.  The following three all return the same result:
+   
+
+   
+    There is also timeofday(), which returns current
+    time to higher precision than the CURRENT_TIMESTAMP
+    family does:
+   
+
+   
+
+SELECT timeofday();
+ Sat Feb 17 19:07:32.000126 2001 EST
+
+   
+
+   
+    timeofday() uses the operating system call
+    gettimeofday(2), which may have resolution as
+    good as microseconds (depending on your platform); the other functions
+    rely on time(2) which is restricted to one-second
+    resolution.  For historical reasons, timeofday()
+    returns its result as a text string rather than a timestamp value.
+   
+
+   
+    It is quite important to realize that
+    CURRENT_TIMESTAMP and related functions all return
+    the time as of the start of the current transaction; their values do not
+    increment while a transaction is running.  But
+    timeofday() returns the actual current time.
+   
+
+   
+    All the date/time datatypes also accept the special literal value
+    now to specify the current date and time.  Thus,
+    the following three all return the same result:
 
 SELECT CURRENT_TIMESTAMP;
 SELECT now();
@@ -2666,11 +2711,13 @@ SELECT TIMESTAMP 'now';
     
      
       You do not want to use the third form when specifying a DEFAULT
-      value when creating a table.  The system will immediately
-      evaluate the constant, thus when the default value is needed,
+      value while creating a table.  The system will convert now
+      to a timestamp as soon as the constant is parsed, so that when
+      the default value is needed,
       the time of the table creation would be used!  The first two
       forms will not be evaluated until the default value is used,
-      because they are function calls.
+      because they are function calls.  Thus they will give the desired
+      behavior of defaulting to the time of row insertion.