gettimeofday(2) — System Calls
NAME
gettimeofday, settimeofday, ftime − Gets and sets date and time
LIBRARY
Standard C Library (libc.a)
ftime() call: Berkeley Compatibility Library (libbsd.a)
SYNOPSIS
#include <sys/time.h>
int gettimeofday (
struct timeval ∗tp,
struct timezone ∗tzp );
int settimeofday (
struct timeval ∗tp,
struct timezone ∗tzp ); #include <sys/time.h>
#include <sys/timeb.h>
int ftime (
struct timeb ∗tp );
PARAMETERS
tpPoints to a timeval structure, defined in the sys/time.h file.
tzpPoints to a timezone structure, defined in the sys/time.h file.
DESCRIPTION
The gettimeofday() and settimeofday() are supported only for compatibility with BSD programs. They have been superseded by the getclock() and setclock() functions for getting and setting the time, and by the user-level timezone-handling package for getting and setting the timezone. (See getclock(3) and setclock(3) for information on the primary functions to use for getting and setting time. Also, see the section on Maintaining Timezone Information in this reference page.)
The gettimeofday() and settimeofday() functions get and set the time and timezone information stored in the kernel. However, since local timezone information is not stored in the kernel (unless you are running in the System V Habitat, discussed later in this reference page), these functions should not be used to access timezone information.
The timezone structure that is returned by the gettimeofday() call is set at boot tim 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. Therefore, these functions should only be used for getting and setting time information.
The tp parameter returns a pointer to a timeval structure which contains the time expressed in seconds and microseconds since midnight (0 hour), January 1, 1970 Greenwich Mean Time (GMT).
The tzp parameter should be set to NULL since timezone information should not be returned or set by these functions.
A process must have the sysattr effective privilege to use settimeofday().
NOTES
The ftime() function is included in libbsd.a for compatibility with older BSD programs. Its function has been made obsolete by getclock(), setclock(), and the user-level timezone-handling package.
SYSTEM V COMPATIBILITY
SVID2 maintains local timezone information in the kernel, although the information is not as accurate or as complete as the information that can be maintained at user level. On SVID2-compatible systems, you can use the tzp parameter with gettimeofday() 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 information is not returned or set.
MAINTAINING TIMEZONE INFORMATION
DEC OSF/1 systems use a public domain timezone-handling package which contains a database of globally accurate timezone information, including daylight savings time changes. Because of the complexity of this information and the limitations of the kernel interface with regard to timezone information, this information is not stored in the kernel. As a result, the kernel time zone is permanently set to GMT and the gettimeofday() and settimeofday() functions are not used to maintain local timezone information.
The following subsections explain how to get and set the local timezone. The zic(8), zdump(8), and tzfile(4) reference pages contain details on the timezone-handling package.
Getting Timezone Information
The libc ctime() and localtime() routines return the local time and timezone information. The ctime() routine returns a string that corresponds to the local time; for example, Tue Oct 27 13:35:29 1992.
The localtime() routine returns a pointer to a tm structure (defined in <sys/time.h>) that contains the local time expressed in fields of the tm structure. For timezone information, there are three relevant fields:
tm_isdst
A flag that is set to 1 if daylight savings time is currently in effect. Otherwise, the flag is set to 0.
tm_gmtoff
Seconds east of Greenwich. For example, −18000 means 5 hours west of Greenwich.
tm_tzone
Abbreviation for the current time zone (for example, EST, PDT, GMT).
Setting Timezone Information
On DEC OSF/1 systems, global timezone information is stored in specially formatted files in /etc/zoneinfo. The file /etc/zoneinfo/localtime is a link to the file in the /etc/zoneinfo directory which corresponds to the local time. This link is set by the installation software and can be changed by the system administrator to any file in the /etc/zoneinfo directory.
For example, to change the default system timezone to Canada’s Atlantic time zone, enter the following as superuser:
# ln −s /etc/zoneinfo/Canada/Atlantic /etc/zoneinfo/localtime
Subsequent calls to the timezone-related functions in libc (ctime() and localtime()) use this link for the default timezone information.
The /etc/zoneinfo/src directory contains the timezone and daylight savings time information that is used to generate the specially formatted files in the /etc/zoneinfo directory. If this information is incorrect for your time zone, you can change the information in the source files and then use the zic command to generate a corresponding /etc/zoneinfo file.
A user can override the default timezone information by setting the TZ environment variable. (See ctime(3) for information on how to set the TZ environment variable.)
RETURN VALUES
Upon successful completion, a value of 0 (zero) is returned. Otherwise, −1 is returned and errno is set to indicate the error.
ERRORS
If the gettimeofday() or settimeofday() function fails, errno may be set the following value:
[EFAULT]A parameter points to an invalid address.
[EPERM]The process’s effective user ID does not have the sysattr effective privilege, which is required for using settimeofday().
RELATED INFORMATION
Functions: adjtime(2), ctime(3), getclock(3), gettimer(3), setclock(3), strftime(3)
Files: tzfile(4)