el_oset_timestamp

NAME

el_set_timestamp(3) - configure timestamp printing for each log

SYNOPSIS

#include <embedlog.h>

int el_set_timestamp(enum el_option_timestamp timestamp,
    enum el_option_timestamp_timer timer,
    enum el_option_timestamp_fractions fraction);

int el_oset_timestamp(struct el *el, enum el_option_timestamp timestamp
    enum el_option_timestamp_timer timer,
    enum el_option_timestamp_fractions fraction);

DESCRIPTION

Function sets EL_TS, EL_TS_TM and EL_TS_FRACT in one go.

EL_TS allows timestamp to be added to each log message. Possible values for timestamp are:

EL_TS_OFF

Timestamp will not be added to messages

EL_TS_SHORT

Short timestamp will be added to log in format [1503661223.537631]

EL_TS_LONG

Long timestamp will be added to log in format [2017-08-25 11:40:23.537651]

EL_TS_TM Sets the timer source for the timestamp print.

EL_TS_TM_CLOCK

Library will use value from clock() function. With this clock precission varies from 10^-3[s] to 10^-9[s]. On POSIX systems, this clock has precision of 10^-6[s]. This timer has a lot drawbacks, time value is unspecified at the beggining of the program, timer is not incremented when thread is sleeping, timer will overlap eventually (on 32bit systems with POSIX it takes around 72 minutes for the clock to overlap). On the other hand this is the most precise clock for pure c89 systems without POSIX.

EL_TS_TM_TIME

Time is taken from time() function. This returns current wall clock of the system, it's precision is very low (1[s]), but it's pure c89 and it is good for logging low frequent messages. This clock is susceptible to unexpected time change (from NTP or by root itself).

EL_TS_TM_REALTIME

Time is taken from clock_gettime() using CLOCK_REALTIME clock. This required system with POSIX.1-2001. This time returns current system wall clock, but it's precision is much higher than EL_TS_TM_TIME clock (depending on system it can vary from 10^-3[s] up to even 10^-9[s]). Just like it is with EL_TS_TM_TIME this timestamp can jump forward of backward if it is changed in the system.

EL_TS_TM_MONOTONIC

This clock is similar to EL_TS_TM_REALTIME but it shows time from unspecified time and is not affected by time change (it can still be altered with adjtime() or NTP)

EL_TS_FRACT option controls how to display fractions of seconds. If high resolution is not needed or not supported, it's best to set this to lowest resolution possible. Table will show exacly what this is about. Example uses long timestamp, interesting part is after date after dot '.'.

+-----------------+-------------------------------+
|      value      |  resulting timestamp string   |
+=================+===============================+
| EL_TS_FRACT_OFF | 2018-04-17 22:02:57           |
| EL_TS_FRACT_MS  | 2018-04-17 22:02:57.070       |
| EL_TS_FRACT_US  | 2018-04-17 22:02:57.070518    |
| EL_TS_FRACT_NS  | 2018-04-17 22:02:57.070518782 |
+-----------------+-------------------------------+

EXAMPLES

/* Disable timestamps. This is default behaviour */
el_set_timestamp(EL_TS_OFF, 0, 0);
el_print(ELI, "no timestamp");
/* log output */
/*   i/no timestamp */

/* Enable short timestamp without fraction seconds
 * Measure time from system boot. */
el_set_timestamp(EL_TS_SHORT, EL_TS_TM_MONOTONIC, EL_TS_FRACT_OFF);
el_print(ELI, "short timestamp");
/* log output */
/*   i/[3234] i/short timestamp */

/* Enable long timestamp with millisecond precision,
 * Measure real, clock time */
el_set_timestamp(EL_TS_LONG, EL_TS_TM_REALTIME, EL_TS_FRACT_MS);
el_print(ELI, "long timestamp with ms");
/* log output */
/*   i/[2024-02-29 10:23:47.361] i/long timestamp with ms */

RETURN VALUE

0 on succes, or -1 and set errno on failure.

ERRORS

EINVAL

Input argument is invalid

ENOSYS

Timestamp support was not compiled in and setting this option is disabled.

ENODEV

Specified timer source was not compiled in and is not available