0001 TPLOGCONFIG(3)
0002 ==============
0003 :doctype: manpage
0004
0005
0006 NAME
0007 ----
0008 tplogconfig - Configure logger facilities
0009
0010
0011 SYNOPSIS
0012 --------
0013 #include <ndebug.h>
0014
0015 #include <nerror.h>
0016
0017 int tplogconfig(int 'logger', int 'lev', char *'debug_string', char *'module', char *'new_file');
0018
0019
0020 Link with '-lnstd -lpthread -lrt -lm'
0021
0022 DESCRIPTION
0023 -----------
0024 Function does configure logging facilities - *NDRX* (XATMI internal logs),
0025 *UBF* (UBF internal logs( and *TP* (User logs).
0026 If not already logger started, then this function will initiate Enduro/X
0027 framework to load the logging settings from [@debug] ini section or from
0028 *ndrxdebug.conf(5)*. Then with help of this function user is able to
0029 override loaded settings.
0030
0031 Also it is possible to set per thread logging, if facility code used here is
0032 *LOG_FACILITY_TP_THREAD*. Or it is possible to configure request based logging
0033 from this function, but *tplogsetreqfile_direct(3)* and *tplogsetreqfile(3)* is
0034 recommended to use instead.
0035
0036 The logging facility is set in 'logger' parameter, you may unify settings
0037 for multiple facilities with bitwise OR. Th facilities defined are following:
0038
0039 -------------------------------------------------------------------------------
0040
0041 /** settings for ATMI logging */
0042 #define LOG_FACILITY_NDRX 0x00000001
0043 /** settings for UBF logging */
0044 #define LOG_FACILITY_UBF 0x00000002
0045 /** settings for TP logging */
0046 #define LOG_FACILITY_TP 0x00000004
0047 /** settings for TP, thread based logging */
0048 #define LOG_FACILITY_TP_THREAD 0x00000008
0049 /** tp, Request logging, thread based*/
0050 #define LOG_FACILITY_TP_REQUEST 0x00000010
0051 /** ndrx thread logging */
0052 #define LOG_FACILITY_NDRX_THREAD 0x00000020
0053 /** ubf thread logging */
0054 #define LOG_FACILITY_UBF_THREAD 0x00000040
0055 /** ndrx request logging */
0056 #define LOG_FACILITY_NDRX_REQUEST 0x00000080
0057 /** ubf request logging */
0058 #define LOG_FACILITY_UBF_REQUEST 0x00000100
0059
0060 -------------------------------------------------------------------------------
0061
0062 'logger' is mandatory parameter to the function. To configure logging level
0063 for given facilities, you may use 'lev' to indicate one of the
0064 following levels:
0065
0066 -------------------------------------------------------------------------------
0067 #define log_always 1
0068 #define log_error 2
0069 #define log_warn 3
0070 #define log_info 4
0071 #define log_debug 5
0072 #define log_dump 6 /* this is un-offical level, normally use 1..5 */
0073 -------------------------------------------------------------------------------
0074
0075 'lev' is optional parameter, and if not used, then set it to '-1'. Function
0076 accepts optional parameter 'debug_string', which is Enduro/X standard debug
0077 string. If field not set then it might be NULL or empty (EOS). If set, then it
0078 contains the configuration settings described in *ndrxdebug.conf(5)* or
0079 see *ex_devguide(guides)*. One special note here is that, with debug string
0080 you may set log levels for *NDRX*, *UBF* and *TP* facilities, thus *ndrx* and
0081 *ubf* and "tp" log levels will affect the given logger settings (process/thread/request).
0082 For example *tp* will change the level of the given logger facility, per process
0083 (*LOG_FACILITY_TP*), per thread (*LOG_FACILITY_TP_THREAD*) or
0084 per request (*LOG_FACILITY_TP_REQUEST*).
0085
0086 If the 'lev' parameter is present and it will override the given loggers
0087 settings from 'debug_string'. The same applies if 'debug_string'
0088 contains the logging file, the 'new_file' is present (not NULL and not EOS)
0089 will override the output file setting if *file* param is
0090 present in 'debug_string'.
0091
0092 'module' module indicates the module code string which is plotted in each
0093 logged line. This is valid only for *TP* loggers for
0094 *NDRX* and *UBF* it is ignored.
0095
0096 As the all logging functions checks the early log level set in process level
0097 (due to fact that at that point TLS might not be initialized), thus by changing
0098 thread or request log levels, may only reduce the log level.
0099 So system might be configured so that, in config process level logs are higher,
0100 and then threads or requests might request to make the level lower.
0101
0102 If process for fails to open log file, logger is switched to *stderr*.
0103
0104 THREAD SAFETY
0105 -------------
0106 tplogconfig() function is thread safe. Changing the log file name while other
0107 threads are logging is supported too.
0108
0109 Due to support of multi-threaded operations is implemented, there is limitation
0110 that process level loggers (*LOG_FACILITY_NDRX*, *LOG_FACILITY_UBF* and *LOG_FACILITY_TP*)
0111 cannot have each different output file name. If for one logger file name is changed
0112 it is automatically replaced for other logger facilities (topics) too.
0113
0114 RETURN VALUE
0115 ------------
0116 On success, *tplogconfig()* returns 0. On error, -1 is returned, with
0117 *Nerror* set to indicate the error.
0118
0119 ERRORS
0120 ------
0121 Note that *Nstrerror()* returns generic error message plus custom message
0122 with debug info from last function call.
0123
0124 *NEFORMAT* Invalid format for 'debug_string'.
0125
0126 *NESYSTEM* System error occurred. See the logs for more info.
0127
0128
0129 EXAMPLE
0130 -------
0131 See *atmitest/test031_logging/atmiclt31.c* for sample code.
0132
0133 BUGS
0134 ----
0135 Report bugs to support@mavimax.com
0136
0137 SEE ALSO
0138 --------
0139 *tplogdump(3)* *tplogdumpdiff(3)* *tplog(3)* *tplogsetreqfile_direct(3)*
0140 *tplogsetreqfile(3)* *ex_devguide(guides)* *ndrxdebug.conf(5)* *tplogqinfo(3)*
0141
0142 COPYING
0143 -------
0144 (C) Mavimax, Ltd
0145
