time.h File Reference

#include <stdint.h>
#include "rcutils/macros.h"
#include "rcutils/types.h"
#include "rcutils/visibility_control.h"

Include dependency graph for time.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Macros
#define	RCUTILS_S_TO_NS(seconds)   ((seconds) * (1000LL * 1000LL * 1000LL))
	Convenience macro to convert seconds to nanoseconds. More...
#define	RCUTILS_MS_TO_NS(milliseconds)   ((milliseconds) * (1000LL * 1000LL))
	Convenience macro to convert milliseconds to nanoseconds. More...
#define	RCUTILS_US_TO_NS(microseconds)   ((microseconds) * 1000LL)
	Convenience macro to convert microseconds to nanoseconds. More...
#define	RCUTILS_NS_TO_S(nanoseconds)   ((nanoseconds) / (1000LL * 1000LL * 1000LL))
	Convenience macro to convert nanoseconds to seconds. More...
#define	RCUTILS_NS_TO_MS(nanoseconds)   ((nanoseconds) / (1000LL * 1000LL))
	Convenience macro to convert nanoseconds to milliseconds. More...
#define	RCUTILS_NS_TO_US(nanoseconds)   ((nanoseconds) / 1000LL)
	Convenience macro to convert nanoseconds to microseconds. More...
#define	RCUTILS_STEADY_TIME   rcutils_steady_time_now
	Convenience macro for rcutils_steady_time_now(rcutils_time_point_value_t *). More...

Typedefs
typedef int64_t	rcutils_time_point_value_t
	A single point in time, measured in nanoseconds since the Unix epoch. More...
typedef int64_t	rcutils_duration_value_t
	A duration of time, measured in nanoseconds. More...

Functions
rcutils_ret_t	rcutils_system_time_now (rcutils_time_point_value_t *now)
rcutils_ret_t	rcutils_steady_time_now (rcutils_time_point_value_t *now)
	Retrieve the current time as a rcutils_time_point_value_t object. More...
rcutils_ret_t	rcutils_time_point_value_as_nanoseconds_string (const rcutils_time_point_value_t *time_point, char *str, size_t str_size)
	Return a time point as nanoseconds in a string. More...
rcutils_ret_t	rcutils_time_point_value_as_seconds_string (const rcutils_time_point_value_t *time_point, char *str, size_t str_size)
	Return a time point as floating point seconds in a string. More...

Macro Definition Documentation

RCUTILS_S_TO_NS

#define RCUTILS_S_TO_NS

(

seconds

)

((seconds) * (1000LL * 1000LL * 1000LL))

Convenience macro to convert seconds to nanoseconds.

RCUTILS_MS_TO_NS

#define RCUTILS_MS_TO_NS

(

milliseconds

)

((milliseconds) * (1000LL * 1000LL))

Convenience macro to convert milliseconds to nanoseconds.

RCUTILS_US_TO_NS

#define RCUTILS_US_TO_NS

(

microseconds

)

((microseconds) * 1000LL)

Convenience macro to convert microseconds to nanoseconds.

RCUTILS_NS_TO_S

#define RCUTILS_NS_TO_S

(

nanoseconds

)

((nanoseconds) / (1000LL * 1000LL * 1000LL))

Convenience macro to convert nanoseconds to seconds.

RCUTILS_NS_TO_MS

#define RCUTILS_NS_TO_MS

(

nanoseconds

)

((nanoseconds) / (1000LL * 1000LL))

Convenience macro to convert nanoseconds to milliseconds.

RCUTILS_NS_TO_US

#define RCUTILS_NS_TO_US

(

nanoseconds

)

((nanoseconds) / 1000LL)

Convenience macro to convert nanoseconds to microseconds.

RCUTILS_STEADY_TIME

#define RCUTILS_STEADY_TIME   rcutils_steady_time_now

Convenience macro for rcutils_steady_time_now(rcutils_time_point_value_t *).

Typedef Documentation

rcutils_time_point_value_t

typedef int64_t rcutils_time_point_value_t

A single point in time, measured in nanoseconds since the Unix epoch.

rcutils_duration_value_t

typedef int64_t rcutils_duration_value_t

A duration of time, measured in nanoseconds.

Function Documentation

rcutils_system_time_now()

rcutils_ret_t rcutils_system_time_now

(

rcutils_time_point_value_t *

now

)

This function returns the time from a system clock. The closest equivalent would be to std::chrono::system_clock::now();

The resolution (e.g. nanoseconds vs microseconds) is not guaranteed.

The now argument must point to an allocated rcutils_time_point_value_t object, as the result is copied into this variable.

---

Attribute	Adherence
Allocates Memory	No
Thread-Safe	Yes
Uses Atomics	No
Lock-Free	Yes

Parameters

[out]

now

a datafield in which the current time is stored

Returns

RCUTILS_RET_OK if the current time was successfully obtained, or

RCUTILS_RET_INVALID_ARGUMENT if any arguments are invalid, or

RCUTILS_RET_ERROR if an unspecified error occur.

rcutils_steady_time_now()

rcutils_ret_t rcutils_steady_time_now

(

rcutils_time_point_value_t *

now

)

Retrieve the current time as a rcutils_time_point_value_t object.

This function returns the time from a monotonically increasing clock. The closest equivalent would be to std::chrono::steady_clock::now();

The resolution (e.g. nanoseconds vs microseconds) is not guaranteed.

The now argument must point to an allocated rcutils_time_point_value_t object, as the result is copied into this variable.

---

Attribute	Adherence
Allocates Memory	No
Thread-Safe	Yes
Uses Atomics	No
Lock-Free	Yes

Parameters

[out]

now

a struct in which the current time is stored

Returns

RCUTILS_RET_OK if the current time was successfully obtained, or

RCUTILS_RET_INVALID_ARGUMENT if any arguments are invalid, or

RCUTILS_RET_ERROR if an unspecified error occur.

rcutils_time_point_value_as_nanoseconds_string()

rcutils_ret_t rcutils_time_point_value_as_nanoseconds_string	(	const rcutils_time_point_value_t *	time_point,
		char *	str,
		size_t	str_size
	)

Return a time point as nanoseconds in a string.

The number is always fixed width, with left padding zeros up to the maximum number of digits the time point can represent. Right now that is 19 digits (so 19 characters) for a signed 64-bit integer. Negative values will have a leading -, so they will be one character longer than the positive values.

The recommended minimum size of the input string is 32 characters, but 21 ( or - for sign, 19 digits, null terminator) should be sufficiently large for both positive and negative values. If the given string is not large enough, the result will be truncated. If you need a string with variable width, using snprintf() directly is recommended.

---

Attribute	Adherence
Allocates Memory	No [1]
Thread-Safe	Yes
Uses Atomics	No
Lock-Free	Yes

[1] if snprintf() does not allocate additional memory internally

Parameters

[in]	time_point	the time to be made into a string
[out]	str	the output string in which it is stored
[in]	str_size	the size of the output string

Returns

RCUTILS_RET_OK if successful (even if truncated), or

RCUTILS_RET_INVALID_ARGUMENT if any arguments are invalid, or

RCUTILS_RET_ERROR if an unspecified error occur.

rcutils_time_point_value_as_seconds_string()

rcutils_ret_t rcutils_time_point_value_as_seconds_string	(	const rcutils_time_point_value_t *	time_point,
		char *	str,
		size_t	str_size
	)

Return a time point as floating point seconds in a string.

The number is always fixed width, with left padding zeros up to the maximum number of digits for the mantissa that the time point can represent and a characteristic (fractional-part) with a fixed width of 9 digits. Right now that means the mantissa is always 10 digits to add up to 19 total for the signed 64-bit time point type. Negative values will have a leading -, so they will be one character longer then positive values.

The recommended minimum size of the input string is 32 characters, but 22 ( or - for sign, 19 digits, decimal point, null terminator) should be sufficient for now. If the given string is not large enough, the result will be truncated.

---

Attribute	Adherence
Allocates Memory	No [1]
Thread-Safe	Yes
Uses Atomics	No
Lock-Free	Yes

[1] if snprintf() does not allocate additional memory internally

Parameters

[in]	time_point	the time to be made into a string
[out]	str	the output string in which it is stored
[in]	str_size	the size of the output string

Returns

RCUTILS_RET_OK if successful (even if truncated), or

RCUTILS_RET_INVALID_ARGUMENT if any arguments are invalid, or

RCUTILS_RET_ERROR if an unspecified error occur.