Description

We supply a function to allow fine adjustment of the time. Unlike cyg_clock_set_systime(), these adjustments will not cause an abrupt step change but allow gradual adjustment, while still preserving the principle of the clock monotonically increasing.

The cyg_clock_time_adj_t type is defined by including <cyg/clock/api.h>, and its contents are as follows:

typedef struct cyg_clock_time_adj_s {
    struct {
        unsigned int set_offset : 1;
        unsigned int get_adjremaining : 1;
    } flags;
    struct timespec  offset;       // Time offset
    struct timespec  adjremaining; // Remaining adjustment (can be negative)
} cyg_clock_time_adj_t;

	Note
	Do not rely on the ordering of members of this structure remaining the same in future. Similarly, additional structure members are likely to be added in future.

To adjust to a fixed offset from the current time, the adjustment is set with the offset member of the struct. The set_offset flag is also set, to indicate the vality of the offset member. Time will be gradually adjusted until this offset is reached. The time over which the offset is reached is derived from the value of CYGNUM_CLOCK_COMMON_ADJTIME_PERIOD_SHIFT. The offset may be positive or negative (represented by a positive or negative tv_sec field for the struct timespec).

Setting the offset will immediately cause any modules registered for time change notifications to be notified of the new adjustment, with an indication that an adjustment, rather than a step change occurred.

Setting the get_adjremaining flag will cause this function to fill in the adjremaining field with the total adjustment remaining to be enacted on the system clock. In other words, an adjustment was requested, but not fully complete because the adjustment period has not been reached, and the field is set with the adjustment remaining.

If no adjustment remains, the contents of adjremaining will be set to 0.

If both get_adjremaining and set_offset flags are set, then the adjremaining field is filled in with the adjustment remaining after the adjustment specified by the offset field has been applied, which will always simply be identical to the requested offset.

To allow for forward compatibility, a cyg_clock_time_adj_t must be initialized with the macro CYG_CLOCK_INIT_ADJ_T(adjt_p) where adjt_p is of type cyg_clock_time_adj_t *.

Example

{
  Cyg_ErrNo             err;
  cyg_clock_time_adj_t  adj;
  struct timespec       timediff;

  get_time_difference(&timediff);

  CYG_CLOCK_INIT_ADJ_T( &adj );
  adj.flags.set_offset = 1;
  adj.offset = timediff;

  err = cyg_clock_adjust_systime( &timediff );
  if ( ENOERR != err )
  {
    etc. …

Return value

This function returns a standard error code, as defined in <errno.h>, or ENOERR on success. Notably, ERANGE will be returned if the offset exceeds the limit configured with CYGNUM_CLOCK_COMMON_ADJTIME_MAX_RANGE.