el_oenable_file_log¶

NAME¶

el_enable_file_log - configures and enables printing to file

SYNOPSIS¶

#include <embedlog.h>

int el_enable_file_log(const char *path, int rotate_number,
    long rotate_size);

int el_oenable_file_log(struct el *el, const char *path,
    int rotate_number, long rotate_size);

DESCRIPTION¶

This function will do multiple things. First it will configure log rotation.

If you want to have limited number of files with limited size, you can specify log rotation in these values.

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

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.

If you want date log rotation, in place of rotate_number pass enum el_option_rotate.

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
`EL_ROT_DATE_SEC`	`logname.2024-03-01--15-04-23` `logname.2024-03-01--15-04-24` `logname.2024-03-01--15-04-25` `logname.2024-03-01--15-04-36`
`EL_ROT_DATE_MIN`	`logname.2024-03-01--15-04` `logname.2024-03-01--15-05` `logname.2024-03-01--15-06` `logname.2024-03-01--15-08`
`EL_ROT_DATE_HOUR`	`logname.2024-03-01--15` `logname.2024-03-01--16` `logname.2024-03-01--18` `logname.2024-03-02--01`
`EL_ROT_DATE_DAY`	`logname.2024-03-01` `logname.2024-03-02` `logname.2024-03-03` `logname.2024-03-08`
`EL_ROT_DATE_MON`	`logname.2024-03` `logname.2024-04` `logname.2024-10` `logname.2024-12`
`EL_ROT_DATE_YEAR`	`logname.2024` `logname.2025` `logname.2026` `logname.2028`

Next it will try to open file specified by 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 or EL_FROTATE_DATE details.

And at the end it will enable outputing to file.

EXAMPLES¶

/* Enable logging to file without rotating, file will grow
 * without any limits, until it devours whole disk space */
el_enable_file_log("/var/log/file.log", 0, 0)

/* Enable logging to file, but also enable log rotation.
 * Program will take maximum 10 files each of 1MB in size.
 * When you enable log rotation do this in separate directory,
 * because program will create multiple file.log.N files in
 * directory where file.log is specified.
 *
 * In this case, file.log will always be a symlink to newest file */
el_enable_file_log("/var/log/progname/file.log", 10, 1024 * 1024)

/* Enable date log rotation. Once per day new file will be created */
el_enable_file_log("/var/log/progname/file.log", EL_ROT_DATE_DAY, 0)

RETURN VALUE¶

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

ERRORS¶

EINVAL: Input parameter is invalid
ENAMETOOLONG: File name is too long

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