el_ooption¶
NAME¶
el_option - sets optional configuration of the logger
SYNOPSIS¶
#include <embedlog.h>
int el_option(int option, ...);
int el_ooption(struct el *el, int option, ...);
DESCRIPTION¶
el_option(3) allows user to configure logger's internal el object, to tune logging to users needs. This is quite raw function to fine tune every aspect of embedlog. For normal usage it may be more beneficial and simpler to use some function that use most common options. Often setting multiple options in one call. These functions are not necessary better or faster. They are just different way of setting embedlog options.
Below is list of these functions and options they set.
+--------------------------+-------------------+----------------------------------+ | function | modified ioctl | short description | +==========================+===================+==================================+ | el_set_log_level(3) | EL_LEVEL | set new log level | +--------------------------+-------------------+----------------------------------+ | el_enable_output(3) | EL_OUT | enable output(s) | | el_disable_output(3) | | disable output(s) | +--------------------------+-------------------+----------------------------------+ | el_set_prefix(3) | EL_PREFIX | set new prefix for logs | +--------------------------+-------------------+----------------------------------+ | el_set_timestamp(3) | EL_TS | Enable timestamps, set time | | | EL_TS_TM | source, and optionally turn on | | | EL_TS_FRACT | fraction of seconds in logging | +--------------------------+-------------------+----------------------------------+ | el_enable_colors(3) | EL_COLORS | enable pretty colors in output | +--------------------------+-------------------+----------------------------------+ | el_print_extra_info(3) | EL_FINFO | Adds to log information about | | | EL_FUNCINFO | filename, line and function name | | | EL_PRINT_LEVEL | where log originated from | +--------------------------+-------------------+----------------------------------+ | el_set_custom_put(3) | EL_CUSTOM_PUT | Set custom function for printing | +--------------------------+-------------------+----------------------------------+ | el_enable_file_log(3) | EL_FROTATE_NUMBER | Enables logging to file, and | | | EL_FPATH | optionally sets file rotate | | | EL_FROTATE_SIZE | configuration | | | EL_FROTATE_DATE | | | | EL_OUT_FILE | | +--------------------------+-------------------+----------------------------------+ | el_set_file_sync(3) | EL_FSYNC_EVERY | Configures conditions to | | | EL_FSYNC_LEVEL + forcefully sync logs to disk | +--------------------------+-------------------+----------------------------------+ | el_set_tty_dev(3) | EL_TTY_DEV | Enables printing to tty device | | | EL_OUT | | +--------------------------+-------------------+----------------------------------+ | el_enable_thread_safe(3) | EL_THREAD_SAFE | Enables thread safety features | +--------------------------+-------------------+----------------------------------+
OPTIONS¶
Below is a list of option that can be configured. Value inside parenthesis determines argument types of variadic arguments ...
option |
arguments |
default value |
|---|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
EL_LEVEL¶
EL_LEVEL (enum el_level level) [default: EL_INFO]
Set 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):
/* print only alert and fatal logs */
el_option(EL_LEVEL, EL_ALERT);
/* print only error, critical, alert and fatal */
el_option(EL_LEVEL, EL_ERROR);
/* print all, including debug logs */
el_option(EL_LEVEL, EL_DBG);
- ERRORS
- EINVAL
specified level is invalid (bigger than EL_DBG).
EL_OUT¶
EL_OUT (enum el_output outputs) [default: EL_OUT_STDERR]
Set to what outputs logs will be printed 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
/* Log only to stdout */
el_option(EL_OUT, EL_OUT_STDOUT);
/* Log to stderr, network and file simultaneously
* Note, this will disable previously set print to stdout! */
el_option(EL_OUT, EL_OUT_STDERR | EL_OUT_NET | EL_OUT_FILE);
- ERRORS
- EINVAL
Specified output is invalid
- ENODEV
Specified output is not implemented on current system (support was not compiled into library)
EL_PRINT_NL¶
EL_PRINT_NL (int nl) [default: 1]
When enabled, new line marker will be added to each print. If you disable it, you will be able to create very long lines with consecutive print calls.
el_option(EL_PRINT_NL, 1);
el_print(ELI, "one");
el_print(ELI, "two");
el_print(ELI, "three");
/* log output: */
/* i/one
* i/two
* i/three */
el_option(EL_PRINT_LEVEL, 0);
el_option(EL_PRINT_NL, 0);
el_print(ELI, "one");
el_print(ELI, "two");
el_print(ELI, "three");
/* log output: */
/* onetwothree */
/* If you didn't disable, EL_PRINT_LEVEL (which by default is enabled)
* you would get: i/onei/twoi/three
EL_PREFIX¶
EL_PREFIX (const char *prefix) [default: none]
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_option(EL_PREFIX, "my-prefix");
el_print(ELI, "some log");
/* log output */
/* i/my-prefix: some log */
el_option(EL_PREFIX, NULL); /* default */
el_print(ELI, "some log");
/* log output */
/* i/some log */
EL_COLORS¶
EL_COLORS (int colors) [default: 0]
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. If you read file with colors in editor like vim, you will see control characters all over file.
- ERRORS
- EINVAL
Input argument is different than 1 or 0
EL_TS¶
EL_TS (enum el_option_timestamp timestamp) [default: EL_TS_OFF]
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_option(EL_TS, EL_TS_SHORT);
el_print(ELI, "some log");
/* log output */
/* [1709153777] i/some log */
el_option(EL_TS, EL_TS_LONG);
el_print(ELI, "some log");
/* log output */
/* [[2024-02-28 20:56:17]] i/some log */
- ERRORS
- EINVAL
Input argument is invalid
- ENOSYS
Timestamp support was not compiled in and setting this option is disabled.
EL_TS_TM¶
EL_TS_TM (enum el_option_timestamp_timer timer) [default: EL_TS_TM_TIME]
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_option(EL_TS_TM, EL_TS_TM_REALTIME);
el_option(EL_TS_TM, EL_TS_TM_TIME);
- ERRORS
- EINVAL
Input argument is invalid
- ENODEV
Specified timer source was not compiled in and is not available
EL_TS_FRACT¶
EL_TS_FRACT (enum el_option_timestamp_fraction fraction) [default: EL_TS_FRACT_OFF]
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 |
+-----------------+-------------------------------+
el_option(EL_TS_FRAC, EL_TS_FRACT_OFF);
el_option(EL_TS_FRAC, EL_TS_FRACT_MS);
- ERRORS
- EINVAL
Input argument is invalid
EL_PRINT_LEVEL¶
EL_PRINT_LEVEL (int print) [default: 1]
If EL_PRINT_LEVEL is set each log will have log level information prefix in format "l/" where 'l' is first character of level message is printed with.
el_option(EL_PRINT_LEVEL, 1);
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
el_option(EL_PRINT_LEVEL, 1);
this is critical message
this is just a notice
debug print
- ERRORS
- EINVAL
Input argument is different than 1 or 0
EL_PMEMORY_SPACE¶
EL_PMEMORY_SPACE (int spacing) [default: 0]
el_pmemory(3) prints 16 bytes in a line. EL_PMEMORY_SPACE alows to add additional spacing in the middle between 8 bytes, to improve readability in some cases. Check el_pmemory(3) how different spacing affects output.
el_option(EL_PMEMORY_SPACE, 2);
- ERRORS
- EINVAL
spacing is not between 0 and 3.
EL_FINFO¶
EL_FINFO (int finfo) [default: 0]
EL_FINFO 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
el_option(EL_FINFO, 1);
el_print(ELI, "some log");
/* log output */
/* [some-file.c:68] i/some log */
- ERRORS
- EINVAL
Input argument is different than 1 or 0
EL_FUNCINFO¶
EL_FUNCINFO (int funcinfo) [default: 0]
EL_FUNCINFO adds information about function from which message has been printed in format [funcname()] or if EL_FINFO is enabled [some_file.c:123:funcname()]. Setting this to 0 will result in no function information.
el_option(EL_FUNCINFO, 1);
el_print(ELI, "some log");
/* log output */
/* [some_function()] i/some log */
- ERRORS
- EINVAL
Input argument is different than 1 or 0
EL_CUSTOM_PUT¶
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.
int custom_logger(const char *s, size_t slen, void *user) {
FILE *f = user;
/* s will contain string "i/print log" */
fwrite(s, slen, 1, f);
return 0;
}
FILE *f = fopen(log_file, "w");
el_option(EL_CUSTOM_PUT, custom_logger, f);
el_option(EL_OUT, EL_OUT_CUSTOM);
el_print(ELI, "print log");
EL_FPATH¶
EL_FPATH (const char *path) [default: unset]
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 or EL_FROTATE_DATE 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(3)
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. EINVAL and ENAMETOOLONG are unrecovery errors, and embedlog will never store any log in that situation.
EL_FROTATE_NUMBER¶
EL_FROTATE_NUMBER (long number) [default: 0]
If FROTATE_NUMBER is 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
When number is bigger than 10, padded zeroes will be added to rotated logs like log.02, log.004or log.076. Actual number of padded zeroes depends in number passed. For bigger than 10 it will be 1 zero, for bigger than 100 it will be 0 zeroes and so on. This is done to ease up sorting when one would want to concat all files with one simple cat *.
Example file listing after multiple rotations may look like this:
$ ls -l /tmp/embedlog-example
total 20K
lrwxrwxrwx 1 lm- family 5 mar 1 19:50 log -> log.4
-rw-r----- 1 lm- family 496 mar 1 19:50 log.0
-rw-r----- 1 lm- family 470 mar 1 19:50 log.1
-rw-r----- 1 lm- family 496 mar 1 19:50 log.2
-rw-r----- 1 lm- family 470 mar 1 19:50 log.3
-rw-r----- 1 lm- family 496 mar 1 19:50 log.4
- ERRORS
- EINVAL
Input parameter is less than 0 or bigger than USHRT_MAX(65535).
EL_FROTATE_SYMLINK¶
EL_FROTATE_SYMLINK (int enable) [default: 1]
When EL_FROTATE_NUMBER is bigger than 0, this option is enabled and program runs on UNIX, embedlog will create symlink file in the same directory as rest of the logs with base name of path that is passed to EL_FPATH. So if "/var/log/program/program.log" path is passed, after some time more or less this file structure will be generated
/var/log/program/program.log.0
/var/log/program/program.log.1
/var/log/program/program.log.2
/var/log/program/program.log.3
/var/log/program/program.log -> program.log.3
Symlink will always point to file directly in the same directory. Symlink file will always point to most recent log file. This option is enabled by default.
- ERRORS
- EINVAL
Input parameter is not 0 or 1
EL_FROTATE_SIZE¶
EL_FROTATE_SIZE (long size) [default: 0]
FROTATE_SIZE defines file 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_FROTATE_DATE¶
EL_FROTATE_DATE (enum el_option_rotate timeslice) [default: EL_ROT_OFF]
EL_FROTATE_DATE enables log rotation based on date. When log is printed, embedlog checks if timeslice has passed. If so, a new file with new date will be opened.
There is no file limit size in this mode. If you set rotation to happen once
per day, log logfile.2024-03-01 may be only 100kB, but next day
logfile.2024-03-02 may be 1GB in size. Program does not remove files in
this mode
If not log has heppend within configured timeslice, no empty files will be created, program wil just jump to newest date.
For example, if timeslice is set to EL_ROT_DATE_MIN, new file will be created each time minute advances and new log is printed in that new minute.
There are 6 possible timeslices.
timeslice |
example rotated output |
|---|---|
|
logname.2024-03-01--15-04-23logname.2024-03-01--15-04-24logname.2024-03-01--15-04-25logname.2024-03-01--15-04-36 |
|
logname.2024-03-01--15-04logname.2024-03-01--15-05logname.2024-03-01--15-06logname.2024-03-01--15-08 |
|
logname.2024-03-01--15logname.2024-03-01--16logname.2024-03-01--18logname.2024-03-02--01 |
|
logname.2024-03-01logname.2024-03-02logname.2024-03-03logname.2024-03-08 |
|
logname.2024-03logname.2024-04logname.2024-10logname.2024-12 |
|
logname.2024logname.2025logname.2026logname.2028 |
- ERRORS
- EINVAL
Invalid timeslice parameter
EL_FSYNC_EVERY¶
EL_FSYNC_EVERY (long size) [default: 32768]
EL_FSYNC_EVERY defines how often logs shall be synced to disk. 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 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. Setting this to 0 will result in all logs being flush ever time they are printed.
- ERRORS
- EINVAL
Value is less than 0
EL_FSYNC_LEVEL¶
EL_FSYNC_LEVEL (enum el_level level) [default: EL_FATAL]
EL_FSYNC_LEVEL defines which log levels are always synced. 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¶
EL_TTY_DEV (const char *dev, speed_t speed) [default: unset]
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¶
EL_THREAD_SAFE (int safe) [default: 0]
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
