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