# libc - High-Resolution Calendar

File: libc.info | Node: High-Resolution Calendar | Next: Broken-down Time | Prev: Simple Calendar Time | Up: Calendar Time

### 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 *Note 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 *Note
                Time Zone Functions::.

--Function: int settimeofday (const struct timeval *TP, const structtimezone *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.

Next: Broken-down Time | Up: Calendar Time

converted by gnuinfo

Main page of this Linux-oriented web server

This server is maintained by VH