nstime.h File Reference

#include <wireshark.h>
#include <time.h>

Go to the source code of this file.

Classes
struct	nstime_t

Macros
#define	TIME_T_MIN
#define	TIME_T_MAX   ((time_t) (~ (time_t) 0 - TIME_T_MIN))
#define	NSTIME_INIT_ZERO   {0, 0}
#define	NSTIME_INIT_UNSET   {0, INT_MAX}
#define	NSTIME_INIT_SECS_NSECS(secs, nsecs)   {(secs) + ((nsecs) / 1000000000), (nsecs) % 1000000000}
#define	NSTIME_INIT_SECS_USECS(secs, usecs)   {(secs) + ((usecs) / 1000000), ((usecs) % 1000000) * 1000}
#define	NSTIME_INIT_SECS_MSECS(secs, msecs)   {(secs) + ((msecs) / 1000), ((msecs) % 1000) * 1000000}
#define	NSTIME_INIT_SECS(secs)   {secs, 0}
#define	NSTIME_INIT_MAX   {TIME_T_MAX, INT_MAX}
#define	nstime_add(sum, a)   nstime_sum(sum, sum, a)
	Adds a time value to an existing sum.
#define	nstime_subtract(sum, a)   nstime_delta(sum, sum, a)
	Subtracts a time value from an existing sum.
#define	NSTIME_ISO8601_BUFSIZE   sizeof("YYYY-MM-DDTHH:MM:SS.123456789Z")
	Buffer size required to store a full ISO 8601 timestamp string.
#define	NSTIME_UNIX_BUFSIZE   (20+10+1)
	Buffer size required to store a full Unix timestamp string with nanosecond precision.
#define	WS_TSPREC_MAX   9
	Maximum supported timestamp precision.
#define	NUM_WS_TSPREC_VALS   (WS_TSPREC_MAX + 1)
	Total number of valid timestamp precision values.
#define	nstime_round(a, prec)   nstime_rounded(a, a, prec)
	In-place rounding of a time value to the specified precision.

Enumerations
enum	iso8601_fmt_e { ISO8601_DATETIME , ISO8601_DATETIME_BASIC , ISO8601_DATETIME_AUTO }
enum	ws_tsprec_e {   WS_TSPREC_SEC = 0 , WS_TSPREC_100_MSEC = 1 , WS_TSPREC_10_MSEC = 2 , WS_TSPREC_MSEC = 3 ,   WS_TSPREC_100_USEC = 4 , WS_TSPREC_10_USEC = 5 , WS_TSPREC_USEC = 6 , WS_TSPREC_100_NSEC = 7 ,   WS_TSPREC_10_NSEC = 8 , WS_TSPREC_NSEC = 9 }
	Timestamp precision levels. More...

Functions
WS_DLL_PUBLIC void	nstime_set_zero (nstime_t *nstime)
	Sets the given nstime_t to zero.
WS_DLL_PUBLIC bool	nstime_is_zero (const nstime_t *nstime)
	Checks whether the given nstime_t is zero.
WS_DLL_PUBLIC bool	nstime_is_negative (const nstime_t *nstime)
	Checks whether the given nstime_t is negative.
WS_DLL_PUBLIC void	nstime_set_unset (nstime_t *nstime)
	Marks the given nstime_t as "unset".
WS_DLL_PUBLIC bool	nstime_is_unset (const nstime_t *nstime)
	Checks whether the given nstime_t is marked as "unset".
WS_DLL_PUBLIC void	nstime_copy (nstime_t *a, const nstime_t *b)
	Copies one nstime_t value to another.
WS_DLL_PUBLIC void	nstime_delta (nstime_t *delta, const nstime_t *b, const nstime_t *a)
	Calculates the time delta between two timestamps.
WS_DLL_PUBLIC void	nstime_sum (nstime_t *sum, const nstime_t *a, const nstime_t *b)
	Calculates the sum of two time values.
WS_DLL_PUBLIC int	nstime_cmp (const nstime_t *a, const nstime_t *b)
	Compares two time values.
WS_DLL_PUBLIC unsigned	nstime_hash (const nstime_t *nstime)
	Computes a hash value for a time value.
WS_DLL_PUBLIC double	nstime_to_msec (const nstime_t *nstime)
	Converts a time value to milliseconds.
WS_DLL_PUBLIC double	nstime_to_sec (const nstime_t *nstime)
	Converts a time value to seconds.
WS_DLL_PUBLIC bool	filetime_to_nstime (nstime_t *nstime, uint64_t filetime)
	Converts a Windows FILETIME to nstime.
WS_DLL_PUBLIC bool	filetime_ns_to_nstime (nstime_t *nstime, uint64_t nsfiletime)
	Converts a nanosecond-based FILETIME to nstime.
WS_DLL_PUBLIC bool	filetime_1sec_to_nstime (nstime_t *nstime, uint64_t filetime)
	Converts a second-based FILETIME to nstime.
WS_DLL_PUBLIC const char *	iso8601_to_nstime (nstime_t *nstime, const char *ptr, iso8601_fmt_e format)
	Parses an ISO 8601 formatted datetime string into an nstime_t.
WS_DLL_PUBLIC const char *	unix_epoch_to_nstime (nstime_t *nstime, const char *ptr)
	Parses a Unix epoch timestamp string into an nstime_t.
WS_DLL_PUBLIC size_t	nstime_to_iso8601 (char *buf, size_t buf_size, const nstime_t *nstime)
	Converts an nstime_t to an ISO 8601 formatted string.
WS_DLL_PUBLIC void	nstime_to_unix (char *buf, size_t buf_size, const nstime_t *nstime)
	Converts an nstime_t to a Unix timestamp string.
WS_DLL_PUBLIC void	nstime_rounded (nstime_t *a, const nstime_t *b, ws_tsprec_e prec)
	Rounds a time value to the specified precision.

Detailed Description

Definition of data structure to hold time values with nanosecond resolution

Macro Definition Documentation

nstime_add

#define nstime_add	(		sum,
			a
	)		nstime_sum(sum, sum, a)

Adds a time value to an existing sum.

Performs in-place addition: sum += a.

Parameters

sum	Pointer to the destination nstime_t structure.
a	Pointer to the time value to add.

NSTIME_ISO8601_BUFSIZE

#define NSTIME_ISO8601_BUFSIZE   sizeof("YYYY-MM-DDTHH:MM:SS.123456789Z")

Buffer size required to store a full ISO 8601 timestamp string.

Includes space for nanosecond precision and the trailing 'Z' character.

nstime_round

#define nstime_round	(		a,
			prec
	)		nstime_rounded(a, a, prec)

In-place rounding of a time value to the specified precision.

Equivalent to calling nstime_rounded(a, a, prec).

Parameters

a	Pointer to the nstime_t structure to round.
prec	The desired precision level.

nstime_subtract

#define nstime_subtract	(		sum,
			a
	)		nstime_delta(sum, sum, a)

Subtracts a time value from an existing sum.

Performs in-place subtraction: sum -= a.

Parameters

sum	Pointer to the destination nstime_t structure.
a	Pointer to the time value to subtract.

NSTIME_UNIX_BUFSIZE

#define NSTIME_UNIX_BUFSIZE   (20+10+1)

Buffer size required to store a full Unix timestamp string with nanosecond precision.

Includes space for a 64-bit signed integer and fractional nanoseconds.

NUM_WS_TSPREC_VALS

#define NUM_WS_TSPREC_VALS   (WS_TSPREC_MAX + 1)

Total number of valid timestamp precision values.

Represents the count of defined precision levels from seconds to nanoseconds.

TIME_T_MIN

#define TIME_T_MIN

Value:

                    ((time_t) ((time_t)0 < (time_t) -1 ? (time_t) 0 \
                    : (time_t) (~0ULL << (sizeof (time_t) * CHAR_BIT - 1))))

WS_TSPREC_MAX

#define WS_TSPREC_MAX   9

Maximum supported timestamp precision.

Indicates the highest precision level supported (nanoseconds).

Note

Extending beyond this would require expanding the fractional part of nstime_t to 64 bits.

Enumeration Type Documentation

iso8601_fmt_e

enum iso8601_fmt_e

Enumerator
ISO8601_DATETIME_BASIC	e.g. 2014-07-04T12:34:56.789+00:00
ISO8601_DATETIME_AUTO	ISO8601 Basic format, i.e. no - : separators

ws_tsprec_e

enum ws_tsprec_e

Timestamp precision levels.

Defines the number of digits of precision after the integral part of a timestamp. These values are used to control formatting and interpretation of time values across various subsystems (e.g., capture, display, export).

Enumerator
WS_TSPREC_SEC	Precision to whole seconds (0 digits)
WS_TSPREC_100_MSEC	Precision to 100 milliseconds (1 digit)
WS_TSPREC_10_MSEC	Precision to 10 milliseconds (2 digits)
WS_TSPREC_MSEC	Precision to 1 millisecond (3 digits)
WS_TSPREC_100_USEC	Precision to 100 microseconds (4 digits)
WS_TSPREC_10_USEC	Precision to 10 microseconds (5 digits)
WS_TSPREC_USEC	Precision to 1 microsecond (6 digits)
WS_TSPREC_100_NSEC	Precision to 100 nanoseconds (7 digits)
WS_TSPREC_10_NSEC	Precision to 10 nanoseconds (8 digits)
WS_TSPREC_NSEC	Precision to 1 nanosecond (9 digits)

Function Documentation

filetime_1sec_to_nstime()

WS_DLL_PUBLIC bool filetime_1sec_to_nstime	(	nstime_t *	nstime,
		uint64_t	filetime
	)

Converts a second-based FILETIME to nstime.

Converts a 64-bit time value expressed in seconds to an nstime_t structure.

Parameters

nstime	Pointer to the destination nstime_t structure.
filetime	The second-based time value to convert.

Returns

true on success, false on failure.

filetime_ns_to_nstime()

WS_DLL_PUBLIC bool filetime_ns_to_nstime	(	nstime_t *	nstime,
		uint64_t	nsfiletime
	)

Converts a nanosecond-based FILETIME to nstime.

Converts a 64-bit time value expressed in nanoseconds to an nstime_t structure. Caller must ensure the input is trusted and properly scaled.

Parameters

nstime	Pointer to the destination nstime_t structure.
nsfiletime	The nanosecond-based time value to convert.

Returns

true on success, false on failure.

filetime_to_nstime()

WS_DLL_PUBLIC bool filetime_to_nstime	(	nstime_t *	nstime,
		uint64_t	filetime
	)

Converts a Windows FILETIME to nstime.

Converts a 64-bit FILETIME value (in 100-nanosecond units since 1601) to an nstime_t structure.

Parameters

nstime	Pointer to the destination nstime_t structure.
filetime	The FILETIME value to convert.

Returns

true on success, false on failure.

iso8601_to_nstime()

WS_DLL_PUBLIC const char * iso8601_to_nstime	(	nstime_t *	nstime,
		const char *	ptr,
		iso8601_fmt_e	format
	)

Parses an ISO 8601 formatted datetime string into an nstime_t.

Converts a string in ISO 8601 format (e.g., "2025-10-22T23:10:00.123Z") into an nstime_t structure. On failure, returns NULL and sets the nstime to "unset".

Parameters

nstime	Pointer to the destination nstime_t structure.
ptr	Pointer to the ISO 8601 string to parse.
format	The expected format variant (e.g., extended or basic).

Returns

Pointer to the first character after the parsed input, or NULL on failure.

nstime_cmp()

WS_DLL_PUBLIC int nstime_cmp	(	const nstime_t *	a,
		const nstime_t *	b
	)

Compares two time values.

Returns a value similar to memcmp() or strcmp():

• > 0 if a > b
• 0 if a == b
• < 0 if a < b

Parameters

a	Pointer to the first time value.
b	Pointer to the second time value.

Returns

An integer indicating the comparison result.

nstime_copy()

WS_DLL_PUBLIC void nstime_copy	(	nstime_t *	a,
		const nstime_t *	b
	)

Copies one nstime_t value to another.

Performs a deep copy of the time value from source to destination. Effectively: a = b

Parameters

a	Pointer to the destination nstime_t structure.
b	Pointer to the source nstime_t structure.

function: nstime_copy

a = b

nstime_delta()

WS_DLL_PUBLIC void nstime_delta	(	nstime_t *	delta,
		const nstime_t *	b,
		const nstime_t *	a
	)

Calculates the time delta between two timestamps.

Computes the difference between two time values, allowing for negative results. The result is stored in the delta structure as delta = b - a. It is safe for any of the arguments to refer to the same structure. If the result does not fit in a nstime_t, delta is clamped to the largest or smallest valid value as appropriate, and errno is set to ERANGE. errno can be set to EINVAL if a->nsecs or b->nsecs is outside the valid range.

Parameters

delta	Pointer to the destination nstime_t structure to store the result.
b	Pointer to the later (or second) time value.
a	Pointer to the earlier (or first) time value.

nstime_hash()

WS_DLL_PUBLIC unsigned nstime_hash

(

const nstime_t *

nstime

)

Computes a hash value for a time value.

Generates a hash suitable for use in hash tables or maps.

Parameters

nstime

Pointer to the time value to hash.

Returns

A hash value representing the time.

nstime_is_negative()

WS_DLL_PUBLIC bool nstime_is_negative

(

const nstime_t *

nstime

)

Checks whether the given nstime_t is negative.

Determines if the time value represents a negative duration.

Parameters

nstime

Pointer to the nstime_t structure to check.

Returns

true if the time is negative, false otherwise.

nstime_is_unset()

WS_DLL_PUBLIC bool nstime_is_unset

(

const nstime_t *

nstime

)

Checks whether the given nstime_t is marked as "unset".

Determines if the time value is (0, INT_MAX), which is used to represent an unset timestamp.

Parameters

nstime

Pointer to the nstime_t structure to check.

Returns

true if the time is unset, false otherwise.

nstime_is_zero()

WS_DLL_PUBLIC bool nstime_is_zero

(

const nstime_t *

nstime

)

Checks whether the given nstime_t is zero.

Determines if the time value represents exactly 0 seconds and 0 nanoseconds.

Parameters

nstime

Pointer to the nstime_t structure to check.

Returns

true if the time is zero, false otherwise.

nstime_rounded()

WS_DLL_PUBLIC void nstime_rounded	(	nstime_t *	a,
		const nstime_t *	b,
		ws_tsprec_e	prec
	)

Rounds a time value to the specified precision.

Adjusts the fractional part of the time value to match the requested precision. For example, rounding to milliseconds will zero out micro- and nanosecond components. It is safe for a and b to point to the same structure.

Parameters

a	Pointer to the destination nstime_t structure.
b	Pointer to the source nstime_t structure.
prec	The desired precision level.

nstime_set_unset()

WS_DLL_PUBLIC void nstime_set_unset

(

nstime_t *

nstime

)

Marks the given nstime_t as "unset".

Sets the time value to (0, INT_MAX) to indicate an unset state. This allows distinguishing between a true zero timestamp and an uninitialized one.

Note

This was created as a fix for bug 1056.

Parameters

nstime

Pointer to the nstime_t structure to modify.

nstime_set_zero()

WS_DLL_PUBLIC void nstime_set_zero

(

nstime_t *

nstime

)

Sets the given nstime_t to zero.

Initializes the time value to 0 seconds and 0 nanoseconds.

Parameters

nstime

Pointer to the nstime_t structure to modify.

nstime_sum()

WS_DLL_PUBLIC void nstime_sum	(	nstime_t *	sum,
		const nstime_t *	a,
		const nstime_t *	b
	)

Calculates the sum of two time values.

Adds two time values together and stores the result in the sum structure as sum = a + b. It is safe for any of the arguments to refer to the same structure. If the result does not fit in a nstime_t, sum is clamped to the largest or smallest valid value as appropriate, and errno is set to ERANGE. errno can be set to EINVAL if a->nsecs or b->nsecs is outside the valid range.

Parameters

sum	Pointer to the destination nstime_t structure to store the result.
a	Pointer to the first time value.
b	Pointer to the second time value.

nstime_to_iso8601()

WS_DLL_PUBLIC size_t nstime_to_iso8601	(	char *	buf,
		size_t	buf_size,
		const nstime_t *	nstime
	)

Converts an nstime_t to an ISO 8601 formatted string.

Formats the given time value into a string using ISO 8601 format with nanosecond precision.

Parameters

buf	Destination buffer to hold the formatted string.
buf_size	Size of the destination buffer.
nstime	Pointer to the time value to format.

Returns

Number of characters written to the buffer (excluding null terminator).

nstime_to_msec()

WS_DLL_PUBLIC double nstime_to_msec

(

const nstime_t *

nstime

)

Converts a time value to milliseconds.

Returns the time as a double-precision value in milliseconds.

Parameters

nstime

Pointer to the time value.

Returns

Time in milliseconds.

nstime_to_sec()

WS_DLL_PUBLIC double nstime_to_sec

(

const nstime_t *

nstime

)

Converts a time value to seconds.

Returns the time as a double-precision value in seconds.

Parameters

nstime

Pointer to the time value.

Returns

Time in seconds.

nstime_to_unix()

WS_DLL_PUBLIC void nstime_to_unix	(	char *	buf,
		size_t	buf_size,
		const nstime_t *	nstime
	)

Converts an nstime_t to a Unix timestamp string.

Formats the given time value into a string representing seconds since the Unix epoch, with optional nanosecond precision.

Parameters

buf	Destination buffer to hold the formatted string.
buf_size	Size of the destination buffer.
nstime	Pointer to the time value to format.

unix_epoch_to_nstime()

WS_DLL_PUBLIC const char * unix_epoch_to_nstime	(	nstime_t *	nstime,
		const char *	ptr
	)

Parses a Unix epoch timestamp string into an nstime_t.

Converts a string representing a Unix timestamp (seconds since epoch) into an nstime_t structure. On failure, returns NULL and sets the nstime to "unset".

Parameters

nstime	Pointer to the destination nstime_t structure.
ptr	Pointer to the Unix timestamp string to parse.

Returns

Pointer to the first character after the parsed input, or NULL on failure.