clock_settime()

Set a clock

Synopsis:

#include <time.h>

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

Since:

BlackBerry 10.0.0

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.
  • In order to set the clock, your process must have the PROCMGR_AID_CLOCKSET ability enabled. For more information, see procmgr_ability().

Returns:

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

Errors:

EINVAL
One of the following occurred:
  • The id is invalid.
  • The number of nanoseconds specified by the tv_nsec member is less than zero or greater than or equal to 1000 million.
  • The tv_sec member is -1 (which could happen if you set it to the result from mktime() without checking to see if the call succeeded).
EPERM
The calling process doesn't have the required permission; see procmgr_ability().

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

Last modified: 2014-06-24



Got questions about leaving a comment? Get answers from our Disqus FAQ.

comments powered by Disqus