clock_settime()

Set a clock

Synopsis:

#include <time.h>

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

Library:

libc

Description:

The clock_settime() function sets the clock specified by clock_id, from the buffer pointed to by tp.

The tp parameter points to a structure containing at least the following members:

time_t tv_sec

The tv_sec member contains a value that is the number of seconds since 1970.

long tv_nsec

The tv_nsec member contains the number of nanoseconds in the current second. This value increases by some multiple of nanoseconds, based on the system clock's resolution.

Be careful if you set the date during the period that a time zone is switching to daylight saving time (DST). When a time zone changes to DST, 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 DST). To avoid problems, use UTC time to set the date in this period.

Returns:

0

Success

-1

An error occurred (errno is set).

Errors:

EINVAL

Invalid clock_id.

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 (Realtime Extensions)

See also:

clock_getres(), clock_gettime(), errno