gettimeofday(2) System Calls Manual 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 Compaq 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 gettime-
ofday64(
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 standards 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 timezone structure, defined in the <sys/time.h> file. For gettimeofday64() and set-
timeofday64(), 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 variable 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
(Coordinated 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 versions 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
handling of larger time values using the time64_t data type and is only available when the _TIME64_T feature macro is defined during compi-
lation.
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 function or the timeval64 struct. These function declarations are only
available when the _TIME64_T feature macro is defined during compilation.
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 mem-
bers, 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 com-
pilation.
NOTES
The following information applies only to the backward-compatible versions of the gettimeofday() and settimeofday() functions.
[Tru64 UNIX] The timezone structure that is returned for the gettimeofday() 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 information. The tz_dsttime field is set to zero because this field is
obsolete.
[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 gettime-
ofday() and settimeofday() to get and set timezone information in addition 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 informa-
tion 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 gettimeofday64() and settimeofday64() as well.
RETURN VALUES
Upon successful completion, a value of 0 (zero) is returned from gettimeofday(), settimeofday(), gettimeofday64(), and settimeofday64().
Otherwise, -1 is returned and errno is set to indicate the error.
ERRORS
If the gettimeofday(), settimeofday(), gettimeofday64(), or settimeofday64() 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 effective
privilege, which is required for using settimeofday() and settimeofday64().
SEE ALSO
Commands: date(1), zdump(8), zic(8)
Functions: adjtime(2), ctime(3), getclock(3), gettimer(3), setclock(3), strftime(3), timezone(3), time(3)
Files: tzfile(4)
Standards: standards(5)
gettimeofday(2)