le_log.h

    1 /**
    2  * @page c_logging Logging API
    3  *
    4  * @subpage le_log.h "API Reference" <br>
    5  *
    6  * The Legato Logging API provides a toolkit allowing code to be instrumented with error, warning,
    7  * informational, and debugging messages. These messages can be turned on or off remotely and pushed or pulled
    8  * from the device through a secure shell, cloud services interfaces, e-mail, SMS, etc.
    9  *
   10  * @section c_log_logging Logging Basics
   11  *
   12  * Legato's logging can be configured through this API, and there's also a command-line target
   13  * @ref toolsTarget_log tool available.
   14  *
   15  * @subsection c_log_levels Levels
   16  *
   17  * Log messages are categorized according to the severity of the information being logged.
   18  * A log message may be purely informational, describing something that is
   19  * expected to occur from time-to-time during normal operation; or it may be a report of a fault
   20  * that might have a significant negative impact on the operation of the system.  To
   21  * differentiate these, each log entry is associated with one of the following log levels:
   22  *
   23  *  - @ref LE_LOG_DEBUG "DEBUG":
   24  *    Handy for troubleshooting.
   25  *  - @ref LE_LOG_INFO "INFORMATION":
   26  *    Expected to happen; can be interesting even when not troubleshooting.
   27  *  - @ref LE_LOG_WARN "WARNING":
   28  *    Should not normally happen; may not have any real impact on system performance.
   29  *  - @ref LE_LOG_ERR "ERROR":
   30  *    Fault that may result in noticeable short-term system misbehaviour. Needs attention.
   31  *  - @ref LE_LOG_CRIT "CRITICAL":
   32  *    Fault needs urgent attention. Will likely result in system failure.
   33  *  - @ref LE_LOG_EMERG "EMERGENCY":
   34  *    Definite system failure.
   35  *
   36  * @subsection c_log_basic_defaultSyslog Standard Out and Standard Error in Syslog
   37  *
   38  * By default, app processes will have their @c stdout and @c stderr redirected to the @c syslog. Each
   39  * process’s stdout will be logged at INFO severity level; it’s stderr will be logged at
   40  * “ERR” severity level.
   41 
   42  * There are two limitations with this feature:
   43  * - the PID reported in the logs generally refer to the PID of the process that
   44  * generates the stdout/stderr message. If a process forks, then both the parent and
   45  * child processes’ stdout/stderr will share the same connection to the syslog, and the parent’s
   46  * PID will be reported in the logs for both processes.
   47  * - stdout is line buffered when connected to a terminal, which means
   48  * <code>printf(“hello\n”)</code> will be printed to the terminal immediately. If stdout is
   49  * connected to something like a pipe it's bulk buffered, which means a flush doesn't occur until the buffer is full.
   50  *
   51  * To make your process line buffer stdout so that printf will show up in the logs as expected,
   52  * the @c setlinebuf(stdout) system call can be used.  Alternatively, @c fflush(stdout) can be called \
   53  * to force a flush of the stdout buffer.
   54  *
   55  * This issue doesn't exist with stderr as stderr is never buffered.
   56  *
   57  * @subsection c_log_basic_logging Basic Logging
   58  *
   59  * A series of macros are available to make logging easy.
   60  *
   61  * None of them return anything.
   62  *
   63  * All of them accept printf-style arguments, consisting of a format string followed by zero or more
   64  * parameters to be printed (depending on the contents of the format string).
   65  *
   66  * There is a logging macro for each of the log levels:
   67  *
   68  *  - @ref LE_DEBUG(formatString, ...)
   69  *  - @ref LE_INFO(formatString, ...)
   70  *  - @ref LE_WARN(formatString, ...)
   71  *  - @ref LE_ERROR(formatString, ...)
   72  *  - @ref LE_CRIT(formatString, ...)
   73  *  - @ref LE_EMERG(formatString, ...)
   74  *
   75  * For example,
   76  * @code
   77  * LE_INFO("Obtained new IP address %s.", ipAddrStr);
   78  * @endcode
   79  *
   80  * @subsection c_log_conditional_logging Conditional Logging
   81  *
   82  * Similar to the basic macros, but these contain a conditional expression as their first parameter.  If this expression equals
   83  * true, then the macro will generate this log output:
   84  *
   85  *  - @ref LE_DEBUG_IF(expression, formatString, ...)
   86  *  - @ref LE_INFO_IF(expression, formatString, ...)
   87  *  - @ref LE_WARN_IF(expression, formatString, ...)
   88  *  - @ref LE_ERROR_IF(expression, formatString, ...)
   89  *  - @ref LE_CRIT_IF(expression, formatString, ...)
   90  *  - @ref LE_EMERG_IF(expression, formatString, ...)
   91  *
   92  * Instead of writing
   93  * @code
   94  * if (result == -1)
   95  * {
   96  *     LE_WARN("Failed to send message to server.  Errno = %d.", errno);
   97  * }
   98  * @endcode
   99  *
  100  * you could write this:
  101  * @code
  102  * LE_WARN_IF(result == -1, "Failed to send message to server.  Errno = %d.", errno);
  103  * @endcode
  104  *
  105  * @subsection c_log_loging_fatals Fatal Errors
  106  *
  107  * There are some special logging macros intended for fatal errors:
  108  *
  109  *  - @ref LE_FATAL(formatString, ...) \n
  110  *    Always kills the calling process after logging the message at EMERGENCY level (never returns).
  111  *  - @ref LE_FATAL_IF(condition, formatString, ...) \n
  112  *    If the condition is true, kills the calling process after logging the message at EMERGENCY
  113  *    level.
  114  *  - @ref LE_ASSERT(condition) \n
  115  *    If the condition is true, does nothing. If the condition is false, logs the source
  116  *    code text of the condition at EMERGENCY level and kills the calling process.
  117  *  - @ref LE_ASSERT_OK(condition) \n
  118  *    If the condition is LE_OK (0), does nothing. If the condition is anything else, logs the
  119  *    a message at EMERGENCY level, containing the source code text of the condition, indicating
  120  *    that it did not evaluate to LE_OK, and kills the calling process.
  121  *
  122  * For example,
  123  * @code
  124  * if (NULL == objPtr)
  125  * {
  126  *     LE_FATAL("Object pointer is NULL!");
  127  * }
  128  *
  129  * // Now I can go ahead and use objPtr, knowing that if it was NULL then LE_FATAL() would have
  130  * // been called and LE_FATAL() never returns.
  131  * @endcode
  132  *
  133  * or,
  134  *
  135  * @code
  136  * LE_FATAL_IF(NULL == objPtr, "Object pointer is NULL!");
  137  *
  138  * // Now I can go ahead and use objPtr, knowing that if it was NULL then LE_FATAL_IF() would not
  139  * // have returned.
  140  * @endcode
  141  *
  142  * or,
  143  *
  144  * @code
  145  * LE_ASSERT(NULL != objPtr);
  146  *
  147  * // Now I can go ahead and use objPtr, knowing that if it was NULL then LE_ASSERT() would not
  148  * // have returned.
  149  * @endcode
  150  *
  151  * @subsection c_log_tracing Tracing
  152  *
  153  * Finally, a macro is provided for tracing:
  154  *
  155  *  - @ref LE_TRACE(traceRef, string, ...)
  156  *
  157  * This macro is special because it's independent of log level.  Instead, trace messages are
  158  * associated with a trace keyword.  Tracing can be enabled and disabled based on these keywords.
  159  *
  160  * If a developer wanted to trace the creation of "shape"
  161  * objects in their GUI package, they could add trace statements like the following:
  162  *
  163  * @code
  164  * LE_TRACE(NewShapeTraceRef, "Created %p with position (%d,%d).", shapePtr, shapePtr->x, shapePtr->y);
  165  * @endcode
  166  *
  167  * The reference to the trace is obtained at start-up as follows:
  168  *
  169  * @code
  170  * NewShapeTraceRef = le_log_GetTraceRef("newShape");
  171  * @endcode
  172  *
  173  * This allows enabling and disabling these LE_TRACE() calls using the "newShape" keyword
  174  * through configuration settings and runtime log control tools.  See @ref c_log_controlling below.
  175  *
  176  * Applications can use @ref LE_IS_TRACE_ENABLED(NewShapeTraceRef) to query whether
  177  * a trace keyword is enabled.
  178  *
  179  * These allow apps to hook into the trace management system to use it to implement
  180  * sophisticated, app-specific tracing or profiling features.
  181  *
  182  * @subsection c_log_resultTxt Result Code Text
  183  *
  184  * The @ref le_result_t macro supports printing an error condition in a human-readable text string.
  185  *
  186  * @code
  187  * result = le_foo_DoSomething();
  188  *
  189  * if (result != LE_OK)
  190  * {
  191  *     LE_ERROR("Failed to do something. Result = %d (%s).", result, LE_RESULT_TXT(result));
  192  * }
  193  * @endcode
  194  *
  195  *
  196  * @section c_log_controlling Log Controls
  197  *
  198  * Log level filtering and tracing can be controlled at runtime using:
  199  *  - the command-line Log Control Tool (@ref toolsTarget_log)
  200  *  - configuration settings
  201  *  - environment variables
  202  *  - function calls.
  203  *
  204  * @subsection c_log_control_tool Log Control Tool
  205  *
  206  * The log control tool is used from the command-line to control the log
  207  * level filtering, log output location (syslog/stderr), and tracing for different components
  208  * within a running system.
  209  *
  210  * Online documentation can be accessed from the log control tool by running "log help".
  211  *
  212  * Here are some code samples.
  213  *
  214  * To set the log level to INFO for a component "myComp" running in all processes with the
  215  * name "myProc":
  216  * @verbatim
  217 $ log level INFO myProc/myComp
  218 @endverbatim
  219  *
  220  * To set the log level to DEBUG for a component "myComp" running in a process with PID 1234:
  221  * @verbatim
  222 $ log level DEBUG 1234/myComp
  223 @endverbatim
  224  *
  225  * To enable all LE_TRACE statements tagged with the keyword "foo" in a component called "myComp"
  226  * running in all processes called "myProc":
  227  * @verbatim
  228 $ log trace foo myProc/myComp
  229 @endverbatim
  230  *
  231  * To disable the trace statements tagged with "foo" in the component "myComp" in processes
  232  * called "myProc":
  233  * @verbatim
  234 $ log stoptrace foo myProc/myComp
  235 @endverbatim
  236  *
  237  * With all of the above examples "*" can be used in place of the process name or a component
  238  * name (or both) to mean "all processes" and/or "all components".
  239  *
  240  * @subsection c_log_control_config Log Control Configuration Settings
  241  *
  242  * @note The configuration settings haven't been implemented yet.
  243  *
  244  * @todo Write @ref c_log_control_config section.
  245  *
  246  * @subsection c_log_control_environment_vars Environment Variables
  247  *
  248  * Environment variables can be used to control the default log settings, taking effect immediately
  249  * at process start-up; even before the Log Control Daemon has been connected to.
  250  *
  251  * Settings in the Log Control Daemon (applied through configuration and/or the log control tool)
  252  * will override the environment variable settings when the process connects to the Log
  253  * Control Daemon.
  254  *
  255  * @subsubsection c_log_control_env_level LE_LOG_LEVEL
  256  *
  257  * @c LE_LOG_LEVEL can be used to set the default log filter level for all components
  258  * in the process.  Valid values are:
  259  *
  260  * - @c EMERGENCY
  261  * - @c CRITICAL
  262  * - @c ERROR
  263  * - @c WARNING
  264  * - @c INFO
  265  * - @c DEBUG
  266  *
  267  * For example,
  268  * @verbatim
  269 $ export LE_LOG_LEVEL=DEBUG
  270 @endverbatim
  271  *
  272  * @subsubsection c_log_control_env_trace LE_LOG_TRACE
  273  *
  274  * @c LE_LOG_TRACE allows trace keywords to be enabled by default.  The contents of this
  275  * variable is a colon-separated list of keywords that should be enabled. Each keyword
  276  * must be prefixed with a component name followed by a slash ('/').
  277  *
  278  * For example,
  279  * @verbatim
  280 $ export LE_LOG_TRACE=framework/fdMonitor:framework/logControl
  281 @endverbatim
  282  *
  283  * @subsection c_log_control_functions Programmatic Log Control
  284  *
  285  * Normally, configuration settings and the log control tool should suffice for controlling
  286  * logging functionality.  In some situations, it can be convenient
  287  * to control logging programmatically in C.
  288  *
  289  * le_log_SetFilterLevel() sets the log filter level.
  290  *
  291  * le_log_GetFilterLevel() gets the log filter level.
  292  *
  293  * Trace keywords can be enabled and disabled programmatically by calling
  294  * @subpage le_log_EnableTrace() and @ref le_log_DisableTrace().
  295  *
  296  *
  297  * @section c_log_format Log Formats
  298  *
  299  * Log entries can also contain any of these:
  300  *  - timestamp (century, year, month, day, hours, minutes, seconds, milliseconds, microseconds)
  301  *  - level (debug, info, warning, etc.) @b or trace keyword
  302  *  - process ID
  303  *  - component name
  304  *  - thread name
  305  *  - source code file name
  306  *  - function name
  307  *  - source code line number
  308  *
  309  * Log messages have the following format:
  310  *
  311  * @verbatim
  312 Jan  3 02:37:56  INFO  | processName[pid]/componentName T=threadName | fileName.c funcName() lineNum | Message
  313 @endverbatim
  314  *
  315  * @section c_log_debugFiles App Crash Logs
  316 
  317 * When a process within an app faults or exits in error, a copy of the current syslog buffer
  318 * is captured along with a core file of the process crash (if generated).
  319 
  320 * The core file maximum size is determined by the process settings @c maxCoreDumpFileBytes and
  321 * @c maxFileBytes found in the processes section of your app's @c .adef file.  By default, the
  322 * @c maxCoreDumpFileBytes is set to 0, do not create a core file.
  323 
  324 * To help save the target from flash burnout, the syslog and core files are stored in the RAM
  325 * FS under /tmp.  When a crash occurs, this directory is created:
  326 
  327  @verbatim
  328  /tmp/legato_logs/
  329  @endverbatim
  330 
  331 * The files in that directory look like this:
  332 
  333  @verbatim
  334  core-myProc-1418694851
  335  syslog-myApp-myProc-1418694851
  336  @endverbatim
  337 
  338 * To save on RAM space, only the most recent 4 copies of each file are preserved.
  339 
  340 * If the fault action for that app's process is to reboot the target, the output location is changed to
  341 * this (and the most recent files in RAM space are preserved across reboots):
  342 
  343  @verbatim
  344  /mnt/flash/legato_logs/
  345  @endverbatim
  346 
  347 *
  348  * @todo May need to support log format configuration through command-line arguments or a
  349  *       configuration file.
  350  *
  351  * @todo Write @ref c_log_retrieving section
  352  *
  353  * <HR>
  354  *
  355  * Copyright (C) Sierra Wireless Inc.
  356  */
  357 
  358 
  359 /** @file le_log.h
  360  *
  361  * Legato @ref c_logging include file.
  362  *
  363  * Copyright (C) Sierra Wireless Inc.
  364  */
  365 
  366 #ifndef LEGATO_LOG_INCLUDE_GUARD
  367 #define LEGATO_LOG_INCLUDE_GUARD
  368 
  369 //--------------------------------------------------------------------------------------------------
  370 /**
  371  * Local definitions that should not be used directly.
  372  */
  373 //--------------------------------------------------------------------------------------------------
  374 typedef enum _le_log_Level_t
  375 {
  376     LE_LOG_DEBUG,   ///< Debug message.
  377     LE_LOG_INFO,    ///< Informational message.  Normally expected.
  378     LE_LOG_WARN,    ///< Warning.  Possibly indicates a problem.  Should be addressed.
  379     LE_LOG_ERR,     ///< Error.  Definitely indicates a  fault that needs to be addressed.
  380                     ///  Possibly resulted in a system failure.
  381     LE_LOG_CRIT,    ///< Critical error.  Fault that almost certainly has or will result in a
  382                     ///  system failure.
  383     LE_LOG_EMERG,   ///< Emergency.  A fatal error has occurred.  A process is being terminated.
  384     LE_LOG_MAX      ///< One beyond maximum log level
  385 }
  386 le_log_Level_t;
  387 
  388 //--------------------------------------------------------------------------------------------------
  389 /**
  390  * Compile-time filtering level.
  391  *
  392  * @note Logs below this filter level will be removed at compile-time and cannot be enabled
  393  *       at runtime.
  394  */
  395 //--------------------------------------------------------------------------------------------------
  396 #if LE_CONFIG_LOG_STATIC_FILTER_NO_LOG
  397 #   define LE_LOG_LEVEL_STATIC_FILTER   LE_LOG_MAX
  398 #elif LE_CONFIG_LOG_STATIC_FILTER_EMERG
  399 #   define LE_LOG_LEVEL_STATIC_FILTER   LE_LOG_EMERG
  400 
  401 #   define LE_EMERG_ENABLED 1
  402 #elif LE_CONFIG_LOG_STATIC_FILTER_CRIT
  403 #   define LE_LOG_LEVEL_STATIC_FILTER   LE_LOG_CRIT
  404 
  405 #   define LE_EMERG_ENABLED 1
  406 #   define LE_CRIT_ENABLED  1
  407 #elif LE_CONFIG_LOG_STATIC_FILTER_ERR
  408 #   define LE_LOG_LEVEL_STATIC_FILTER   LE_LOG_ERR
  409 
  410 #   define LE_EMERG_ENABLED 1
  411 #   define LE_CRIT_ENABLED  1
  412 #   define LE_ERROR_ENABLED 1
  413 #elif LE_CONFIG_LOG_STATIC_FILTER_WARN
  414 #   define LE_LOG_LEVEL_STATIC_FILTER   LE_LOG_WARN
  415 
  416 #   define LE_EMERG_ENABLED 1
  417 #   define LE_CRIT_ENABLED  1
  418 #   define LE_ERROR_ENABLED 1
  419 #   define LE_WARN_ENABLED  1
  420 #elif LE_CONFIG_LOG_STATIC_FILTER_INFO
  421 #   define LE_LOG_LEVEL_STATIC_FILTER   LE_LOG_INFO
  422 
  423 #   define LE_EMERG_ENABLED 1
  424 #   define LE_CRIT_ENABLED  1
  425 #   define LE_ERROR_ENABLED 1
  426 #   define LE_WARN_ENABLED  1
  427 #   define LE_INFO_ENABLED  1
  428 #else /* default to LE_DEBUG */
  429 #   define LE_LOG_LEVEL_STATIC_FILTER   LE_LOG_DEBUG
  430 
  431 #   define LE_EMERG_ENABLED 1
  432 #   define LE_CRIT_ENABLED  1
  433 #   define LE_ERROR_ENABLED 1
  434 #   define LE_WARN_ENABLED  1
  435 #   define LE_INFO_ENABLED  1
  436 #   define LE_DEBUG_ENABLED 1
  437 #endif
  438 
  439 //--------------------------------------------------------------------------------------------------
  440 /// @cond HIDDEN_IN_USER_DOCS
  441 
  442 typedef struct le_log_Session* le_log_SessionRef_t;
  443 
  444 typedef struct le_log_Trace* le_log_TraceRef_t;
  445 
  446 #if !defined(LE_DEBUG) && \
  447     !defined(LE_DUMP) && \
  448     !defined(LE_LOG_DUMP) && \
  449     !defined(LE_INFO) && \
  450     !defined(LE_WARN) && \
  451     !defined(LE_ERROR) && \
  452     !defined(LE_CRIT) && \
  453     !defined(LE_EMERG)
  454 
  455 /// Default log implementation is in use.
  456 #   define LE_LOG_DEFAULT_IMPL 1
  457 
  458 //--------------------------------------------------------------------------------------------------
  459 /**
  460  * Send a message to the logging target.
  461  **/
  462 //--------------------------------------------------------------------------------------------------
  463 void _le_log_Send
  464 (
  465     const le_log_Level_t     level,             ///< Log level.
  466     const le_log_TraceRef_t  traceRef,          ///< Trace reference.  May be NULL.
  467     le_log_SessionRef_t      logSession,        ///< Log session.  May be NULL.
  468     const char              *filenamePtr,       ///< File name.
  469     const char              *functionNamePtr,   ///< Function name.  May be NULL.
  470     const unsigned int       lineNumber,        ///< Line number.
  471     const char              *formatPtr,         ///< Format string.
  472     ...                                         ///< Positional parameters.
  473 ) __attribute__((format (printf, 7, 8)));
  474 
  475 //--------------------------------------------------------------------------------------------------
  476 /**
  477  * Log data block.  Provides a hex dump for debug.
  478  */
  479 //--------------------------------------------------------------------------------------------------
  480 void _le_LogData
  481 (
  482     le_log_Level_t       level,             ///< Log level.
  483     const uint8_t       *dataPtr,           ///< The buffer address to be dumped.
  484     int                  dataLength,        ///< The data length of buffer.
  485     const char          *filenamePtr,       ///< The name of the source file that logged the
  486                                             ///< message.
  487     const char          *functionNamePtr,   ///< The name of the function that logged the message.
  488     const unsigned int   lineNumber         ///< The line number in the source file that logged the
  489                                             ///< message.
  490 );
  491 
  492 //--------------------------------------------------------------------------------------------------
  493 /**
  494  * Gets a reference to a trace keyword's settings.
  495  *
  496  * @return  Trace reference.
  497  **/
  498 //--------------------------------------------------------------------------------------------------
  499 le_log_TraceRef_t _le_log_GetTraceRef
  500 (
  501     le_log_SessionRef_t  logSession,    ///< Log session.
  502     const char          *keyword        ///< Trace keyword.
  503 );
  504 
  505 //--------------------------------------------------------------------------------------------------
  506 /**
  507  * Sets the log filter level for the calling component.
  508  **/
  509 //--------------------------------------------------------------------------------------------------
  510 void _le_log_SetFilterLevel
  511 (
  512     le_log_SessionRef_t logSession, ///< Log session.
  513     le_log_Level_t      level       ///< Log level to apply.
  514 );
  515 
  516 //--------------------------------------------------------------------------------------------------
  517 /**
  518  * Filtering session reference for the current source file.
  519  *
  520  * @note The real name of this is passed in by the build system. This way it can be a unique
  521  *       variable for each component.
  522  */
  523 //--------------------------------------------------------------------------------------------------
  524 extern LE_SHARED le_log_SessionRef_t LE_LOG_SESSION;
  525 
  526 //--------------------------------------------------------------------------------------------------
  527 /**
  528  * Filtering level for the current source file.
  529  *
  530  * @note The real name of this is passed in by the build system. This way it can be a unique
  531  *       variable for each component.
  532  */
  533 //--------------------------------------------------------------------------------------------------
  534 extern LE_SHARED le_log_Level_t* LE_LOG_LEVEL_FILTER_PTR;
  535 
  536 //--------------------------------------------------------------------------------------------------
  537 /**
  538  * Internal macro to set whether the function name is displayed with log messages.
  539  */
  540 //--------------------------------------------------------------------------------------------------
  541 #if LE_CONFIG_LOG_FUNCTION_NAMES
  542 #   define _LE_LOG_FUNCTION_NAME __func__
  543 #else
  544 #   define _LE_LOG_FUNCTION_NAME NULL
  545 #endif
  546 
  547 /// @endcond
  548 //--------------------------------------------------------------------------------------------------
  549 
  550 //--------------------------------------------------------------------------------------------------
  551 /**
  552  * Internal macro to filter out messages that do not meet the current filtering level.
  553  */
  554 //--------------------------------------------------------------------------------------------------
  555 #define _LE_LOG_MSG(level, formatString, ...) \
  556     do { \
  557         if ((level >= LE_LOG_LEVEL_STATIC_FILTER) &&                        \
  558             ((LE_LOG_LEVEL_FILTER_PTR == NULL) || (level >= *LE_LOG_LEVEL_FILTER_PTR))) \
  559             _le_log_Send(level, NULL, LE_LOG_SESSION, __FILE__, _LE_LOG_FUNCTION_NAME, __LINE__, \
  560                     formatString, ##__VA_ARGS__); \
  561     } while(0)
  562 
  563 
  564 //--------------------------------------------------------------------------------------------------
  565 /** @internal
  566  * The following macros are used to send log messages at different severity levels:
  567  *
  568  * Accepts printf-style arguments, consisting of a format string followed by zero or more parameters
  569  * to be printed (depending on the contents of the format string).
  570  */
  571 //--------------------------------------------------------------------------------------------------
  572 
  573 /** @copydoc LE_LOG_DEBUG */
  574 #define LE_DEBUG(formatString, ...)     _LE_LOG_MSG(LE_LOG_DEBUG, formatString, ##__VA_ARGS__)
  575 
  576 //--------------------------------------------------------------------------------------------------
  577 /**
  578  * Dump a buffer of data as hexadecimal to the log at debug level.
  579  *
  580  *  @param  dataPtr     Binary data to dump.
  581  *  @param  dataLength  Length og the buffer.
  582  */
  583 //--------------------------------------------------------------------------------------------------
  584 #define LE_DUMP(dataPtr, dataLength)                                                              \
  585     _le_LogData(LE_LOG_DEBUG, dataPtr, dataLength, STRINGIZE(LE_FILENAME), _LE_LOG_FUNCTION_NAME, \
  586         __LINE__)
  587 
  588 //--------------------------------------------------------------------------------------------------
  589 /**
  590  * Dump a buffer of data as hexadecimal to the log at the specified level.
  591  *
  592  *  @param  level       Log level.
  593  *  @param  dataPtr     Binary data to dump.
  594  *  @param  dataLength  Length of the buffer.
  595  */
  596 //--------------------------------------------------------------------------------------------------
  597 #define LE_LOG_DUMP(level, dataPtr, dataLength) \
  598     _le_LogData(level, dataPtr, dataLength, STRINGIZE(LE_FILENAME), _LE_LOG_FUNCTION_NAME, __LINE__)
  599 /** @copydoc LE_LOG_INFO */
  600 #define LE_INFO(formatString, ...)      _LE_LOG_MSG(LE_LOG_INFO, formatString, ##__VA_ARGS__)
  601 /** @copydoc LE_LOG_WARN */
  602 #define LE_WARN(formatString, ...)      _LE_LOG_MSG(LE_LOG_WARN, formatString, ##__VA_ARGS__)
  603 /** @copydoc LE_LOG_ERR */
  604 #define LE_ERROR(formatString, ...)     _LE_LOG_MSG(LE_LOG_ERR, formatString, ##__VA_ARGS__)
  605 /** @copydoc LE_LOG_CRIT */
  606 #define LE_CRIT(formatString, ...)      _LE_LOG_MSG(LE_LOG_CRIT, formatString, ##__VA_ARGS__)
  607 /** @copydoc LE_LOG_EMERG */
  608 #define LE_EMERG(formatString, ...)     _LE_LOG_MSG(LE_LOG_EMERG, formatString, ##__VA_ARGS__)
  609 
  610 
  611 //--------------------------------------------------------------------------------------------------
  612 /**
  613  * Mark tracing as used, so trace-related code can be compiled in.
  614  */
  615 //--------------------------------------------------------------------------------------------------
  616 #define LE_LOG_CAN_TRACE        1
  617 
  618 
  619 //--------------------------------------------------------------------------------------------------
  620 /**
  621  * Queries whether or not a trace keyword is enabled.
  622  *
  623  * @return
  624  *      true if the keyword is enabled.
  625  *      false otherwise.
  626  */
  627 //--------------------------------------------------------------------------------------------------
  628 #define LE_IS_TRACE_ENABLED(traceRef)  (le_log_IsTraceEnabled(traceRef))
  629 
  630 
  631 //--------------------------------------------------------------------------------------------------
  632 /**
  633  * Logs the string if the keyword has been enabled by a runtime tool or configuration setting.
  634  */
  635 //--------------------------------------------------------------------------------------------------
  636 #define LE_TRACE(traceRef, string, ...)             \
  637     do  {                                           \
  638             if (le_log_IsTraceEnabled(traceRef))    \
  639             {                                       \
  640                 _le_log_Send((le_log_Level_t)-1,    \
  641                         traceRef,                   \
  642                         LE_LOG_SESSION,             \
  643                         STRINGIZE(LE_FILENAME),     \
  644                         _LE_LOG_FUNCTION_NAME,      \
  645                         __LINE__,                   \
  646                         string,                     \
  647                         ##__VA_ARGS__);             \
  648             }                                       \
  649         } while(0)
  650 
  651 //--------------------------------------------------------------------------------------------------
  652 /**
  653  * Gets a reference to a trace keyword's settings.
  654  *
  655  * @param keywordPtr   [IN] Pointer to the keyword string.
  656  *
  657  * @return  Trace reference.
  658  **/
  659 //--------------------------------------------------------------------------------------------------
  660 #define le_log_GetTraceRef(keywordPtr)                  \
  661     _le_log_GetTraceRef(LE_LOG_SESSION, (keywordPtr))
  662 
  663 
  664 //--------------------------------------------------------------------------------------------------
  665 /**
  666  * Determines if a trace is currently enabled.
  667  *
  668  * @param traceRef    [IN] Trace reference obtained from le_log_GetTraceRef()
  669  *
  670  * @return  true if enabled, false if not.
  671  **/
  672 //--------------------------------------------------------------------------------------------------
  673 #define le_log_IsTraceEnabled(traceRef) ((traceRef) == NULL ? false : *((bool *) (traceRef)))
  674 
  675 
  676 //--------------------------------------------------------------------------------------------------
  677 /**
  678  * Sets the log filter level for the calling component.
  679  *
  680  * @note    Normally not necessary as the log filter level can be controlled at
  681  *          runtime using the log control tool, and can be persistently configured.
  682  *          See @ref c_log_controlling.
  683  *
  684  * @param level   [IN] Log filter level to apply to the current log session.
  685  **/
  686 //--------------------------------------------------------------------------------------------------
  687 #define le_log_SetFilterLevel(level)                    \
  688     _le_log_SetFilterLevel(LE_LOG_SESSION, (level))
  689 
  690 
  691 //--------------------------------------------------------------------------------------------------
  692 /**
  693  * Gets the log filter level for the calling component.
  694  **/
  695 //--------------------------------------------------------------------------------------------------
  696 #define le_log_GetFilterLevel()                 \
  697     ((LE_LOG_LEVEL_FILTER_PTR != NULL)?(*LE_LOG_LEVEL_FILTER_PTR):(LE_LOG_INFO))
  698 
  699 
  700 //--------------------------------------------------------------------------------------------------
  701 /**
  702  * Enables a trace.
  703  *
  704  * @note    Normally, this is not necessary, since traces can be enabled at runtime using the
  705  *          log control tool and can be persistently configured.  See @ref c_log_controlling.
  706  *
  707  * @param traceRef    [IN] Trace reference obtained from le_log_GetTraceRef()
  708  *
  709  **/
  710 //--------------------------------------------------------------------------------------------------
  711 #define le_log_EnableTrace(traceRef)            \
  712     ((void)(*((bool*)(traceRef)) = true))
  713 
  714 
  715 //--------------------------------------------------------------------------------------------------
  716 /**
  717  * Disables a trace.
  718  *
  719  * @note    Normally, this is not necessary, since traces can be enabled at runtime using the
  720  *          log control tool and can be persistently configured.  See @ref c_log_controlling.
  721  *
  722  * @param traceRef    [IN] Trace reference obtained from le_log_GetTraceRef()
  723  *
  724  **/
  725 //--------------------------------------------------------------------------------------------------
  726 #define le_log_DisableTrace(traceRef)           \
  727     ((void)(*((bool*)(traceRef)) = false))
  728 
  729 #else
  730 
  731 // If any logging macro is overridden, all logging macros must be overridden.
  732 #if !defined(LE_DEBUG)
  733 #  error "Logging are overridden, but LE_DEBUG not defined.  Define LE_DEBUG."
  734 #endif
  735 
  736 #if !defined(LE_DUMP)
  737 #  error "Logging are overridden, but LE_DUMP not defined.  Define LE_DUMP."
  738 #endif
  739 
  740 #if !defined(LE_LOG_DUMP)
  741 #  error "Logging are overridden, but LE_LOG_DUMP not defined.  Define LE_LOG_DUMP."
  742 #endif
  743 
  744 #if !defined(LE_INFO)
  745 #  error "Logging are overridden, but LE_INFO not defined.  Define LE_INFO."
  746 #endif
  747 
  748 #if !defined(LE_WARN)
  749 #  error "Logging are overridden, but LE_WARN not defined.  Define LE_WARN."
  750 #endif
  751 
  752 #if !defined(LE_ERROR)
  753 #  error "Logging are overridden, but LE_ERROR not defined.  Define LE_ERROR."
  754 #endif
  755 
  756 #if !defined(LE_CRIT)
  757 #  error "Logging are overridden, but LE_CRIT not defined.  Define LE_CRIT."
  758 #endif
  759 
  760 #if !defined(LE_EMERG)
  761 #  error "Logging are overridden, but LE_EMERG not defined.  Define LE_EMERG."
  762 #endif
  763 
  764 // If SetFilterLevel is not defined when logging is overridden,
  765 // assume it cannot be set programatically
  766 #ifndef le_log_SetFilterLevel
  767 //--------------------------------------------------------------------------------------------------
  768 /**
  769  * Sets the log filter level for the calling component.
  770  *
  771  * @note    Normally not necessary as the log filter level can be controlled at
  772  *          runtime using the log control tool, and can be persistently configured.
  773  *          See @ref c_log_controlling.
  774  *
  775  * @param level   [IN] Log filter level to apply to the current log session.
  776  **/
  777 //--------------------------------------------------------------------------------------------------
  778 #define le_log_SetFilterLevel(level) ((void)(level))
  779 #endif
  780 
  781 
  782 // If le_log_GetFilterLevel is not defined when logging is overridden, assume it
  783 // cannot be obtained programatically.  In this case code should assume filter level
  784 // is equal to static filter level
  785 #ifndef le_log_GetFilterLevel
  786 //--------------------------------------------------------------------------------------------------
  787 /**
  788  * Gets the log filter level for the calling component.
  789  **/
  790 //--------------------------------------------------------------------------------------------------
  791 #define le_log_GetFilterLevel()  (LE_LOG_LEVEL_STATIC_FILTER)
  792 #endif
  793 
  794 //--------------------------------------------------------------------------------------------------
  795 /*
  796  * If logging is overridden, disable Legato tracing mechanism.  Tracing is noisy and should
  797  * not be put into general logs.
  798  */
  799 //--------------------------------------------------------------------------------------------------
  800 
  801 //--------------------------------------------------------------------------------------------------
  802 /**
  803  * Queries whether or not a trace keyword is enabled.
  804  *
  805  * @return
  806  *      true if the keyword is enabled.
  807  *      false otherwise.
  808  */
  809 //--------------------------------------------------------------------------------------------------
  810 #define LE_IS_TRACE_ENABLED(traceRef)  (false)
  811 
  812 
  813 //--------------------------------------------------------------------------------------------------
  814 /**
  815  * Logs the string if the keyword has been enabled by a runtime tool or configuration setting.
  816  */
  817 //--------------------------------------------------------------------------------------------------
  818 #define LE_TRACE(traceRef, string, ...) ((void)(traceRef))
  819 
  820 
  821 //--------------------------------------------------------------------------------------------------
  822 /**
  823  * Gets a reference to a trace keyword's settings.
  824  *
  825  * @param keywordPtr   [IN] Pointer to the keyword string.
  826  *
  827  * @return  Trace reference.
  828  **/
  829 //--------------------------------------------------------------------------------------------------
  830 #define le_log_GetTraceRef(keywordPtr) ((le_log_TraceRef_t)NULL)
  831 
  832 
  833 //--------------------------------------------------------------------------------------------------
  834 /**
  835  * Determines if a trace is currently enabled.
  836  *
  837  * @param traceRef    [IN] Trace reference obtained from le_log_GetTraceRef()
  838  *
  839  * @return  true if enabled, false if not.
  840  **/
  841 //--------------------------------------------------------------------------------------------------
  842 #define le_log_IsTraceEnabled(traceRef) (false)
  843 
  844 
  845 //--------------------------------------------------------------------------------------------------
  846 /**
  847  * Enables a trace.
  848  *
  849  * @note    Normally, this is not necessary, since traces can be enabled at runtime using the
  850  *          log control tool and can be persistently configured.  See @ref c_log_controlling.
  851  *
  852  * @param traceRef    [IN] Trace reference obtained from le_log_GetTraceRef()
  853  *
  854  **/
  855 //--------------------------------------------------------------------------------------------------
  856 #define le_log_EnableTrace(traceRef) ((void)(0))
  857 
  858 
  859 //--------------------------------------------------------------------------------------------------
  860 /**
  861  * Disables a trace.
  862  *
  863  * @note    Normally, this is not necessary, since traces can be enabled at runtime using the
  864  *          log control tool and can be persistently configured.  See @ref c_log_controlling.
  865  *
  866  * @param traceRef    [IN] Trace reference obtained from le_log_GetTraceRef()
  867  *
  868  **/
  869 //--------------------------------------------------------------------------------------------------
  870 #define le_log_DisableTrace(traceRef) ((void)(0))
  871 
  872 #endif /* Logging macro override */
  873 
  874 /// Function that does the real work of translating result codes.  See @ref LE_RESULT_TXT.
  875 const char* _le_log_GetResultCodeString
  876 (
  877     le_result_t resultCode  ///< [in] Result code value to be translated.
  878 );
  879 
  880 /// Function that does the real work of translating result codes.  See @ref LE_RESULT_TXT.
  881 const char* _le_log_GetErrnoCodeString
  882 (
  883     int errnoCode  ///< [in] errno value to be translated.
  884 );
  885 
  886 /// Function that exits in a race-free manner -- work around glibc BZ#14333
  887 __attribute__((noreturn))
  888 void _le_log_ExitFatal
  889 (
  890     void
  891 );
  892 
  893 //--------------------------------------------------------------------------------------------------
  894 /** @internal
  895  * The following macros are used to send log messages at different severity levels conditionally.
  896  * If the condition is true the message is logged.  If the condition is false the message is not
  897  * logged.
  898  *
  899  * Accepts printf-style arguments, consisting of a format string followed by zero or more parameters
  900  * to be printed (depending on the contents of the format string).
  901  */
  902 //--------------------------------------------------------------------------------------------------
  903 
  904 /** @ref LE_DEBUG if condition is met. */
  905 #define LE_DEBUG_IF(condition, formatString, ...)                   \
  906     do                                                              \
  907     {                                                               \
  908         if (condition) { LE_DEBUG(formatString, ##__VA_ARGS__); }   \
  909     } while (0)
  910 
  911 /** @ref LE_INFO if condition is met. */
  912 #define LE_INFO_IF(condition, formatString, ...)                    \
  913     do                                                              \
  914     {                                                               \
  915         if (condition) { LE_INFO(formatString, ##__VA_ARGS__); }    \
  916     } while (0)
  917 
  918 /** @ref LE_WARN if condition is met. */
  919 #define LE_WARN_IF(condition, formatString, ...)                    \
  920     do                                                              \
  921     {                                                               \
  922         if (condition) { LE_WARN(formatString, ##__VA_ARGS__); }    \
  923     } while (0)
  924 
  925 /** @ref LE_ERROR if condition is met. */
  926 #define LE_ERROR_IF(condition, formatString, ...)                   \
  927     do                                                              \
  928     {                                                               \
  929         if (condition) { LE_ERROR(formatString, ##__VA_ARGS__); }   \
  930     } while (0)
  931 
  932 /** @ref LE_CRIT if condition is met. */
  933 #define LE_CRIT_IF(condition, formatString, ...)                    \
  934     do                                                              \
  935     {                                                               \
  936         if (condition) { LE_CRIT(formatString, ##__VA_ARGS__); }    \
  937     } while (0)
  938 
  939 /** @ref LE_EMERG if condition is met. */
  940 #define LE_EMERG_IF(condition, formatString, ...)                   \
  941     do                                                              \
  942     {                                                               \
  943         if (condition) { LE_EMERG(formatString, ##__VA_ARGS__); }   \
  944     } while (0)
  945 
  946 //--------------------------------------------------------------------------------------------------
  947 /**
  948  * Log fatal errors by killing the calling process after logging the message at EMERGENCY
  949  * level.  This macro never returns.
  950  *
  951  * Accepts printf-style arguments, consisting of a format string followed by zero or more parameters
  952  * to be printed (depending on the contents of the format string).
  953  */
  954 //--------------------------------------------------------------------------------------------------
  955 #ifndef LE_FATAL
  956 #   if !LE_CONFIG_DEBUG
  957 #       define LE_FATAL(formatString, ...)                              \
  958         do{                                                             \
  959             LE_EMERG(formatString, ##__VA_ARGS__); _le_log_ExitFatal(); \
  960         } while(0)
  961 #   else
  962 #       define LE_FATAL(formatString, ...)                              \
  963         do {                                                            \
  964             LE_EMERG(formatString, ##__VA_ARGS__); abort();             \
  965         } while(0)
  966 #   endif
  967 #endif
  968 
  969 
  970 //--------------------------------------------------------------------------------------------------
  971 /**
  972  * This macro does nothing if the condition is false, otherwise it logs the message at EMERGENCY
  973  * level and then kills the calling process.
  974  *
  975  * Accepts printf-style arguments, consisting of a format string followed by zero or more parameters
  976  * to be printed (depending on the contents of the format string).
  977  */
  978 //--------------------------------------------------------------------------------------------------
  979 #define LE_FATAL_IF(condition, formatString, ...)               \
  980 do{                                                             \
  981     if (condition) { LE_FATAL(formatString, ##__VA_ARGS__); }   \
  982 }while(0)
  983 
  984 
  985 //--------------------------------------------------------------------------------------------------
  986 /**
  987  * This macro does nothing if the condition is true, otherwise it logs the condition expression as
  988  * a message at EMERGENCY level and then kills the calling process.
  989  */
  990 //--------------------------------------------------------------------------------------------------
  991 #define LE_ASSERT(condition)                            \
  992     LE_FATAL_IF(!(condition), "Assert Failed: '%s'", #condition)
  993 
  994 
  995 //--------------------------------------------------------------------------------------------------
  996 /**
  997  * This macro does nothing if the condition is LE_OK (0), otherwise it logs that the expression did
  998  * not evaluate to LE_OK (0) in a message at EMERGENCY level and then kills the calling process.
  999  */
 1000 //--------------------------------------------------------------------------------------------------
 1001 #define LE_ASSERT_OK(condition)                                         \
 1002     LE_FATAL_IF((condition) != LE_OK, "Assert Failed: '%s' is not LE_OK (0)", #condition)
 1003 
 1004 
 1005 //--------------------------------------------------------------------------------------------------
 1006 /**
 1007  * Get a null-terminated, printable string representing an le_result_t value.
 1008  *
 1009  * For example, LE_RESULT_TXT(LE_NOT_PERMITTED) would return a pointer to a string containing
 1010  * "LE_NOT_PERMITTED".
 1011  *
 1012  * "(unknown)" will be returned if the value given is out of range.
 1013  *
 1014  * @return Pointer to a string constant.
 1015  */
 1016 //--------------------------------------------------------------------------------------------------
 1017 #define LE_RESULT_TXT(v) _le_log_GetResultCodeString(v)
 1018 
 1019 //--------------------------------------------------------------------------------------------------
 1020 /**
 1021  * Get a null-terminated, printable string representing an errno value.
 1022  *
 1023  * Use this instead of strerror() or strerror_r() since those have
 1024  * incompatible implementations on different platforms.
 1025  *
 1026  * @return Pointer to a string constant.
 1027  */
 1028 //--------------------------------------------------------------------------------------------------
 1029 #ifndef LE_ERRNO_TXT
 1030 #  define LE_ERRNO_TXT(v) _le_log_GetErrnoCodeString(v)
 1031 #  define LE_LOG_NEED_GET_ERRNO_STRING 1
 1032 
 1033 const char *_le_log_GetErrnoCodeString(int error);
 1034 #endif
 1035 
 1036 
 1037 //--------------------------------------------------------------------------------------------------
 1038 /**
 1039  * Connects to the Log Control Daemon.  This must not be done until after the Messaging system
 1040  * is initialized, but must be done before the main thread's Event Loop starts to ensure that
 1041  * all log settings are received from the Log Control Daemon and applied to sessions in the local
 1042  * process before any component initialization functions are run.
 1043  */
 1044 //--------------------------------------------------------------------------------------------------
 1045 LE_FULL_API void le_log_ConnectToControlDaemon
 1046 (
 1047     void
 1048 );
 1049 
 1050 //--------------------------------------------------------------------------------------------------
 1051 /**
 1052  * Registers a named component with the logging system.
 1053  *
 1054  * @return
 1055  *      A log session reference.  This reference must be kept by the component and accessible
 1056  *      through a local macro with the name LE_LOG_SESSION.
 1057  */
 1058 //--------------------------------------------------------------------------------------------------
 1059 LE_FULL_API le_log_SessionRef_t le_log_RegComponent
 1060 (
 1061     const char       *componentNamePtr, ///< [IN] A pointer to the component's name.
 1062     le_log_Level_t  **levelFilterPtrPtr ///< [OUT] Set to point to the component's level filter.
 1063 );
 1064 
 1065 #endif // LEGATO_LOG_INCLUDE_GUARD
le_log_RegComponent
LE_FULL_API le_log_SessionRef_t le_log_RegComponent(const char *componentNamePtr, le_log_Level_t **levelFilterPtrPtr)
LE_SHARED
#define LE_SHARED
Definition: le_basics.h:300
le_result_t
le_result_t
Definition: le_basics.h:46
LE_LOG_WARN
Warning. Possibly indicates a problem. Should be addressed. 
Definition: le_log.h:378
le_log_Level_t
le_log_Level_t
Definition: le_log.h:374
LE_LOG_DEBUG
Debug message. 
Definition: le_log.h:376
LE_LOG_ERR
Definition: le_log.h:379
_le_log_GetErrnoCodeString
const char * _le_log_GetErrnoCodeString(int errnoCode)
Function that does the real work of translating result codes. See LE_RESULT_TXT. 
_le_log_GetResultCodeString
const char * _le_log_GetResultCodeString(le_result_t resultCode)
Function that does the real work of translating result codes. See LE_RESULT_TXT. 
le_log_ConnectToControlDaemon
LE_FULL_API void le_log_ConnectToControlDaemon(void)
LE_LOG_CRIT
Definition: le_log.h:381
LE_FULL_API
#define LE_FULL_API
Definition: le_apiFeatures.h:40
LE_LOG_INFO
Informational message. Normally expected. 
Definition: le_log.h:377
LE_LOG_EMERG
Emergency. A fatal error has occurred. A process is being terminated. 
Definition: le_log.h:383
_le_log_ExitFatal
void _le_log_ExitFatal(void)
Function that exits in a race-free manner -- work around glibc BZ#14333. 
LE_LOG_MAX
One beyond maximum log level. 
Definition: le_log.h:384