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:

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.


Note:
  • 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

See also:

clock_getres(), clock_gettime(), errno, timespec