clock_settime()

Set a clock

Synopsis:

#include <time.h>

int clock_settime( clockid_t id,
                   const struct timespec * tp );

Arguments:

id

The clock ID, CLOCK_REALTIME or CLOCK_MONOTONIC, that maintains the system time, or the clock ID that's returned by ClockId().

tp

A pointer to a timespec structure containing at least the following members:

tv_sec — the number of seconds since 1970.
tv_nsec — the number of nanoseconds in the current second. This value increases by some multiple of nanoseconds, based on the system clock's resolution.

Library:

libc

Use the -l c option to qcc to link against this library. This library is usually included automatically.

Description:

The clock_settime() function sets the clock specified by id to the time specified in the buffer pointed to by tp.

Be careful if you set the date during the period that a time zone is switching from daylight saving time (DST) to standard time. When a time zone changes to standard time, the local time goes back one hour (for example, 2:00 a.m. becomes 1:00 a.m.). The local time during this hour is ambiguous (e.g. 1:14 a.m. occurs twice in the morning that the time zone switches to standard time). To avoid problems, use UTC time to set the date in this period.
You can't set the time when the id is CLOCK_MONOTONIC.
You need to have superuser privileges to set the clock.

Returns:

0: Success
-1: An error occurred (errno is set).

Errors:

EINVAL: Invalid id or the number of nanoseconds specified by the tv_nsec is less than zero or greater than or equal to 1000 million.
EPERM: You don't have sufficient privilege to change the time.

Examples:

/*  This program sets the clock forward 1 day. */

#include <stdio.h>
#include <stdlib.h>
#include <unistd.h>
#include <time.h>

int main( void )
  {
    struct timespec stime;

    if( clock_gettime( CLOCK_REALTIME, &stime) == -1 ) {
       perror( "getclock" );
       return EXIT_FAILURE;
    }

    stime.tv_sec += (60*60)*24L;  /* Add one day */
    stime.tv_nsec = 0;
    if( clock_settime( CLOCK_REALTIME, &stime) == -1 ) {
       perror( "setclock" );
       return EXIT_FAILURE;
    }
    return EXIT_SUCCESS;
  }

Classification:

POSIX 1003.1 TMR

Safety:
Cancellation point	No
Interrupt handler	No
Signal handler	Yes
Thread	Yes