source: rtems-docs/c_user/timespec_helpers.rst @ 489740f

.. comment SPDX-License-Identifier: CC-BY-SA-4.0

.. COMMENT: COPYRIGHT (c) 2011.
.. COMMENT: On-Line Applications Research Corporation (OAR).
.. COMMENT: All rights reserved.

Timespec Helpers
################

Introduction
============

The Timespec helpers manager provides directives to assist in manipulating
instances of the POSIX ``struct timespec`` structure.

The directives provided by the timespec helpers manager are:

- rtems_timespec_set_ - Set timespec's value

- rtems_timespec_zero_ - Zero timespec's value

- rtems_timespec_is_valid_ - Check if timespec is valid

- rtems_timespec_add_to_ - Add two timespecs

- rtems_timespec_subtract_ - Subtract two timespecs

- rtems_timespec_divide_ - Divide two timespecs

- rtems_timespec_divide_by_integer_ - Divide timespec by integer

- rtems_timespec_less_than_ - Less than operator

- rtems_timespec_greater_than_ - Greater than operator

- rtems_timespec_equal_to_ - Check if two timespecs are equal

- rtems_timespec_get_seconds_ - Obtain seconds portion of timespec

- rtems_timespec_get_nanoseconds_ - Obtain nanoseconds portion of timespec

- rtems_timespec_to_ticks_ - Convert timespec to number of ticks

- rtems_timespec_from_ticks_ - Convert ticks to timespec

Background
==========

Time Storage Conventions
------------------------

Time can be stored in many ways. One of them is the ``struct timespec`` format
which is a structure that consists of the fields ``tv_sec`` to represent
seconds and ``tv_nsec`` to represent nanoseconds.  The``struct timeval``
structure is simular and consists of seconds (stored in ``tv_sec``) and
microseconds (stored in ``tv_usec``). Either``struct timespec`` or ``struct
timeval`` can be used to represent elapsed time, time of executing some
operations, or time of day.

Operations
==========

Set and Obtain Timespec Value
-----------------------------

A user may write a specific time by passing the desired seconds and nanoseconds
values and the destination ``struct timespec`` using the ``rtems_timespec_set``
directive.

The ``rtems_timespec_zero`` directive is used to zero the seconds
and nanoseconds portions of a ``struct timespec`` instance.

Users may obtain the seconds or nanoseconds portions of a ``struct timespec``
instance with the ``rtems_timespec_get_seconds`` or
``rtems_timespec_get_nanoseconds`` methods, respectively.

Timespec Math
-------------

A user can perform multiple operations on ``struct timespec`` instances. The
helpers in this manager assist in adding, subtracting, and performing divison
on ``struct timespec`` instances.

- Adding two ``struct timespec`` can be done using the
  ``rtems_timespec_add_to`` directive. This directive is used mainly to
  calculate total amount of time consumed by multiple operations.

- The ``rtems_timespec_subtract`` is used to subtract two ``struct timespecs``
  instances and determine the elapsed time between those two points in time.

- The ``rtems_timespec_divide`` is used to use to divide one ``struct
  timespec`` instance by another. This calculates the percentage with a
  precision to three decimal points.

- The ``rtems_timespec_divide_by_integer`` is used to divide a ``struct
  timespec`` instance by an integer. It is commonly used in benchmark
  calculations to dividing duration by the number of iterations performed.

Comparing struct timespec Instances
-----------------------------------

A user can compare two ``struct timespec`` instances using the
``rtems_timespec_less_than``, ``rtems_timespec_greater_than`` or
``rtems_timespec_equal_to`` routines.

Conversions and Validity Check
------------------------------

Conversion to and from clock ticks may be performed by using the
``rtems_timespec_to_ticks`` and ``rtems_timespec_from_ticks`` directives.

User can also check validity of timespec with ``rtems_timespec_is_valid``
routine.

Directives
==========

This section details the Timespec Helpers manager's directives.  A subsection
is dedicated to each of this manager's directives and describes the calling
sequence, related constants, usage, and status codes.

.. _rtems_timespec_set:

TIMESPEC_SET - Set struct timespec Instance
-------------------------------------------
.. index:: set struct timespec instance

**CALLING SEQUENCE:**

.. index:: rtems_timespec_set

.. code-block:: c

    void rtems_timespec_set(
        struct timespec *time,
        time_t           seconds,
        uint32_t         nanoseconds
    );

**STATUS CODES:**

NONE

**DESCRIPTION:**

This directive sets the ``struct timespec`` *time* to the desired ``seconds``
and ``nanoseconds`` values.

**NOTES:**

This method does NOT check if ``nanoseconds`` is less than the maximum number
of nanoseconds in a second.

.. _rtems_timespec_zero:

TIMESPEC_ZERO - Zero struct timespec Instance
---------------------------------------------

**CALLING SEQUENCE:**

.. index:: rtems_timespec_zero

.. code-block:: c

    void rtems_timespec_zero(
        struct timespec *time
    );

**STATUS CODES:**

NONE

**DESCRIPTION:**

This routine sets the contents of the ``struct timespec`` instance ``time`` to
zero.

**NOTES:**

NONE

.. _rtems_timespec_is_valid:

TIMESPEC_IS_VALID - Check validity of a struct timespec instance
----------------------------------------------------------------

**CALLING SEQUENCE:**

.. index:: rtems_timespec_is_valid

.. code-block:: c

    bool rtems_timespec_is_valid(
        const struct timespec *time
    );

**STATUS CODES:**

This method returns ``true`` if the instance is valid, and ``false`` otherwise.

**DESCRIPTION:**

This routine check validity of a ``struct timespec`` instance. It checks if the
nanoseconds portion of the ``struct timespec`` instanceis in allowed range
(less than the maximum number of nanoseconds per second).

**NOTES:**

.. _rtems_timespec_add_to:

TIMESPEC_ADD_TO - Add Two struct timespec Instances
---------------------------------------------------

**CALLING SEQUENCE:**

.. index:: rtems_timespec_add_to

.. code-block:: c

    uint32_t rtems_timespec_add_to(
        struct timespec       *time,
        const struct timespec *add
    );

**STATUS CODES:**

The method returns the number of seconds ``time`` increased by.

**DESCRIPTION:**

This routine adds two ``struct timespec`` instances. The second argument is
added to the first. The parameter ``time`` is the base time to which the
``add`` parameter is added.

**NOTES:**

NONE

.. _rtems_timespec_subtract:

TIMESPEC_SUBTRACT - Subtract Two struct timespec Instances
----------------------------------------------------------

**CALLING SEQUENCE:**

.. index:: rtems_timespec_subtract

.. code-block:: c

    void rtems_timespec_subtract(
        const struct timespec *start,
        const struct timespec *end,
        struct timespec       *result
    );

**STATUS CODES:**

NONE

**DESCRIPTION:**

This routine subtracts ``start`` from ``end`` saves the difference in
``result``. The primary use of this directive is to calculate elapsed time.

**NOTES:**

It is possible to subtract when ``end`` is less than ``start`` and it produce
negative ``result``. When doing this you should be careful and remember that
only the seconds portion of a ``struct timespec`` instance is signed, which
means that nanoseconds portion is always increasing. Due to that when your
timespec has seconds = -1 and nanoseconds = 500,000,000 it means that result is
-0.5 second, NOT the expected -1.5!

.. _rtems_timespec_divide:

TIMESPEC_DIVIDE - Divide Two struct timespec Instances
------------------------------------------------------

**CALLING SEQUENCE:**

.. index:: rtems_timespec_divide

.. code-block:: c

    void rtems_timespec_divide(
        const struct timespec *lhs,
        const struct timespec *rhs,
        uint32_t              *ival_percentage,
        uint32_t              *fval_percentage
    );

**STATUS CODES:**

NONE

**DESCRIPTION:**

This routine divides the ``struct timespec`` instance ``lhs`` by the ``struct
timespec`` instance ``rhs``. The result is returned in the ``ival_percentage``
and ``fval_percentage``, representing the integer and fractional results of the
division respectively.

The ``ival_percentage`` is integer value of calculated percentage and
``fval_percentage`` is fractional part of calculated percentage.

**NOTES:**

The intended use is calculating percentges to three decimal points.

When dividing by zero, this routine return both ``ival_percentage`` and
``fval_percentage`` equal zero.

The division is performed using exclusively integer operations.

.. _rtems_timespec_divide_by_integer:

TIMESPEC_DIVIDE_BY_INTEGER - Divide a struct timespec Instance by an Integer
----------------------------------------------------------------------------

**CALLING SEQUENCE:**

.. index:: rtems_timespec_divide_by_integer

.. code-block:: c

    int rtems_timespec_divide_by_integer(
        const struct timespec *time,
        uint32_t               iterations,
        struct timespec       *result
    );

**STATUS CODES:**

NONE

**DESCRIPTION:**

This routine divides the ``struct timespec`` instance ``time`` by the integer
value ``iterations``.  The result is saved in ``result``.

**NOTES:**

The expected use is to assist in benchmark calculations where you typically
divide a duration (``time``) by a number of iterations what gives average time.

.. _rtems_timespec_less_than:

TIMESPEC_LESS_THAN - Less than operator
---------------------------------------

**CALLING SEQUENCE:**

.. index:: rtems_timespec_less_than

.. code-block:: c

    bool rtems_timespec_less_than(
        const struct timespec *lhs,
        const struct timespec *rhs
    );

**STATUS CODES:**

This method returns ``struct true`` if ``lhs`` is less than ``rhs`` and
``struct false`` otherwise.

**DESCRIPTION:**

This method is the less than operator for ``struct timespec`` instances. The
first parameter is the left hand side and the second is the right hand side of
the comparison.

**NOTES:**

NONE

.. _rtems_timespec_greater_than:

TIMESPEC_GREATER_THAN - Greater than operator
---------------------------------------------

**CALLING SEQUENCE:**

.. index:: rtems_timespec_greater_than

.. code-block:: c

    bool rtems_timespec_greater_than(
        const struct timespec *_lhs,
        const struct timespec *_rhs
    );

**STATUS CODES:**

This method returns ``struct true`` if ``lhs`` is greater than ``rhs`` and
``struct false`` otherwise.

**DESCRIPTION:**

This method is greater than operator for ``struct timespec`` instances.

**NOTES:**

NONE

.. _rtems_timespec_equal_to:

TIMESPEC_EQUAL_TO - Check equality of timespecs
-----------------------------------------------

**CALLING SEQUENCE:**

.. index:: rtems_timespec_equal_to

.. code-block:: c

    bool rtems_timespec_equal_to(
        const struct timespec *lhs,
        const struct timespec *rhs
    );

**STATUS CODES:**

This method returns ``struct true`` if ``lhs`` is equal to ``rhs`` and ``struct
false`` otherwise.

**DESCRIPTION:**

This method is equality operator for ``struct timespec`` instances.

**NOTES:**

NONE

.. _rtems_timespec_get_seconds:

TIMESPEC_GET_SECONDS - Get Seconds Portion of struct timespec Instance
----------------------------------------------------------------------

**CALLING SEQUENCE:**

.. index:: rtems_timespec_get_seconds

.. code-block:: c

    time_t rtems_timespec_get_seconds(
        struct timespec *time
    );

**STATUS CODES:**

This method returns the seconds portion of the specified ``struct timespec``
instance.

**DESCRIPTION:**

This method returns the seconds portion of the specified ``struct timespec``
instance ``time``.

**NOTES:**

NONE

.. _rtems_timespec_get_nanoseconds:

TIMESPEC_GET_NANOSECONDS - Get Nanoseconds Portion of the struct timespec Instance
----------------------------------------------------------------------------------

**CALLING SEQUENCE:**

.. index:: rtems_timespec_get_nanoseconds

.. code-block:: c

    uint32_t rtems_timespec_get_nanoseconds(
        struct timespec *_time
    );

**STATUS CODES:**

This method returns the nanoseconds portion of the specified ``struct
timespec`` instance.

**DESCRIPTION:**

This method returns the nanoseconds portion of the specified timespec which is
pointed by ``_time``.

**NOTES:**

.. _rtems_timespec_to_ticks:

TIMESPEC_TO_TICKS - Convert struct timespec Instance to Ticks
-------------------------------------------------------------

**CALLING SEQUENCE:**

.. index:: rtems_timespec_to_ticks

.. code-block:: c

    uint32_t rtems_timespec_to_ticks(
        const struct timespec *time
    );

**STATUS CODES:**

This directive returns the number of ticks computed.

**DESCRIPTION:**

This directive converts the ``time`` timespec to the corresponding number of
clock ticks.

**NOTES:**

NONE

.. _rtems_timespec_from_ticks:

TIMESPEC_FROM_TICKS - Convert Ticks to struct timespec Representation
---------------------------------------------------------------------

**CALLING SEQUENCE:**

.. index:: rtems_timespec_from_ticks

.. code-block:: c

    void rtems_timespec_from_ticks(
        uint32_t         ticks,
        struct timespec *time
    );

.. index:: rtems_timespec_from_ticks

**STATUS CODES:**

NONE

**DESCRIPTION:**

This routine converts the ``ticks`` to the corresponding ``struct timespec``
representation and stores it in ``time``.

**NOTES:**

NONE