The GNU C Library - High-Resolution Calendar

High-Resolution Calendar

The time_t data type used to represent calendar times has a resolution of only one second. Some applications need more precision.

So, the GNU C library also contains functions which are capable of representing calendar times to a higher resolution than one second. The functions and the associated data types described in this section are declared in `sys/time.h'.

Data Type struct timeval

The struct timeval structure represents a calendar time. It has the following members:

long int tv_sec

This represents the number of seconds since the epoch. It is equivalent to a normal time_t value.

long int tv_usec

This is the fractional second value, represented as the number of microseconds.

Some times struct timeval values are used for time intervals. Then the tv_sec member is the number of seconds in the interval, and tv_usec is the number of additional microseconds.

Data Type struct timezone

The struct timezone structure is used to hold minimal information about the local time zone. It has the following members:

int tz_minuteswest

This is the number of minutes west of GMT.

int tz_dsttime

If nonzero, daylight savings time applies during some part of the year.

The struct timezone type is obsolete and should never be used. Instead, use the facilities described in Time Zone Functions.

It is often necessary to subtract two values of type struct timeval . Here is the best way to do this. It works even on some peculiar operating systems where the tv_sec member has an unsigned type.

	/* Subtract the `struct timeval' values X and Y,
	   storing the result in RESULT.
	   Return 1 if the difference is negative, otherwise 0.  */
	
	int
	timeval_subtract (result, x, y)
	     struct timeval *result, *x, *y;
	{
	  /* Perform the carry for the later subtraction by updating y. */
	  if (x->tv_usec < y->tv_usec) {
	    int nsec = (y->tv_usec - x->tv_usec) / 1000000 + 1;
	    y->tv_usec -= 1000000 * nsec;
	    y->tv_sec += nsec;
	  }
	  if (x->tv_usec - y->tv_usec > 1000000) {
	    int nsec = (y->tv_usec - x->tv_usec) / 1000000;
	    y->tv_usec += 1000000 * nsec;
	    y->tv_sec -= nsec;
	  }
	
	  /* Compute the time remaining to wait.
	     tv_usec  is certainly positive. */
	  result->tv_sec = x->tv_sec - y->tv_sec;
	  result->tv_usec = x->tv_usec - y->tv_usec;
	
	  /* Return 1 if result is negative. */
	  return x->tv_sec < y->tv_sec;
	}

Function int gettimeofday (struct timeval *tp, struct timezone *tzp)

The gettimeofday function returns the current date and time in the struct timeval structure indicated by tp. Information about the time zone is returned in the structure pointed at tzp. If the tzp argument is a null pointer, time zone information is ignored.

The return value is 0 on success and -1 on failure. The following errno error condition is defined for this function:

ENOSYS

The operating system does not support getting time zone information, and tzp is not a null pointer. The GNU operating system does not support using struct timezone to represent time zone information; that is an obsolete feature of 4.3 BSD. Instead, use the facilities described in Time Zone Functions.

Function int settimeofday (const struct timeval *tp, const struct timezone *tzp)

The settimeofday function sets the current date and time according to the arguments. As for gettimeofday , time zone information is ignored if tzp is a null pointer.

You must be a privileged user in order to use settimeofday .

The return value is 0 on success and -1 on failure. The following errno error conditions are defined for this function:

EPERM

This process cannot set the time because it is not privileged.

ENOSYS

The operating system does not support setting time zone information, and tzp is not a null pointer.

Function int adjtime (const struct timeval *delta, struct timeval *olddelta)

This function speeds up or slows down the system clock in order to make gradual adjustments in the current time. This ensures that the time reported by the system clock is always monotonically increasing, which might not happen if you simply set the current time.

The delta argument specifies a relative adjustment to be made to the current time. If negative, the system clock is slowed down for a while until it has lost this much time. If positive, the system clock is speeded up for a while.

If the olddelta argument is not a null pointer, the adjtime function returns information about any previous time adjustment that has not yet completed.

This function is typically used to synchronize the clocks of computers in a local network. You must be a privileged user to use it. The return value is 0 on success and -1 on failure. The following errno error condition is defined for this function:

EPERM

You do not have privilege to set the time.

Portability Note: The gettimeofday , settimeofday , and adjtime functions are derived from BSD.