include/libwebsockets/lws-logs.h

   1 /*
   2  * libwebsockets - small server side websockets and web server implementation
   3  *
   4  * Copyright (C) 2010-2018 Andy Green <andy@warmcat.com>
   5  *
   6  *  This library is free software; you can redistribute it and/or
   7  *  modify it under the terms of the GNU Lesser General Public
   8  *  License as published by the Free Software Foundation:
   9  *  version 2.1 of the License.
  10  *
  11  *  This library is distributed in the hope that it will be useful,
  12  *  but WITHOUT ANY WARRANTY; without even the implied warranty of
  13  *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  14  *  Lesser General Public License for more details.
  15  *
  16  *  You should have received a copy of the GNU Lesser General Public
  17  *  License along with this library; if not, write to the Free Software
  18  *  Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston,
  19  *  MA  02110-1301  USA
  20  *
  21  * included from libwebsockets.h
  22  */
  23
  24 /** \defgroup log Logging
  25  *
  26  * ##Logging
  27  *
  28  * Lws provides flexible and filterable logging facilities, which can be
  29  * used inside lws and in user code.
  30  *
  31  * Log categories may be individually filtered bitwise, and directed to built-in
  32  * sinks for syslog-compatible logging, or a user-defined function.
  33  */
  34 ///@{
  35
  36 enum lws_log_levels {
  37         LLL_ERR         = 1 << 0,
  38         LLL_WARN        = 1 << 1,
  39         LLL_NOTICE      = 1 << 2,
  40         LLL_INFO        = 1 << 3,
  41         LLL_DEBUG       = 1 << 4,
  42         LLL_PARSER      = 1 << 5,
  43         LLL_HEADER      = 1 << 6,
  44         LLL_EXT         = 1 << 7,
  45         LLL_CLIENT      = 1 << 8,
  46         LLL_LATENCY     = 1 << 9,
  47         LLL_USER        = 1 << 10,
  48         LLL_THREAD      = 1 << 11,
  49
  50         LLL_COUNT       = 12 /* set to count of valid flags */
  51 };
  52
  53 /**
  54  * lwsl_timestamp: generate logging timestamp string
  55  *
  56  * \param level:        logging level
  57  * \param p:            char * buffer to take timestamp
  58  * \param len:  length of p
  59  *
  60  * returns length written in p
  61  */
  62 LWS_VISIBLE LWS_EXTERN int
  63 lwsl_timestamp(int level, char *p, int len);
  64
  65 #if defined(LWS_PLAT_OPTEE) && !defined(LWS_WITH_NETWORK)
  66 #define _lws_log(aaa, ...) SMSG(__VA_ARGS__)
  67 #else
  68 LWS_VISIBLE LWS_EXTERN void _lws_log(int filter, const char *format, ...) LWS_FORMAT(2);
  69 LWS_VISIBLE LWS_EXTERN void _lws_logv(int filter, const char *format, va_list vl);
  70 #endif
  71
  72 /* these guys are unconditionally included */
  73
  74 #define lwsl_err(...) _lws_log(LLL_ERR, __VA_ARGS__)
  75 #define lwsl_user(...) _lws_log(LLL_USER, __VA_ARGS__)
  76
  77 #if !defined(LWS_WITH_NO_LOGS)
  78 /* notice and warn are usually included by being compiled in */
  79 #define lwsl_warn(...) _lws_log(LLL_WARN, __VA_ARGS__)
  80 #define lwsl_notice(...) _lws_log(LLL_NOTICE, __VA_ARGS__)
  81 #endif
  82 /*
  83  *  weaker logging can be deselected by telling CMake to build in RELEASE mode
  84  *  that gets rid of the overhead of checking while keeping _warn and _err
  85  *  active
  86  */
  87
  88 #if defined(_DEBUG)
  89 #if defined(LWS_WITH_NO_LOGS)
  90 /* notice, warn and log are always compiled in */
  91 #define lwsl_warn(...) _lws_log(LLL_WARN, __VA_ARGS__)
  92 #define lwsl_notice(...) _lws_log(LLL_NOTICE, __VA_ARGS__)
  93 #endif
  94 #define lwsl_info(...) _lws_log(LLL_INFO, __VA_ARGS__)
  95 #define lwsl_debug(...) _lws_log(LLL_DEBUG, __VA_ARGS__)
  96 #define lwsl_parser(...) _lws_log(LLL_PARSER, __VA_ARGS__)
  97 #define lwsl_header(...)  _lws_log(LLL_HEADER, __VA_ARGS__)
  98 #define lwsl_ext(...)  _lws_log(LLL_EXT, __VA_ARGS__)
  99 #define lwsl_client(...) _lws_log(LLL_CLIENT, __VA_ARGS__)
 100 #define lwsl_latency(...) _lws_log(LLL_LATENCY, __VA_ARGS__)
 101 #define lwsl_thread(...) _lws_log(LLL_THREAD, __VA_ARGS__)
 102
 103 #else /* no debug */
 104 #if defined(LWS_WITH_NO_LOGS)
 105 #define lwsl_warn(...) do {} while(0)
 106 #define lwsl_notice(...) do {} while(0)
 107 #endif
 108 #define lwsl_info(...) do {} while(0)
 109 #define lwsl_debug(...) do {} while(0)
 110 #define lwsl_parser(...) do {} while(0)
 111 #define lwsl_header(...) do {} while(0)
 112 #define lwsl_ext(...) do {} while(0)
 113 #define lwsl_client(...) do {} while(0)
 114 #define lwsl_latency(...) do {} while(0)
 115 #define lwsl_thread(...) do {} while(0)
 116
 117 #endif
 118
 119
 120 #define lwsl_hexdump_err(...) lwsl_hexdump_level(LLL_ERR, __VA_ARGS__)
 121 #define lwsl_hexdump_warn(...) lwsl_hexdump_level(LLL_WARN, __VA_ARGS__)
 122 #define lwsl_hexdump_notice(...) lwsl_hexdump_level(LLL_NOTICE, __VA_ARGS__)
 123 #define lwsl_hexdump_info(...) lwsl_hexdump_level(LLL_INFO, __VA_ARGS__)
 124 #define lwsl_hexdump_debug(...) lwsl_hexdump_level(LLL_DEBUG, __VA_ARGS__)
 125
 126 /**
 127  * lwsl_hexdump_level() - helper to hexdump a buffer at a selected debug level
 128  *
 129  * \param level: one of LLL_ constants
 130  * \param vbuf: buffer start to dump
 131  * \param len: length of buffer to dump
 132  *
 133  * If \p level is visible, does a nice hexdump -C style dump of \p vbuf for
 134  * \p len bytes.  This can be extremely convenient while debugging.
 135  */
 136 LWS_VISIBLE LWS_EXTERN void
 137 lwsl_hexdump_level(int level, const void *vbuf, size_t len);
 138
 139 /**
 140  * lwsl_hexdump() - helper to hexdump a buffer (DEBUG builds only)
 141  *
 142  * \param buf: buffer start to dump
 143  * \param len: length of buffer to dump
 144  *
 145  * Calls through to lwsl_hexdump_level(LLL_DEBUG, ... for compatability.
 146  * It's better to use lwsl_hexdump_level(level, ... directly so you can control
 147  * the visibility.
 148  */
 149 LWS_VISIBLE LWS_EXTERN void
 150 lwsl_hexdump(const void *buf, size_t len);
 151
 152 /**
 153  * lws_is_be() - returns nonzero if the platform is Big Endian
 154  */
 155 static LWS_INLINE int lws_is_be(void) {
 156         const int probe = ~0xff;
 157
 158         return *(const char *)&probe;
 159 }
 160
 161 /**
 162  * lws_set_log_level() - Set the logging bitfield
 163  * \param level:        OR together the LLL_ debug contexts you want output from
 164  * \param log_emit_function:    NULL to leave it as it is, or a user-supplied
 165  *                      function to perform log string emission instead of
 166  *                      the default stderr one.
 167  *
 168  *      log level defaults to "err", "warn" and "notice" contexts enabled and
 169  *      emission on stderr.  If stderr is a tty (according to isatty()) then
 170  *      the output is coloured according to the log level using ANSI escapes.
 171  */
 172 LWS_VISIBLE LWS_EXTERN void
 173 lws_set_log_level(int level,
 174                   void (*log_emit_function)(int level, const char *line));
 175
 176 /**
 177  * lwsl_emit_syslog() - helper log emit function writes to system log
 178  *
 179  * \param level: one of LLL_ log level indexes
 180  * \param line: log string
 181  *
 182  * You use this by passing the function pointer to lws_set_log_level(), to set
 183  * it as the log emit function, it is not called directly.
 184  */
 185 LWS_VISIBLE LWS_EXTERN void
 186 lwsl_emit_syslog(int level, const char *line);
 187
 188 /**
 189  * lwsl_emit_stderr() - helper log emit function writes to stderr
 190  *
 191  * \param level: one of LLL_ log level indexes
 192  * \param line: log string
 193  *
 194  * You use this by passing the function pointer to lws_set_log_level(), to set
 195  * it as the log emit function, it is not called directly.
 196  *
 197  * It prepends a system timestamp like [2018/11/13 07:41:57:3989]
 198  *
 199  * If stderr is a tty, then ansi colour codes are added.
 200  */
 201 LWS_VISIBLE LWS_EXTERN void
 202 lwsl_emit_stderr(int level, const char *line);
 203
 204 /**
 205  * lwsl_emit_stderr_notimestamp() - helper log emit function writes to stderr
 206  *
 207  * \param level: one of LLL_ log level indexes
 208  * \param line: log string
 209  *
 210  * You use this by passing the function pointer to lws_set_log_level(), to set
 211  * it as the log emit function, it is not called directly.
 212  *
 213  * If stderr is a tty, then ansi colour codes are added.
 214  */
 215 LWS_VISIBLE LWS_EXTERN void
 216 lwsl_emit_stderr_notimestamp(int level, const char *line);
 217
 218 /**
 219  * lwsl_visible() - returns true if the log level should be printed
 220  *
 221  * \param level: one of LLL_ log level indexes
 222  *
 223  * This is useful if you have to do work to generate the log content, you
 224  * can skip the work if the log level used to print it is not actually
 225  * enabled at runtime.
 226  */
 227 LWS_VISIBLE LWS_EXTERN int
 228 lwsl_visible(int level);
 229
 230 ///@}