.\" SUCH DAMAGE.
.\"
.\" @(#)time.3 8.1 (Berkeley) 6/4/93
-.\" $FreeBSD: src/lib/libc/gen/time.3,v 1.11 2001/10/01 16:08:51 ru Exp $
+.\" $FreeBSD: src/lib/libc/gen/time.3,v 1.13 2004/07/02 19:07:30 ru Exp $
.\"
-.Dd June 4, 1993
+.Dd July 18, 2003
.Dt TIME 3
.Os
.Sh NAME
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
projects / apple / libc.git / blobdiff