diff options
author | Michał Łyszczek <michal.lyszczek@bofc.pl> | 2017-10-17 20:49:11 +0200 |
---|---|---|
committer | Michał Łyszczek <michal.lyszczek@bofc.pl> | 2017-10-17 20:49:11 +0200 |
commit | 3fa79ea0753236644547b8e67184a9c438255bb1 (patch) | |
tree | 4475839f182f89733f36f523e05adbfce77dd3cf | |
parent | a96867011b6802e987cb221108d8a7fc43165a02 (diff) | |
download | embedlog-3fa79ea0753236644547b8e67184a9c438255bb1.tar.gz embedlog-3fa79ea0753236644547b8e67184a9c438255bb1.tar.bz2 embedlog-3fa79ea0753236644547b8e67184a9c438255bb1.zip |
Added man pages
-rw-r--r-- | man/el_cleanup.3 | 56 | ||||
-rw-r--r-- | man/el_init.3 | 87 | ||||
-rw-r--r-- | man/el_level_set.3 | 85 | ||||
-rw-r--r-- | man/el_ocleanup.3 | 1 | ||||
-rw-r--r-- | man/el_oinit.3 | 1 | ||||
-rw-r--r-- | man/el_olevel_set.3 | 1 | ||||
-rw-r--r-- | man/el_ooption.3 | 1 | ||||
-rw-r--r-- | man/el_ooutput_disable.3 | 1 | ||||
-rw-r--r-- | man/el_ooutput_enable.3 | 1 | ||||
-rw-r--r-- | man/el_operror.3 | 1 | ||||
-rw-r--r-- | man/el_opmemory.3 | 1 | ||||
-rw-r--r-- | man/el_oprint.3 | 1 | ||||
-rw-r--r-- | man/el_option.3 | 266 | ||||
-rw-r--r-- | man/el_oputs.3 | 1 | ||||
-rw-r--r-- | man/el_output_disable.3 | 1 | ||||
-rw-r--r-- | man/el_output_enable.3 | 106 | ||||
-rw-r--r-- | man/el_overview.7 | 199 | ||||
-rw-r--r-- | man/el_ovprint.3 | 1 | ||||
-rw-r--r-- | man/el_perror.3 | 1 | ||||
-rw-r--r-- | man/el_pmemory.3 | 1 | ||||
-rw-r--r-- | man/el_print.3 | 230 | ||||
-rw-r--r-- | man/el_puts.3 | 1 | ||||
-rw-r--r-- | man/el_vprint.3 | 1 |
23 files changed, 1045 insertions, 0 deletions
diff --git a/man/el_cleanup.3 b/man/el_cleanup.3 new file mode 100644 index 0000000..b06d63c --- /dev/null +++ b/man/el_cleanup.3 @@ -0,0 +1,56 @@ +.TH "el_cleanup" "3" "22 Sep 2017 (v1.0.0)" "bofc.pl" + +.SH NAME +\fBel_cleanup\fR - cleans all resources allocated by \fBel_init()\fR and +\fBel_option\fR() calls. + +.SH SYNOPSIS + +.sh +.BI "#include <embedlog.h>" + +.sh +.BI "int el_cleanup(void)" +.br +.BI "int el_ocleanup(struct el_options *" options ")" + +.SH DESCRIPTION +\fBel_cleanup\fR() flushes all remaining buffers and frees any resources +allocated through the life of the library. After clean up, library calls +cannot be used without initialization. + +\fBel_ocleanup\fR() works just the same, but accepts custom \fIoptions\fR +as argument + +.SH RETURN VALUE +0 upon successful cleanup or -1 on errors. When -1 was returned no resources +were freed, and library functions still can be used. + +.SH ERRORS +\fBel_cleanup\fR() function cannot fail. \fBel_ocleanup\fR() may return: + +.TP +.B EINVAL +Passed options object is not valid + +.SH SEE ALSO +.BR el_init (3), +.BR el_overview (7), +.BR el_level_set (3), +.BR el_output_enable (3), +.BR el_output_disable (3), +.BR el_option (3), +.BR el_puts (3), +.BR el_print (3), +.BR el_vprint (3), +.BR el_perror (3), +.BR el_pmemory (3), +.BR el_olevel_set (3), +.BR el_ooutput_enable (3), +.BR el_ooutput_disable (3), +.BR el_ooption (3), +.BR el_oputs (3), +.BR el_oprint (3), +.BR el_ovprint (3), +.BR el_operror (3), +.BR el_opmemory (3), diff --git a/man/el_init.3 b/man/el_init.3 new file mode 100644 index 0000000..fcd886a --- /dev/null +++ b/man/el_init.3 @@ -0,0 +1,87 @@ +.TH "el_init" "3" "22 Sep 2017 (v1.0.0)" "bofc.pl" + +.SH NAME +\fBel_init\fR - initializes library and options for printing. + +.SH SYNOPSIS + +.sh +.BI "#include <embedlog.h> + +.sh +.BI "int el_init(void)" +.br +.BI "int el_oinit(struct options *" options ")" + +.SH DESCRIPTION +\fBel_init()\fR initializes library and default options structure. This function +must be called once before using any other function. + +\fBel_oinit()\fR initializes only \fIoptions\fR structure passed to it. Only after +that functions that accepts \fIoptions\fR may be used. + +.SH RETURN VALUE + +Both functions will return 0 upon success and -1 on errors + +.SH ERRORS + +.TP +.B EINVAL +\fIoptions\fR is invalid (null) + +.SH EXAMPLE +Error handling has been ommited for clarity sake + +.nf +#include <embedlog.h> + +int main(void) +{ + struct el_options opts; + + /* initialize both default and opts */ + el_init(); + el_oinit(&opts); + + /* default logger will print to stderr */ + el_output_enable(EL_OUT_STDERR); + + /* and opts will print to file */ + el_ooutput_enable(&opts, EL_OUT_FILE); + el_ooption(&opts, EL_OPT_FNAME, "/tmp/test.log"); + + /* print messages */ + el_print(ELI, "will print to stderr"); + el_oprint(ELI, &opts, "will print to file /tmp/test.log"); + + /* cleanup after any initialization code (like fopen) */ + el_ocleanup(&opts); + el_cleanup(); + + return 0; +} + +.SH SEE ALSO +.BR el_init (3), +.BR el_cleanup (3), +.BR el_overview (7), +.BR el_level_set (3), +.BR el_output_enable (3), +.BR el_output_disable (3), +.BR el_option (3), +.BR el_puts (3), +.BR el_print (3), +.BR el_vprint (3), +.BR el_perror (3), +.BR el_pmemory (3), +.BR el_ocleanup (3), +.BR el_olevel_set (3), +.BR el_ooutput_enable (3), +.BR el_ooutput_disable (3), +.BR el_ooption (3), +.BR el_oputs (3), +.BR el_oprint (3), +.BR el_ovprint (3), +.BR el_operror (3), +.BR el_opmemory (3), diff --git a/man/el_level_set.3 b/man/el_level_set.3 new file mode 100644 index 0000000..696cc40 --- /dev/null +++ b/man/el_level_set.3 @@ -0,0 +1,85 @@ +.TH "el_level_set" "3" "22 Sep 2017 (v1.0.0)" "bofc.pl" + +.SH NAME +\fBel_level_set\fR - sets current logging level + +.SH SYNOPSIS + +.sh +.BI "#include <embedlog.h> + +.sh +.BI "int el_level_set(enum el_level " level ")" +.br +.BI "int el_olevel_set(struct el_options *" options ", enum el_level " level ")" + +.SH DESCRIPTION +\fBel_level_set\fR sets what the current logging level shall be. Altough it +accepts \fBenum el_level\fR this can be whatever number from range <0, INT_MAX>. +The higher the level, the lower priority of the message. All messages that have +lower priority (higher number) then currently set \fIlevel\fR will not be +printed. There are 8 predefined levels, sorted by priority (highest first): + +.RS 4 +.B EL_FATAL, +.br +.B EL_ALERT, +.br +.B EL_CRIT, +.br +.B EL_ERROR, +.br +.B EL_WARN, +.br +.B EL_NOTICE, +.br +.B EL_INFO, +.br +.B EL_DBG +.RE + +If 8 print levels are not enough, one can define new levels, knowing that +\fBEL_FATAL\fR has int value of 0, and \fBEL_DBG\fR has int value of +7. User can also use debug level and add an integer like: \fBEL_DBG\fR + +\fIn\fR - where \fIn\fR can be any number from range <0, INT_MAX - 8>. + +If messages are printed with lower priority than \fBEL_DBG\fR they all +will be treated as messages printed with level \fBEL_DBG\fR, that means +message printed with level \fBEL_DBG\fR and \fBEL_DBG + 3\fR, will +be printed exactly the same, so same color (if colors are enabled) and if log +level printig is enabled, such messages will have same 'd/' prefix no matter +the level. + +\fBel_olevel_set\fR works the same way but it accepts external \fIoptions\fR +instead of static one in library. + +.SH RETURN VALUE +0 is returned on success or -1 on error + +.SH ERRORS +.TP +.B EINVAL +\fIoptions\fR is invalid (null) + +.SH SEE ALSO +.BR el_overview (7), +.BR el_init (3), +.BR el_cleanup (3), +.BR el_output_enable (3), +.BR el_output_disable (3), +.BR el_option (3), +.BR el_puts (3), +.BR el_print (3), +.BR el_vprint (3), +.BR el_perror (3), +.BR el_pmemory (3), +.BR el_oinit (3), +.BR el_ocleanup (3), +.BR el_ooutput_enable (3), +.BR el_ooutput_disable (3), +.BR el_ooption (3), +.BR el_oputs (3), +.BR el_oprint (3), +.BR el_ovprint (3), +.BR el_operror (3), +.BR el_opmemory (3), diff --git a/man/el_ocleanup.3 b/man/el_ocleanup.3 new file mode 100644 index 0000000..f5c1d77 --- /dev/null +++ b/man/el_ocleanup.3 @@ -0,0 +1 @@ +.so man3/el_cleanup.3 diff --git a/man/el_oinit.3 b/man/el_oinit.3 new file mode 100644 index 0000000..3dbf2b6 --- /dev/null +++ b/man/el_oinit.3 @@ -0,0 +1 @@ +.so man3/el_init.3 diff --git a/man/el_olevel_set.3 b/man/el_olevel_set.3 new file mode 100644 index 0000000..57be040 --- /dev/null +++ b/man/el_olevel_set.3 @@ -0,0 +1 @@ +.so man3/el_level_set.3 diff --git a/man/el_ooption.3 b/man/el_ooption.3 new file mode 100644 index 0000000..a82cd78 --- /dev/null +++ b/man/el_ooption.3 @@ -0,0 +1 @@ +.so man3/el_option.3 diff --git a/man/el_ooutput_disable.3 b/man/el_ooutput_disable.3 new file mode 100644 index 0000000..906eb43 --- /dev/null +++ b/man/el_ooutput_disable.3 @@ -0,0 +1 @@ +.so man3/el_output_enable.3 diff --git a/man/el_ooutput_enable.3 b/man/el_ooutput_enable.3 new file mode 100644 index 0000000..906eb43 --- /dev/null +++ b/man/el_ooutput_enable.3 @@ -0,0 +1 @@ +.so man3/el_output_enable.3 diff --git a/man/el_operror.3 b/man/el_operror.3 new file mode 100644 index 0000000..8a9800f --- /dev/null +++ b/man/el_operror.3 @@ -0,0 +1 @@ +.so man3/el_print.3 diff --git a/man/el_opmemory.3 b/man/el_opmemory.3 new file mode 100644 index 0000000..8a9800f --- /dev/null +++ b/man/el_opmemory.3 @@ -0,0 +1 @@ +.so man3/el_print.3 diff --git a/man/el_oprint.3 b/man/el_oprint.3 new file mode 100644 index 0000000..8a9800f --- /dev/null +++ b/man/el_oprint.3 @@ -0,0 +1 @@ +.so man3/el_print.3 diff --git a/man/el_option.3 b/man/el_option.3 new file mode 100644 index 0000000..7371f5c --- /dev/null +++ b/man/el_option.3 @@ -0,0 +1,266 @@ +.TH "el_option" "3" "22 Sep 2017 (v1.0.0)" "bofc.pl" + +.SH NAME +\fBel_option\fR - sets optional configuration of the logger + +.SH SYNOPSIS + +.sh +.B #include <embedlog.h> + +.sh +.BI "int el_option(enum el_option " option ", " ... ")" +.br +.BI "int el_ooption(struct el_options *" options "," +.BI "enum el_option " option ", " ... ")" + +.SH DESCRIPTION +\fBel_option\fR allows user to configure logger's internal options, to tune +logging to users needs. + +.SH OPTIONS +\fIoption\fR can be (value inside parenthesis determines argument types of +variadic arguments \fI...\fR) + +.BI "EL_OPT_COLORS (" int ")" +.RS 4 +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. + +. B ERRORS +. RS 4 +. B EINVAL +. RS 4 +Input argument is different than 1 or 0 +. RE +. RE +.RE + +.BI "EL_OPT_TS (" enum " " el_option_timestamp ")" +.RS 4 +Allows timestamp to be added to each log message. Possible values are: + +. B EL_OPT_TS_OFF +. RS 4 +Timestamp will not be added to messages +. RE + +. B EL_OPT_TS_SHORT +. RS 4 +Short timestamp will be added to log in format \fB[1503661223.537631]\fR +. RE + +. B EL_OPT_TS_LONG +. RS 4 +Long timestamp will be added to log in format \fB[2017-08-25 11:40:23.537651]\fR +. RE + +. B ERRORS +. RS 4 +. B EINVAL +. RS 4 +Input argument is invalid +. RE +. RE +.RE + +.BI "EL_OPT_TS_TM (" enum " " el_option_timestamp_timer ")" +.RS 4 +Sets the clock source for the timestamp print. + +. B EL_OPT_TS_TM_CLOCK +. RS 4 +Library will use value from \fBclock\fR() 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. +. RE + +. B EL_OPT_TS_TM_TIME +. RS 4 +Time is taken from \fBtime\fR() 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). +. RE + +. B EL_OPT_TS_TM_REALTIME +. RS 4 +Time is taken from \fBclock_gettime\fR() using \fBCLOCK_REALTIME\fR clock. +This required system with POSIX.1-2001. This time returns current system +wall clock, but it's precision is much higher that \fBEL_OPT_TS_TM_TIME\fR +clock (depending on system it can vary from 10^-3[s] up to even 10^-9[s]). +Just like it is with \fBEL_OPT_TS_TM_TIME\fR this timestamp can jump forward of +backward if it is changed in the system. +. RE + +. B EL_OPT_TS_TM_MONOTONIC +. RS 4 +This clock is similar to \fBEL_OPT_TS_TM_REALTIME\fR but it shows time from +unspecified time and is not affected by time change (it can still be altered +with \fBadjtime\fR(3) or NTP) +. RE + +. B ERRORS +. RS 4 +. B EINVAL +. RS 4 +Input argument is invalid +. RE +. RE +.RE + + +.BI "EL_OPT_PRINT_LEVEL (" int ")" +.RS 4 +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: + +. RS 4 +c/this is critical message +.br +n/this is just a notice +.br +d/debug print +. RE + +If value is set to 0, level information will not be added, and above messages +would like like this + +. RS 4 +this is critical message +.br +this is just an notice +.br +debug print +. RE + +. B ERRORS +. RS 4 +. B EINVAL +. RS 4 +Input argument is different than 1 or 0 +. RE +. RE +.RE + +.BI "EL_OPT_FINFO (" int ")" +.RS 4 +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 + +. B ERRORS +. RS 4 +. B EINVAL +. RS 4 +Input argument is different than 1 or 0 +. RE +. RE +.RE + +.BI "EL_OPT_FNAME (" const " " char " " * ")" +.RS 4 +Sets the file name for the logs. Logs will be stored in this file. If file +rotation is enabled, a numer will be postfixed to each file. See +\fBEL_OPT_FROTATE_NUMBER\fR in this page for more details. + +. B ERRORS +. RS 4 +. B EINVAL +. RS 4 +Input parameter is NULL +. RE + +. B ENAMETOOLONG +. RS 4 +File name is too long +. RE + +Function can also fail and set \fIerrno\fR for any of the errors specified for +the routing \fBfopen(3)\fR + +. RE + +If function fails, file is not opened and any calls that logs to file will +result in failure. +.RE + +.BI "EL_OPT_FROTATE_NUMBER (" long ")" +.RS 4 +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_OPT_FNAME. For example, +\fIprogram.log.0\fR. Files are enumareted from \fI.0\fR to \fI.n\fR, where +\fIn\fR is set rotate number. File with suffix \fI.0\fR 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 \fI.0\fR will be deleted and suffixes +of the files will be decremented by 1 (ie. \fIlog.1\fR will be renamed to +\fIlog.0\fR, \fIlog.2\fR will be renamed to \fIlog.1\fR 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 + +. B ERRORS +. RS 4 +. B EINVAL +. RS 4 +Input parameter is less than 0 +. RE +. RE +.RE + +.BI "EL_OPT_FROTATE_SIZE (" long ")" +.RS 4 +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. + +. B ERRORS +. RS 4 +. B EINVAL +. RS 4 +Value is less than 1 +. RE +. RE +.RE + + +.SH RETURN VALUE +On success 0 is returned. -1 is returned when some error occured + +.SH ERRORS +Check for error description of specific option that failed for more informations + +.SH SEE ALSO +.BR el_init (3), +.BR el_cleanup (3), +.BR el_overview (7), +.BR el_level_set (3), +.BR el_output_enable (3), +.BR el_output_disable (3), +.BR el_puts (3), +.BR el_print (3), +.BR el_vprint (3), +.BR el_perror (3), +.BR el_pmemory (3), +.BR el_ocleanup (3), +.BR el_olevel_set (3), +.BR el_ooutput_enable (3), +.BR el_ooutput_disable (3), +.BR el_oputs (3), +.BR el_oprint (3), +.BR el_ovprint (3), +.BR el_operror (3), +.BR el_opmemory (3), diff --git a/man/el_oputs.3 b/man/el_oputs.3 new file mode 100644 index 0000000..8a9800f --- /dev/null +++ b/man/el_oputs.3 @@ -0,0 +1 @@ +.so man3/el_print.3 diff --git a/man/el_output_disable.3 b/man/el_output_disable.3 new file mode 100644 index 0000000..906eb43 --- /dev/null +++ b/man/el_output_disable.3 @@ -0,0 +1 @@ +.so man3/el_output_enable.3 diff --git a/man/el_output_enable.3 b/man/el_output_enable.3 new file mode 100644 index 0000000..15f7cf6 --- /dev/null +++ b/man/el_output_enable.3 @@ -0,0 +1,106 @@ +.TH "el_output_enable" "3" "22 Sep 2017 (v1.0.0)" "bofc.pl" + +.SH NAME +\fBel_output_enable\fR, \fBel_output_disable\fR - enable or disable specific +output. + +.SH SYNOPSIS + +.sh +.BI "#include <embedlog.h> + +.sh +.BI "el_output_enable(enum el_output " output ")" +.br +.BI "el_output_disable(enum el_output " output ")" +.br +.BI "el_ooutput_enable(struct el_options *" options "," +.BI "enum el_output " output ")" +.br +.BI "el_ooutput_disable(struct el_options *" options "," +.BI "enum el_output " output ")" + +.SH DESCRIPTION +\fBel_output_enable\fR will enable given \fIoutput\fR, when log is printed +with any of the printing function. User can enable as many outputs as he +desires - it can be all inputs of even none (if one wants to surpress logging +for some time). Enabling or disabling \fIoutput\fR when it alread has been +enabled/disabled has no effect. + +Currently following \fIoutputs\fB can be enabled. + +.TP +.B EL_OUT_STDERR +Messages will be printed to standard error output + +.TP +.B EL_OUT_SYSLOG +Messages will be sent to syslog facility. This requires system with implementing +POSIX.1-2001 and any syslog daemon + +.TP +.B EL_OUT_FILE +Messages will be printed to file +.TP +.B 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) + +.TP +.B EL_OUT_TTY +Prints messages directly to configured serial console + +.TP +.B EL_OUT_ALL +Enables all supported outputs at once + +.P +Many of the outputs can be configured for special needs, and some of them need +mandatory configuration. For information about output configuration see +\fBel_option\fR(3) + + +\fBel_output_disable\fR simply disables specified \fIoutput\fR. If no output +is enabled, logging will be disabled (no cpu cycles will be wasted constructing +message). + +\fBel_ooutput_enable\fR and \fBel_ooutput_disable\fR work same way but also +accept \fIoptions\fR + +.SH RETURN VALUE +0 is returned on success and -1 on errors + +.SH ERRORS +.TP +.B EINVAL +Specified \fIoutput\fR is invalid + +.TP +.B EINVAL +\fIoptions\fR object is invalid (null) + +.TP +.B ENOSYS +Specified \fIoutput\fR is not implemented on current system (support was not +compiled into library) + +.SH SEE ALSO +.BR el_overview (7), +.BR el_init (3), +.BR el_cleanup (3), +.BR el_level_set (3), +.BR el_option (3), +.BR el_puts (3), +.BR el_print (3), +.BR el_vprint (3), +.BR el_perror (3), +.BR el_pmemory (3), +.BR el_oinit (3), +.BR el_ocleanup (3), +.BR el_olevel_set (3), +.BR el_ooption (3), +.BR el_oputs (3), +.BR el_oprint (3), +.BR el_ovprint (3), +.BR el_operror (3), +.BR el_opmemory (3), diff --git a/man/el_overview.7 b/man/el_overview.7 new file mode 100644 index 0000000..34bebbe --- /dev/null +++ b/man/el_overview.7 @@ -0,0 +1,199 @@ +.TH "el_overview" "7" "22 Sep 2017 (v1.0.0)" "bofc.pl" + +.SH NAME +\fBel_overview\fR - quick overview of \fIembedlog\fR logging library + +.SH SYNOPSIS +\fBembedlog\fR - is a highly portable \fBc89\fR complaint logger (with +additional features for users with \fBc99\fR compilers and/or \fBPOSIX\fR +systems). This library is designed mainly for embedded devices, but can also be +used in high level OSes like \fBLinux\fR. + +.SH DESCRIPTION +Logger incorporates features like: + +.RS 4 +- printing to different outputs (simultaneously) like: +.RS 4 +- stderr +.br +- syslog +.br +- file (with optional rotating) +.br +- net (TODO: not implemented yet) +.br +- tty - directly to chosen serial console (TODO: not implemented yet) +.RE +- timestamping using following clocks: +.RS 4 +- clock_t +.br +- time_t +.br +- CLOCK_REALTIME (requires POSIX) +.br +- CLOCK_MONOTONIC (requires POSIX) +.RE +- printing file and line information +.br +- 8 predefined log levels (and [sizeof(int) - 8] custom levels ;-)) +.br +- colorful output (for easy error spotting) +.RE + +.RE +Library implements following functions: + +.sh +.BI "int el_init(void)" +.br +.BI "int el_cleanup(void)" +.br +.BI "int el_level_set(enum el_level " level ")" +.br +.BI "int el_output_enable(enum el_output " output ")" +.br +.BI "int el_output_disable(enum el_output " output ")" +.br +.BI "int el_option(enum el_option " option ", ...)" +.br +.BI "int el_puts(const char *" string ")" +.br +.BI "int el_print(const char *" file ", size_t " line "," +.BI "enum el_level " level ", const char *" fmt ", " ... ")" +.br +.BI "int el_vprint(const char *" file ", size_t " line "," +.BI "enum el_level " level ", const char *" fmt ", va_list " ap ")" +.br +.BI "int el_pmemory(const char *" file ", size_t " line "," +.BI "enum el_level " level ", const void *" memory ", size_t " mlen ")" +.br +.BI "int el_perror(const char *" file ", size_t " line "," +.BI "enum el_level " level ", const char *" fmt ", " ... ")" + +Each functions has its equivalent function but accepting \fBoptions\fR as +argument. This is helpful if we want to have more than one, separated loggers +in a single program. Please see \fBel_option\fR(3) for more information. + +.sh +.BI "int el_oinit(struct el_options *" options ")" +.br +.BI "int el_ocleanup(struct el_options *" options ")" +.br +.BI "int el_olevel_set(struct el_options *" options ", enum el_level " level ")" +.br +.BI "int el_ooutput_enable(struct el_options *" options "," +.BI "enum el_output " output ")" +.br +.BI "int el_ooutput_disable(struct el_options *" options "," +.BI "enum el_output " output ")" +.br +.BI "int el_ooption(struct el_options *" options ", enum el_option " option "," +.BI "...)" +.br +.BI "int el_oputs(struct el_options *" options ", const char *" string ")" +.br +.BI "int el_oprint(const char *" file ", size_t " line "," +.BI "enum el_level " level ", struct el_options *" options "," +.BI "const char * "fnt ", " ... ")" +.br +.BI "int el_ovprint(const char *" file ", size_t " line "," +.BI "enum el_level " level ", struct el_options *" options "," +.BI "const char *" fmt ", va_list " ap ")" +.br +.BI "int el_opmemory(const char *" file ", size_t " line "," +.BI "enum el_level " level ", struct el_options *" options "," +.BI "const void *" memory ", size_t " mlen ")" +.br +.BI "int el_operror(const char *" file ", size_t " line "," +.BI "enum el_level " level ", struct el_options *" options "," +.BI "const char *" fmt ", " ... ")" + +For more information about a function open manual page with functions name from +section 3 (ie. for el_oputs, you'd open \fBel_oputs\fR(3)) + +Every function that accepts 3 parameters \fIlevel\fR, \fIfile\fR and \fIline\fR +as its first arguments, can accept short macro that injects proper values into +function. Awailable macros are: + +.RS 4 +\fBELF\fR Fatal errors, usually precedes application crash +.br +\fBELA\fR Alert, vey major error that should be fixed as soon as possible +.br +\fBELC\fR Critical +.br +\fBELE\fR Error +.br +\fBELW\fR Warning +.br +\fBELN\fR Normal log, but of high importance +.br +\fBELI\fR Information message, shouldn't spam too much here +.br +\fBELD\fR Debug messages, can spam as much as you'd like +.RE + +So instead of calling + +.RS 4 +\fBel_print(__FILE__, __LINE__, EL_NOTICE, "Notice message");\fR +.RE + +You can simply call it like + +.RS 4 +\fBel_print(ELN, "Notice message");\fR +.RE + +.SH EXAMPLE +Initial setup is very trivial. One should call init function and set at least +one output. Output can also be customized with proper options, see +\fBel_option\fR(3) for more details. + +.nf +#include <embedlog.h> + +int main(void) +{ + /* initialize library */ + el_init(); + + + /* tell logger to print onto stderr */ + el_output_enable(EL_OUT_STDERR); + + /* print message with info severity */ + el_print(ELI, "answer is %d", 42); + + /* clean after ourselfs */ + el_cleanup(); + + return 0; +} + +.SH SEE ALSO +.BR el_overview (7), +.BR el_init (3), +.BR el_cleanup (3), +.BR el_level_set (3), +.BR el_output_enable (3), +.BR el_output_disable (3), +.BR el_option (3), +.BR el_puts (3), +.BR el_print (3), +.BR el_vprint (3), +.BR el_perror (3), +.BR el_pmemory (3), +.BR el_oinit (3), +.BR el_ocleanup (3), +.BR el_olevel_set (3), +.BR el_ooutput_enable (3), +.BR el_ooutput_disable (3), +.BR el_ooption (3), +.BR el_oputs (3), +.BR el_oprint (3), +.BR el_ovprint (3), +.BR el_operror (3), +.BR el_opmemory (3), diff --git a/man/el_ovprint.3 b/man/el_ovprint.3 new file mode 100644 index 0000000..8a9800f --- /dev/null +++ b/man/el_ovprint.3 @@ -0,0 +1 @@ +.so man3/el_print.3 diff --git a/man/el_perror.3 b/man/el_perror.3 new file mode 100644 index 0000000..8a9800f --- /dev/null +++ b/man/el_perror.3 @@ -0,0 +1 @@ +.so man3/el_print.3 diff --git a/man/el_pmemory.3 b/man/el_pmemory.3 new file mode 100644 index 0000000..8a9800f --- /dev/null +++ b/man/el_pmemory.3 @@ -0,0 +1 @@ +.so man3/el_print.3 diff --git a/man/el_print.3 b/man/el_print.3 new file mode 100644 index 0000000..11b59f5 --- /dev/null +++ b/man/el_print.3 @@ -0,0 +1,230 @@ +.TH "el_print" "3" "22 sep 2017 (v1.0.0)" "bofc.pl" + +.SH NAME +\fBel_print\fR, \fBel_vprint\fR, \fBel_puts\fR, \fBel_perror\fR - prints message +to previously configured outputs. + +.SH SYNOPSIS + +.sh +.B "#include <embedlog.h>" + +.sh +.BI "int el_puts(const char *" message ")" +.br +.BI "int el_print(const char *" file ", size_t " line "," +.BI "enum el_level " level ", const char *" fmt ", " ... ")" +.br +.BI "int el_vprint(const char *" file ", size_t " line "," +.BI "enum el_level " level ", const char *" fmt ", va_list " ap ")" +.br +.BI "int el_perror(const char *" file ", size_t " line "," +.BI "enum el_level " level ", const char *" fmt ", " ... ")" +.br +.BI "int el_pmemory(const char *" file ", size_t " line "," +.BI "enum el_level " level ", const void *" memory ", size_t " mlen ") + +.sh +.BI "int el_oputs(struct el_options *" options ", const char *" message ")" +.br +.BI "int el_oprint(const char *" file ", size_t " line "," +.BI "enum el_level " level ", struct el_options *" options "," +.BI "const char *" fmt ", " ... ")" +.br +.BI "int el_ovprint(const char *" file ", size_t " line "," +.BI "enum el_level " level ", struct el_options *" options "," +.BI "const char *" fmt ", va_list " ap ")" +.br +.BI "int el_operror(const char *" file ", size_t " line "," +.BI "enum el_level " level ", struct el_options *" options "," +.BI "const char *" fmt ", " ... ")" +.br +.BI "int el_pmemory(const char *" file ", size_t " line "," +.BI "enum el_level " level ", struct el_options *" options "," +.BI "const void *" memory ", size_t " mlen ")" + +.sh +.BI "#define ELF " __FILE__ ", " __LINE__ ", " EL_FATAL +.br +.BI "#define ELA " __FILE__ ", " __LINE__ ", " EL_ALERT +.br +.BI "#define ELC " __FILE__ ", " __LINE__ ", " EL_CRIT +.br +.BI "#define ELE " __FILE__ ", " __LINE__ ", " EL_ERROR +.br +.BI "#define ELW " __FILE__ ", " __LINE__ ", " EL_WARN +.br +.BI "#define ELN " __FILE__ ", " __LINE__ ", " EL_NOTICE +.br +.BI "#define ELI " __FILE__ ", " __LINE__ ", " EL_INFO +.br +.BI "#define ELD " __FILE__ ", " __LINE__ ", " EL_DBG +.br + +ish +.BI "#define EL_DEBUG(" ... ") el_print(ELD, __VA_ARGS__) + +Feature Test Macro + +.BR "#define EL_DEBUG" () +.RS 4 +__ISOC99_SOURCE +.RE + +.SH DESCRIPTION +Functions print log into configured outputs. + +\fBel_puts\fR() function prints \fImessage\fR that is simple string, +\fImessage\fR is not altered in anyway - that means no automatic log levels, +location of the log nor timestamp is printed - even if they are enabled. Logs +printed with this functions are not filtered by log level, and will always be +printed. Prints can still be suppressed by disabling output. + +\fBel_print\fR() function behaves similar to standard \fBprintf\fR(3) function +from the standard library, but it adds (if enabled) additional information, such +as \fIfile\fR and \fIline\fR number from where log is printed, log \fIlevel\fR, +and timestamp of the message. \fIfmt\fR and variadic variables \fI...\fR have +the same role as it is described in \fBprintf\fR(3) function. + +\fBel_vprint\fR() function behaves just like \fBel_print\fR() but it accepts +argument pointer \fIap\fR instead of variadic variables. Check \fBvprintf\fR(3) +for more information. + +\fBel_perror\fR() works the same way as \fBel_print\fR() but will also print +information about current errno that was set. If \fIfmt\fR is \fBNULL\fR, +only information about errno will be printed. It is similar to \fBperror\fR(3) +function. + +\fBel_pmemory\fR() is designed to print memory location in a nice hex+ascii +format that may look like this. In this example we print all ascii table, to +present printing of printable and non-printable values + +.RS 4 +------ ----------------------------------------------- ---------------- +.br +offset hex ascii +.br +------ ----------------------------------------------- ---------------- +.br +0x0000 00 01 02 03 04 05 06 07 08 09 0a 0b 0c 0d 0e 0f ................ +.br +0x0010 10 11 12 13 14 15 16 17 18 19 1a 1b 1c 1d 1e 1f ................ +.br +0x0020 20 21 22 23 24 25 26 27 28 29 2a 2b 2c 2d 2e 2f !"#$%&'()*+,-./ +.br +0x0030 30 31 32 33 34 35 36 37 38 39 3a 3b 3c 3d 3e 3f 0123456789:;<=>? +.br +0x0040 40 41 42 43 44 45 46 47 48 49 4a 4b 4c 4d 4e 4f @ABCDEFGHIJKLMNO +.br +0x0050 50 51 52 53 54 55 56 57 58 59 5a 5b 5c 5d 5e 5f PQRSTUVWXYZ[\]^_ +.br +0x0060 60 61 62 63 64 65 66 67 68 69 6a 6b 6c 6d 6e 6f `abcdefghijklmno +.br +0x0070 70 71 72 73 74 75 76 77 78 79 7a 7b 7c 7d 7e 7f pqrstuvwxyz{|}~. +.br +------ ----------------------------------------------- ---------------- +.RE + +\fBel_print\fR(), \fBel_vprint\fR(), \fBel_perror\fR() and \fBel_pmemory\fR() +are filtered based on their \fIlevel\fR. + +All of above functions have their counterpart that also accepts custom +\fIoptions\fR object. This is useful if we want for example, print logs into +one file, and program queries into another. It can also be used to print +every level into different file. + +It is real pain in the ass to provice information about file in every print +function. For that matter very simple macros have been provided. + +.RS 4 +.BR ELF " fatal " +.br +.BR ELA " alert " +.br +.BR ELC " critical " +.br +.BR ELE " error " +.br +.BR ELW " warning " +.br +.BR ELN " notice " +.br +.BR ELI " information " +.br +.BR ELD " debug " +.RE + +These macros comprese first 3 parameters \fIfile\fR, \fIline\fR and +\fIlevel\fR into single, short parameter. For example instead calling this + +.RS 4 +el_print(__FILE__, __LINE__, EL_NOTICE, "notice message number %d", num); +.RE + +you can simply call + +.RS 4 +el_print(ELN, "notice message number %d", num); +.RE + +This solution works both for c89 and c99 standards. All side effects +(like from calling function or incrementing variable in print function call) +will take effect always regardless of set logging level. Also strings used in +functions will be compiled and put into binary - always. + +If user has access to c99 compiler, one can use \fBEL_DEBUG\fR for debuging +messages only. Later when application is compiled with NDEBUG, all side effects +as well as strings used will be stripped out from final binary - so no vital +information will be leaked in such way. This is not possible on c89 compiller +due to absence of variadic variables in preprocesor macros. + +.SH RETURN VALUE +All functions return 0 when whole message has been successfuly printed to all +configured outputs. If message couldn't be printed, it was printed only +partially, or was not send to at least one configured output -1 is returned. +Note that only one error is returned even if there was multiple errors. + +.SH ERRORS + +All functions may return one of these on error + +.TP +.B EINVAL +Any of the input parameters is invalid. + +.TP +.B EBADF +Loggig to file is enabled and filename was not set with \fBEL_OPT_FNAME\fR +option + +.RE +\fBel_print\fR(), \fBel_vprint\fR(), \fBel_perror\fR() \fBel_pmemory\fR +may also return + +.TP +.B ECHRNG +Message will not be logged as message log level is lower than configured one. + +.TP +.B ENOBUFS +Message is bigger than \fBEL_LOG_MAX\fR and will be truncated. + +.RE +When logging to file is enabled, all functions may also return errors +from \fBfwrite\fR(3) and if file rotation is enabled also from \fBfopen\fR(3) + +.SH SEE ALSO +.BR el_init (3), +.BR el_cleanup (3), +.BR el_overview (7), +.BR el_level_set (3), +.BR el_output_enable (3), +.BR el_output_disable (3), +.BR el_option (3), +.BR el_pmemory (3), +.BR el_ocleanup (3), +.BR el_olevel_set (3), +.BR el_ooutput_enable (3), +.BR el_ooutput_disable (3), +.BR el_ooption (3), +.BR el_opmemory (3), diff --git a/man/el_puts.3 b/man/el_puts.3 new file mode 100644 index 0000000..8a9800f --- /dev/null +++ b/man/el_puts.3 @@ -0,0 +1 @@ +.so man3/el_print.3 diff --git a/man/el_vprint.3 b/man/el_vprint.3 new file mode 100644 index 0000000..8a9800f --- /dev/null +++ b/man/el_vprint.3 @@ -0,0 +1 @@ +.so man3/el_print.3 |