Rewrite to reflect slight change in semantics for C99, and note a bug

in the standard.  Defer to gettimeofday(2) for error indications.

lib/libc/gen/time.3

@@ -36,7 +36,7 @@
 .\"     @(#)time.3	8.1 (Berkeley) 6/4/93
 .\" $FreeBSD$
 .\"
-.Dd June 4, 1993
+.Dd July 18, 2003
 .Dt TIME 3
 .Os
 .Sh NAME
@@ -54,32 +54,49 @@ The
 function
 returns the value of time in seconds since 0 hours, 0 minutes,
 0 seconds, January 1, 1970, Coordinated Universal Time.
-.Pp
-A copy of the time value may be saved to the area indicated by the
-pointer
-.Fa tloc .
-If
-.Fa tloc
-is a NULL pointer, no value is stored.
-.Pp
-Upon successful completion,
+If an error occurs,
 .Fn time
-returns the value of time.
-Otherwise a value of
-.Pq Po Vt time_t Pc \-1
-is returned and the global variable
-.Va errno
-is set to indicate the error.
+returns the value
+.Po Vt time_t Pc Ns \-1 .
+.Pp
+The return value is also stored in 
+.No \&* Ns Va tloc ,
+provided that
+.Va tloc
+is non-null.
 .Sh ERRORS
-The following error codes may be set in
-.Va errno :
-.Bl -tag -width Er
-.It Bq Er EFAULT
-An argument address referenced invalid memory.
-.El
+The
+.Fn time
+function may fail for any of the reasons described in
+.Xr gettimeofday 2 .
 .Sh SEE ALSO
 .Xr gettimeofday 2 ,
 .Xr ctime 3
+.Sh STANDARDS
+The
+.Nm
+function conforms to
+.St -p1003.1-2001 .
+.Sh BUGS
+Neither
+.St -isoC-99
+nor
+.St -p1003.1-2001
+requires
+.Fn time
+to set
+.Va errno
+on failure; thus, it is impossible for an application to distinguish
+the valid time value \-1 (representing the last UTC second of 1969)
+from the error return value.
+.Pp
+Systems conforming to earlier versions of the C and
+.Tn POSIX
+standards (including older versions of
+.Fx )
+did not set
+.No \&* Ns Va tloc
+in the error case.
 .Sh HISTORY
 A
 .Fn time