el_ooption(3)

bofc manual pages

el_ooption(3)

NAME
SYNOPSIS
DESCRIPTION
OPTIONS
RETURN VALUE
ERRORS
SEE ALSO

NAME

el_option - sets optional configuration of the logger

SYNOPSIS

#include <embedlog.h>

int el_option(enum el_option option, ...)
const struct el *el_get_el(void)
int el_ooption(struct el *el, enum el_option option, ...)

DESCRIPTION

el_option(3) allows user to configure logger's internal el object, to tune logging to users needs.

el_get_el(3) allows user to get pointer to global embedlog object - that is used by all embedlog functions that don't accept el object - to directly read its fields.

OPTIONS

Below is a list of option that can be configured. Value inside parenthesis determines argument types of variadic arguments ...

EL_LEVEL (enum el_level level)

EL_LEVEL sets what the current logging level shall be. Altough it accepts enum el_level type, this can be whatever number from range <0, 7>. The higher the level, the lower priority of the message. All messages that have lower priority (higher number) then currently set level will not be printed. There are 8 predefined levels, sorted by priority (highest first):

: EL_FATAL,
EL_ALERT,
EL_CRIT,
EL_ERROR,
EL_WARN,
EL_NOTICE,
EL_INFO,
EL_DBG

ERRORS

EINVAL

: specified level is invalid (bigger than EL_DBG).

EL_OUT (enum el_output outputs)

EL_OUT simply sets to what outputs. logs will be printed to with any of the printing function. User can enable as many outputs as he desires - it can be all inputs or even none (if one wants to surpress logging for some time). To enable multiple outputs join values with or operator ( | ).

Currently following outputs can be enabled.

EL_OUT_STDERR

: Messages will be printed to standard error output

EL_OUT_STDOUT

: Messages will be printed to standard output

EL_OUT_SYSLOG

: Messages will be sent to syslog facility. This requires system with implemented POSIX.1-2001 and any syslog daemon

EL_OUT_FILE

: Messages will be printed to file. To work user should set output file with EL_FPATH. Log rotation can be configured with EL_FROTATE_NUMBER and EL_FROTATE_SIZE options.

EL_OUT_NET

: Messages shall be printed to external server. This requires BSD Sockets to be enabled on the clients system, and listening server. (TODO Not implemented yet)

EL_OUT_TTY

: Prints messages directly to configured serial console. Apart from setting this, user should also configure device and speed with EL_TTY_DEV.

EL_OUT_ALL

: Enables all supported outputs at once

EL_OUT_NONE

: Disables every output - logs won't be printed at all

EL_OUT_CUSTOM

: Enables custom function to be called on log print. Pointer to custom function needs to be set with EL_CUSTOM_PUTS option.

Many of the outputs can be configured for special needs, and some of them need mandatory configuration. For information about output configuration see proper option description

ERRORS

EINVAL

: Specified output is invalid

ENODEV

: Specified output is not implemented on current system (support was not compiled into library)

EL_PREFIX (const char *prefix)

: You can configure logger to add prefix to every message you print. prefix will be printed between log level info "i/" and you message. No spaces are added. If you set your prefix to simple PREFIX, printed message will be i/PREFIXmy log message, so you might want to add space there. If prefix is bigger than EL_PREFIX_LEN prefix will be truncated. To disable prefixing, simply set prefix to NULL.

EL_COLORS (int colors)

If this is set to 1, output will be enriched with ANSI colors depending on the message severity. This option needs terminal supporting colors. You can store messages with colors to file, and then read them with colors on color-enabled terminal. If this is set to 0, no colors will be added.

ERRORS

EINVAL

: Input argument is different than 1 or 0

EL_TS (enum el_option_timestamp timestamp)

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]

ERRORS

EINVAL

: Input argument is invalid

ENOSYS

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

EL_TS_TM (enum el_option_timestamp_timer timer)

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)

ERRORS

EINVAL

: Input argument is invalid

ENODEV

: Specified timer source was not compiled in and is not available

EL_TS_FRACT (enum el_option_timestamp_fraction fraction)

This 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 |
    +-----------------+-------------------------------+

EL_PRINT_LEVEL (int print)

If this is set to 1, each log will have log level information prefix in format "l/" where 'l' is first character of level message is printed with, for example:

: c/this is critical message
n/this is just a notice
d/debug print

If value is set to 0, level information will not be added, and above messages would like like this

: this is critical message
this is just an notice
debug print

ERRORS

EINVAL

: Input argument is different than 1 or 0

EL_FINFO (int finfo)

If set to 1, adds information about log location to each message in format [some_file.c:123]. Setting this to 0, will result in no file information at all

ERRORS

EINVAL

: Input argument is different than 1 or 0

EL_FUNCINFO (int funcinfo)

If set to 1, adds information about function from which message has been printed in format [funcname()] or if EL_FINFO is enabled [some_file.c:123:funcname()]. Settint this to 0 will result in no function information.

ERRORS

EINVAL

: Input argument is different than 1 or 0

EL_CUSTOM_PUT ( int (*el_custom_put)(const char *s, size_t slen, void *user), void *user )

Sets function pointer for custom message print. Function will receive complete messsage (after processsing) to print, just as it would be printed to ie. stderr or another facility. Both binary and string data can be received this way.

s points to a data buffer, it can be null terminated string, or arbitrary binary data - depending on which functions has been called.

slen contains size of s buffer. If s is null terminated string, then slen contains length of string including null terminator character. For binary data, it contains size of binary buffer.

user pointer can be used to pass own logger object where data shall be sent. For example it may contain pointer to el struct, if you don't use global el struct.

Function cannot fail. If NULL is passed, custom function won't be called. It is still mandatory to enable custom printing with el_option(3) - EL_OUT.

EL_FPATH (const char *path)

Sets the path for the logs. Logs will be stored in this file. If file rotation is enabled, a numer will be postfixed to each file. See EL_FROTATE_NUMBER in this page for more details.

ERRORS

EINVAL

: Input parameter is NULL

ENAMETOOLONG

: File name is too long

Function can also fail and set errno for any of the errors specified for the routing fopen()

If function fails with EINVAL or ENAMETOOLONG, file is not opened and any calls that logs to file will result in failure. Any other error is in reality just a warning, meaning file could not have been opened now, but embedlog will try to reopen in each time it logs to file.

EL_FROTATE_NUMBER (long number)

If set to 0, file rotation will be disabled and logs will be printed into specified file without size limit. The only size limit is the one presented by the filesystem and architecture.

If this value is bigger than 0, file rotation will be enabled. All files will have suffixes added to name set in EL_FPATH. For example, program.log.0. Files are enumareted from .0 to .n, where n is set rotate number. File with suffix .0 is the oldest one, and the higher the number, the newer the file is. If logger reaches maximum number of files, oldest one with suffix .0 will be deleted and suffixes of the files will be decremented by 1 (ie. log.1 will be renamed to log.0, log.2 will be renamed to log.1 and so on).

User can also pass 1 here, but if file reaches its size limit, it will be deleted and printing will continue from the empty file

ERRORS

EINVAL

: Input parameter is less than 0

EL_FROTATE_SIZE (long size)

This defines size at which files will be rotated. If message being printed would overflow rotate size, current file will be closed and new one will be created, and current message will be stored in that new file. It is guaranteed that file will not be bigger than value set in this option. If log printed into file is bigger than configure rotate size, message will be truncated, to prevent file bigger than configure rotate size. It's very rare situation as it doesn't make a lot of sense to set rotate size to such small value.

ERRORS

EINVAL

: Value is less than 1

EL_FSYNC_EVERY (long size)

Simply writing data to file descriptor is not enough, metadata also has to be synced or you are facing data loose on unexpected power loose. Yes, data will be on block device, but entry to it in file system will not be updated, thus system will think file did not change. To prevent that one must sync data and metadata periodically. Data will be synced every size of bytes written. It basically translates to 'how much data am I ready to loose?'. Set this too high and you may loose a significant ammout of data on power lose. Set this too low and your performance goes out of the window.

ERRORS

EINVAL

: Value is less than 0

EL_FSYNC_LEVEL (enum el_level level)

If level of printed message is level or less (that is higher priority), it will be synced to disk every single time regardless of EL_FSYNC_EVERY option. Messages with level EL_FATAL (that is also default value for level sync) are synced always regardless of any options set. Messages printed with functions that don't take log level, will be treated as messages with EL_DBG level. If level is set to EL_DBG every message printed with any function will be immediately synced to drive (careful with that, this will impact performance a great deal if you print a lot of debug messages).

ERRORS

EINVAL

: specified level is invalid (bigger than EL_DBG).

EL_TTY_DEV (const char *dev, speed_t speed)

Tells embedlog to use dev serial device configured to speed. Serial device will also be configured to transmit in 8 bits of data, without parity and one stop bit (8N1). Logger uses only transmit pin (TX) and will translate all LF into CR-LF. If speed is configured to B0, serial port settings will not be altered, library will simply open port and will happily work on current serial settings.

ERRORS

: Function can return errors from open, tcgetattr, cfsetispeed and tcsetattr.

EL_THREAD_SAFE (int safe)

By default, embedlog is not thread safe. While it may be relatively safe to use it in multi-thread environment when you are logging to stdio or stderr, this surely isn't the case for more complex outputs like printing to file. Also, without EL_THREAD_SAFE calling el_pmemory(3) may result in interlacing prints.

So, when using embedlog in multi-threaded environment, it is advised to enable EL_THREAD_SAFE by passing 1 as safe argument. embedlog will then pthread_mutex_lock() whenever threads access el object.

EL_THREAD_SAFE call must be performed when no other threads are accessing el object, since at this point it is not possible to lock the mutex. Common usage is to enable thread safety at the beggining - right after el_init(3), and leave it to be destroyed by el_cleanup(3).

It is safe to call this option multiple time with same argument. embedlog will not allow for multiple initialization nor destruction of mutex. When options is called for the second time with same argument (like 1), nothing will happen and funciton will return 0.

ERRORS

Function can return errors from pthread_mutex_init(), and pthread_mutex_destroy().

EINVAL

: safe is different than 1 or 0

RETURN VALUE

On success 0 is returned. -1 is returned when any error occured.

ERRORS

EINVAL: Passed option is invalid.
ENOSYS: Passed option is not supported on this system (support was not compiled)

Also check for error description of specific option that failed for more informations

NAME

SYNOPSIS

DESCRIPTION

OPTIONS

RETURN VALUE

ERRORS

SEE ALSO