SNTP Client Options

SNTP clients can set and get configuration and status related vales with tfSntpUserSetOption() and tfSntpUserGetOption(), respectively. The following is a list of possible options and in what context they may be used.

SNTP Client Configuration and Runtime Values

Option Name	Set/Get	Parameter Type	Macro Name	Default Value	Description
TM_SNTP_OPT_STEP_TIME	Set	struct timeval	TM_SNTP_STEP_TIME	0.2s	Sets the step time threshold. If a time update is received and the local clock offset is below this threshold, your notification callback function gets a TM_SNTP_EVENT_SLEW event. If the local clock offset is above the threshold, a TM_SNTP_EVENT_STEP or TM_SNTP_EVENT_PANIC event is signaled.
TM_SNTP_OPT_PANIC_TIME	Set	struct timeval	TM_SNTP_PANIC_TIME	1000s	Sets the panic time threshold. If a time update is received and the local clock offset above this threshold, your notification callback function gets a TM_SNTP_EVENT_PANIC event. If the local clock offset is below the threshold, a TM_SNTP_EVENT_STEP or TM_SNTP_EVENT_SLEW event is signaled.
TM_SNTP_OPT_BURST_TIME	Set	struct timeval	TM_SNTP_BURST_TIME	2s	(Unicast mode only) Sets the interval between burst requests. When an NTP client communicates with multiple servers, it usually sends a burst of requests to each server initially to quickly determine which servers will yield the most accurate time measurement. SNTP clients communicate with one server only, so burst requests may not be very useful. However, if your connection with the server is lossy, a burst of requests may mitigate the loss and help get you synchronized sooner.
TM_SNTP_OPT_BURST_COUNT	Set or Get	int	TM_SNTP_BURST_COUNT	3	(Unicast mode only) On write, sets the number of burst packets to send. On read, gets the number of burst packets left to send. Set a zero value to skip the burst phase and go straight to TM_SNTP_MINPOLL interval between requests.
TM_SNTP_OPT_UNREACH_COUNT	Set or Get	int	TM_SNTP_UNREACH	12	(Unicast mode only) On write, sets the number of packets to send to an unreachable server before exponentially backing off on sending requests. On read, gets the current unreachable counter value. A server is considered unreachable after sending 8 consecutive unanswered requests.
TM_SNTP_OPT_CLK_TOLERANCE	Set	struct timeval	TM_SNTP_PHI	15×10−6	Sets the rate, φ, that the local clock drifts in seconds per second. The default value of 15×10−6 is equivalent to 1.3s per day. This value is important for NTP servers but not very useful for SNTP clients.
TM_SNTP_OPT_CLK_PRECISION	Set	struct timeval	TM_SNTP_PRECISION	3.8µs	Sets the local clock precision, ρ. The value ρ is the local clock resolution or the time it takes to read the local clock, whichever is greater. This value is important for NTP servers but not very useful for SNTP clients.
TM_SNTP_OPT_BROADCAST_DELAY	Set	struct timeval	TM_SNTP_BCAST_DELAY	0.004s	(Broadcast mode only) Sets the estimated time it takes for a packet to travel from the broadcast server to us. This value is important for NTP servers but not very useful for SNTP clients.
TM_SNTP_OPT_MINPOLL	Set	struct timeval	TM_SNTP_MINPOLL	64s	(Unicast mode only) Sets the minimum interval between time update requests, excluding burst send phase. This interval is used when the server is reachable, i.e. has responded at least once in the last 8 attempts.
TM_SNTP_OPT_MAXPOLL	Set	struct timeval	TM_SNTP_MAXPOLL	17min	(Unicast mode only) Sets the maximum interval between time update requests. This interval is used when the server has been unreachable for some time.
TM_SNTP_OPT_MINFIRST	Set	struct timeval	TM_SNTP_MINFIRST	20s	(Unicast mode only) Sets the minimum time to delay before Treck SNTP sends it's first time update request. If there are many SNTP clients on the same network, it is useful to have a random delay when powering up to avoid overwhelming the server. This value sets the lower bound on the random delay.
TM_SNTP_OPT_MAXFIRST	Set	struct timeval	TM_SNTP_MAXFIRST	90s	(Unicast mode only) Sets the maximum time to delay before Treck SNTP sends it's first time update request. If there are many SNTP clients on the same network, it is useful to have a random delay when powering up to avoid overwhelming the server. This value sets the upper bound on the random delay.
TM_SNTP_OPT_MINDISP	Set	struct timeval	TM_SNTP_MINDISP	0.005s	Sets a minimum bound on the dispersion, ε, calculation. The dispersion is the worst case error in a time measurement. In some circumstances, ε can become unreasonably small and even negative, affecting other calculations. This value is important for NTP servers but not very useful for SNTP clients.
TM_SNTP_OPT_MAXDISP	Set	struct timeval	TM_SNTP_MAXDISP	16s	Sets the maximum allowable dispersion. If the root dispersion calculated from the received message ((RootDelay / 2) + RootDisp) exceeds this value, the received time update is ignored as having too much inherent error.
TM_SNTP_OPT_MAXDIST	Set	struct timeval	TM_SNTP_MAXDIST	1s	Sets the maximum allowable distance (maximum of all errors: dispersion, delay, etc.). Currently, this value is not used as it is primarily intended for NTP servers.
TM_SNTP_OPT_REACH_REGISTER	Get	int	–	–	(Unicast only) Get the current reach register value. The reach register holds an 8-bit value that is shifted left by 1 bit for each request sent and the least significant bit is set for each valid response received. When the reach register is zero, the server is considered unreachable.
TM_SNTP_OPT_CURRENT_POLL	Get	struct timeval	–	–	(Unicast only) Get the current poll interval.
TM_SNTP_OPT_CLOCK_OFFSET	Get	struct timeval	–	–	Get the most recently computed clock offset (computed at the last update).
TM_SNTP_OPT_TOTAL_DELAY	Get	struct timeval	–	–	Get the most recently computed delay (the root delay from the last message and the delay from the server to us).
TM_SNTP_OPT_TOTAL_DISP	Get	struct timeval	–	–	Get the most recently computed dispersion (the root dispersion from the last message and our dispersion).
TM_SNTP_OPT_REFERENCE_ID	Get	long	–	–	Get the most recently received reference identifier (typically the IP address of the root).
TM_SNTP_OPT_LEAP_INDICATOR	Get	int	–	–	Get the most recently received Leap Indicator (LI field, informs of leap second adjustment at midnight): 0: no change 1: last minute of the day has 61 seconds 2: last minute of the day has 59 seconds 3: unknown (clock unsynchronized)
TM_SNTP_OPT_STRATUM	Get	int	–	–	Get the most recently received server stratum: 0: unspecified or invalid 1: primary server (e.g., equipped with a GPS receiver) 2-15: secondary server (via NTP) 16: unsynchronized
TM_SNTP_OPT_USER_POINTER	Set or Get	void *	–	–	Set your own data pointer in the association object so that you can retrieve it, for example, from within your event notification function. This may be useful if you are using the same code for multiple SNTP associations. Important: Do not specify a pointer to a stack variable when you set the data pointer—specify the data pointer directly (static or dynamic memory). When retrieving, specify a pointer to a variable (possibly on the stack) to receive the value you set earlier.
TM_SNTP_OPT_CURRENT_TIME	Set or Get	struct timeval	–	–	Get or set the time kept internally for the association. This is only meaningful if you have not disabled automatic time correction (option TM_SNTP_OPT_USER_ADJUST).
TM_SNTP_OPT_ADJUST_TIME	Set	struct timeval	–	–	Add (subtract) to (from) the time kept internally for the association. This is only meaningful if you have not disabled automatic time correction (option TM_SNTP_OPT_USER_ADJUST).
TM_SNTP_OPT_USER_ADJUST	Set or Get	int	–	0 (false)	User adjusts the precise counter/timer. The default behavior assumes that the counter/timer input used by this implementation is not affected by time corrections made by the user's application. This might not be the case for legacy applications, especially if you do not use the TM_USE_KERNEL_PRECISE_TIME option. If you are upgrading from a version that did not support this option, please check your configuration and your SNTP callback function to make sure the counter/timer is not corrected both internally and externally. If you enable TM_USE_KERNEL_PRECISE_TIME, user-maintained function tfKernelGetPreciseTime() provides counter/timer input. Otherwise, Treck's sub-second timer is used (see tfTimerUpdate).