gettimeofday(2)gettimeofday(2)NAME
gettimeofday, settimeofday, ftime, gettimeofday64, settimeofday64,
TIMEVAL32TO64, TIMEVAL64TO32 - Gets and sets date and time and converts
time between timeval and timeval64
SYNOPSIS
#include <sys/time.h>
int gettimeofday(
struct timeval *tp,
void *tzp ); #include <sys/timeb.h>
int ftime(
struct timeb *tp );
The following function declarations do not conform to current standards
and are supported only for backward compatibility: #include
<sys/time.h>
int gettimeofday(
struct timeval *tp,
struct timezone *tzp ); int settimeofday(
struct timeval *tp,
struct timezone *tzp );
The following data type, function declarations, and macros are Tru64
UNIX extensions and do not conform to current standards. These features
are provided to support the time64_t data type and are accessible only
when the _TIME64_T feature macro is defined during compilation.
#include <sys/time.h>
struct timeval64 {
time64_t tv_sec; /* seconds */
int tv_usec; /* microseconds */ };
int gettimeofday64(
struct timeval64 *tp64,
void *tzp ); void TIMEVAL32TO64(
tv32, tv64 ); int TIMEVAL64TO32(
tv64, tv32 );
The following function declarations correspond to their non-standard
counterparts above, using timeval64 in place of timeval: int gettimeof‐
day64(
struct timeval64 *tp64,
struct timezone *tzp ); int settimeofday64(
struct timeval64 *tp64,
struct timezone *tzp );
LIBRARY
Standard C Library (libc)
STANDARDS
Interfaces documented on this reference page conform to industry stan‐
dards as follows:
gettimeofday(), ftime(): XPG4-UNIX
Refer to the standards(5) reference page for more information about
industry standards and associated tags.
PARAMETERS
For gettimeofday() and settimeofday(), points to a timeval structure,
defined in the <sys/time.h> file.
For ftime(), points to a timeb structure, defined in the
<sys/timeb.h> file. [Tru64 UNIX] For the backward-compatible
versions of gettimeofday() and settimeofday(), points to a time‐
zone structure, defined in the <sys/time.h> file. For gettime‐
ofday64() and settimeofday64(), points to a timeval64 structure,
defined in the <sys/time.h> system header file and described
below. Refers to a variable of type timeval. Refers to a vari‐
able of type timeval64.
DESCRIPTION
The gettimeofday(), ftime(), and settimeofday() functions get and set
the time and timezone information stored in the kernel.
The gettimeofday() function gets the current time, expressed in seconds
and microseconds since midnight (0 hour), January 1, 1970 UTC (Coordi‐
nated Universal Time, formerly Greenwich Mean Time or GMT), and stores
it in the timeval structure pointed to by tp.
The ftime() function sets the time and millitm members of the timeb
structure pointed to by tp to contain the seconds and milliseconds por‐
tions, respectively, of the current time in seconds since midnight (0
hour), January 1, 1970 UTC.
See the NOTES section for information on the backward-compatible ver‐
sions of gettimeofday() and settimeofday().
See the timezone(3) reference page for information on timezone handling
on Tru64 UNIX systems.
The timeval64 struct is identical to the timeval struct defined in the
<sys/time.h> system header file except that the tv_sec (seconds) field
is of type time64_t. The time64_t data type is described in the
time(3) reference page. The timeval64 struct is provided to allow han‐
dling of larger time values using the time64_t data type and is only
available when the _TIME64_T feature macro is defined during compila‐
tion.
The gettimeofday64() and settimeofday64() functions work exactly as the
gettimeofday() and settimeofday() functions (respectively), but use the
larger timeval64 struct (referenced by the tp64 pointer) instead of
timeval. The current system time setting limits (Jan 1 00:00:00 GMT
1970 through Jan 19 03:14:07 GMT 2038) are not changed by these func‐
tion or the timeval64 struct. These function declarations are only
available when the _TIME64_T feature macro is defined during compila‐
tion.
The TIMEVAL32TO64() and TIMEVAL64TO32() macros are provided to assist
developers converting between values of type timeval and values of type
timeval64. The TIMEVAL32TO64() macro converts the values contained in
the tv32 struct to values corresponding to timeval64 struct members,
storing the results in tv64 and performing sign-extension on the tv_sec
(seconds) field as appropriate. The TIMEVAL64TO32() macro attempts to
convert the values contained in the timeval64 struct tv64 to values
corresponding to timeval struct members, storing the results in tv32.
If the value of the tv_sec (seconds) field of tv64 overflows the size
of a time_t, the value of the TIMEVAL64TO32() macro will be 1 and the
values contained in tv32 are undefined. Otherwise, the value of the
TIMEVAL64TO32() macro will be 0 and tv32 will contain the converted
values from tv64. These conversion macros are only available when the
_TIME64_T feature macro is defined during compilation.
NOTES
The following information applies only to the backward-compatible ver‐
sions of the gettimeofday() and settimeofday() functions.
[Tru64 UNIX] The timezone structure that is returned for the gettime‐
ofday() call is set at boot time by the /sbin/init.d/settime script.
The tz_minuteswest field of the structure is set to your local time
zone. This field is set only for backward compatibility with older
applications that may use the gettimeofday() call for timezone informa‐
tion. The tz_dsttime field is set to zero because this field is obso‐
lete.
[Tru64 UNIX] On SVID2-compatible systems, local timezone information
is maintained in the kernel, although the information is not as accu‐
rate or as complete as the information that can be maintained at user
level. On these systems, you can use the tzp parameter with gettimeof‐
day() and settimeofday() to get and set timezone information in addi‐
tion to the time. The tzp parameter returns a pointer to a timezone
structure that contains the local timezone expressed in minutes of time
westward from Greenwich and a flag that, when nonzero, indicates that
daylight savings time applies locally during some part of the year.
Note that, if the tzp parameter is set to NULL, timezone information is
not returned or set.
[Tru64 UNIX] A process must have the sysattr effective privilege to
use settimeofday().
The above notes also pertain to the non-standard versions of gettimeof‐
day64() and settimeofday64() as well.
RETURN VALUES
Upon successful completion, a value of 0 (zero) is returned from get‐
timeofday(), settimeofday(), gettimeofday64(), and settimeofday64().
Otherwise, -1 is returned and errno is set to indicate the error.
ERRORS
If the gettimeofday(), settimeofday(), gettimeofday64(), or settimeof‐
day64() functions fail, errno may be set to the following values:
[Tru64 UNIX] A parameter points to an invalid address. [Tru64
UNIX] The process's effective user ID does not have the sysattr effec‐
tive privilege, which is required for using settimeofday() and settime‐
ofday64().
SEE ALSO
Commands: date(1), zdump(8), zic(8)
Functions: adjtime(2), ctime(3), getclock(3), gettimer(3), set‐
clock(3), strftime(3), timezone(3), time(3)
Files: tzfile(4)
Standards: standards(5)gettimeofday(2)