Macros
#define	lwsl_err(...) _lws_log(LLL_ERR, __VA_ARGS__)

#define	lwsl_user(...) _lws_log(LLL_USER, __VA_ARGS__)

#define	lwsl_warn(...) _lws_log(LLL_WARN, __VA_ARGS__)

#define	lwsl_notice(...) _lws_log(LLL_NOTICE, __VA_ARGS__)

#define	lwsl_info(...) do {} while(0)

#define	lwsl_debug(...) do {} while(0)

#define	lwsl_parser(...) do {} while(0)

#define	lwsl_header(...) do {} while(0)

#define	lwsl_ext(...) do {} while(0)

#define	lwsl_client(...) do {} while(0)

#define	lwsl_latency(...) do {} while(0)

#define	lwsl_thread(...) do {} while(0)

#define	lwsl_hexdump_err(...) lwsl_hexdump_level(LLL_ERR, __VA_ARGS__)

#define	lwsl_hexdump_warn(...) lwsl_hexdump_level(LLL_WARN, __VA_ARGS__)

#define	lwsl_hexdump_notice(...) lwsl_hexdump_level(LLL_NOTICE, __VA_ARGS__)

#define	lwsl_hexdump_info(...) lwsl_hexdump_level(LLL_INFO, __VA_ARGS__)

#define	lwsl_hexdump_debug(...) lwsl_hexdump_level(LLL_DEBUG, __VA_ARGS__)

#define	lws_list_ptr_container(P, T, M) ((T )((char )(P) - offsetof(T, M)))

#define	lws_list_ptr_advance(_lp) _lp = ((void *)_lp)

Typedefs
typedef unsigned char *	lwsac_cached_file_t

typedef void *	lws_list_ptr

typedef int(*	lws_list_ptr_sort_func_t) (lws_list_ptr a, lws_list_ptr b)

Enumerations
enum	lws_log_levels { LLL_ERR = 1 << 0, LLL_WARN = 1 << 1, LLL_NOTICE = 1 << 2, LLL_INFO = 1 << 3, LLL_DEBUG = 1 << 4, LLL_PARSER = 1 << 5, LLL_HEADER = 1 << 6, LLL_EXT = 1 << 7, LLL_CLIENT = 1 << 8, LLL_LATENCY = 1 << 9, LLL_USER = 1 << 10, LLL_THREAD = 1 << 11, LLL_COUNT = 12 }

Functions
LWS_VISIBLE LWS_EXTERN void	_lws_log (int filter, const char *format,...) LWS_FORMAT(2)

LWS_VISIBLE LWS_EXTERN void	_lws_logv (int filter, const char *format, va_list vl)

LWS_VISIBLE LWS_EXTERN int	lwsl_timestamp (int level, char *p, int len)

LWS_VISIBLE LWS_EXTERN void	lwsl_hexdump_level (int level, const void *vbuf, size_t len)

LWS_VISIBLE LWS_EXTERN void	lwsl_hexdump (const void *buf, size_t len)

LWS_VISIBLE LWS_EXTERN void	lws_set_log_level (int level, void(log_emit_function)(int level, const char line))

LWS_VISIBLE LWS_EXTERN void	lwsl_emit_syslog (int level, const char *line)

LWS_VISIBLE LWS_EXTERN void	lwsl_emit_stderr (int level, const char *line)

LWS_VISIBLE LWS_EXTERN void	lwsl_emit_stderr_notimestamp (int level, const char *line)

LWS_VISIBLE LWS_EXTERN int	lwsl_visible (int level)

LWS_VISIBLE LWS_EXTERN void	lws_list_ptr_insert (lws_list_ptr phead, lws_list_ptr add, lws_list_ptr_sort_func_t sort)

LWS_VISIBLE LWS_EXTERN void *	lwsac_use (struct lwsac **head, size_t ensure, size_t chunk_size)

LWS_VISIBLE LWS_EXTERN void	lwsac_free (struct lwsac **head)

LWS_VISIBLE LWS_EXTERN void	lwsac_detach (struct lwsac **head)

LWS_VISIBLE LWS_EXTERN void	lwsac_reference (struct lwsac *head)

LWS_VISIBLE LWS_EXTERN void	lwsac_unreference (struct lwsac **head)

LWS_VISIBLE LWS_EXTERN void	lwsac_use_cached_file_start (lwsac_cached_file_t cache)

LWS_VISIBLE LWS_EXTERN void	lwsac_use_cached_file_end (lwsac_cached_file_t *cache)

LWS_VISIBLE LWS_EXTERN void	lwsac_use_cached_file_detach (lwsac_cached_file_t *cache)

LWS_VISIBLE LWS_EXTERN int	lwsac_cached_file (const char filepath, lwsac_cached_file_t cache, size_t *len)

LWS_VISIBLE LWS_EXTERN size_t	lwsac_sizeof (void)

LWS_VISIBLE LWS_EXTERN size_t	lwsac_get_tail_pos (struct lwsac *lac)

LWS_VISIBLE LWS_EXTERN struct lwsac *	lwsac_get_next (struct lwsac *lac)

LWS_VISIBLE LWS_EXTERN size_t	lwsac_align (size_t length)

LWS_VISIBLE LWS_EXTERN void	lwsac_info (struct lwsac *head)

LWS_VISIBLE LWS_EXTERN uint64_t	lwsac_total_alloc (struct lwsac *head)

Detailed Description

Logging

Lws provides flexible and filterable logging facilities, which can be used inside lws and in user code.

Log categories may be individually filtered bitwise, and directed to built-in sinks for syslog-compatible logging, or a user-defined function.

Allocated Chunks

If you know you will be allocating a large, unknown number of same or differently sized objects, it's certainly possible to do it with libc malloc. However the allocation cost in time and memory overhead can add up, and deallocation means walking the structure of every object and freeing them in turn.

lwsac (LWS Allocated Chunks) allocates chunks intended to be larger than your objects (4000 bytes by default) which you linearly allocate from using lwsac_use().

If your next request won't fit in the current chunk, a new chunk is added to the chain of chunks and the allocaton done from there. If the request is larger than the chunk size, an oversize chunk is created to satisfy it.

When you are finished with the allocations, you call lwsac_free() and free all the chunks. So you may have thousands of objects in the chunks, but they are all destroyed with the chunks without having to deallocate them one by one pointlessly.

Function Documentation

◆ lws_set_log_level()

LWS_VISIBLE LWS_EXTERN void lws_set_log_level	(	int	level,
		void()(int level, const char line)	log_emit_function
	)

#include <include/libwebsockets/lws-logs.h>

lws_set_log_level() - Set the logging bitfield

Parameters

level	OR together the LLL_ debug contexts you want output from
log_emit_function	NULL to leave it as it is, or a user-supplied function to perform log string emission instead of the default stderr one.

log level defaults to "err", "warn" and "notice" contexts enabled and emission on stderr. If stderr is a tty (according to isatty()) then the output is coloured according to the log level using ANSI escapes.

◆ lwsac_detach()

LWS_VISIBLE LWS_EXTERN void lwsac_detach ( struct lwsac ** head )

#include <include/libwebsockets/lws-lwsac.h>

lwsac_detach() - destroy an lwsac unless somebody else is referencing it

Parameters

head	pointer to the lwsac list object

The creator of the lwsac can all this instead of lwsac_free() when it itself has finished with the lwsac, but other code may be consuming it.

If there are no other references, the lwsac is destroyed, *head is set to NULL and that's the end; however if something else has called lwsac_reference() on the lwsac, it simply returns. When lws_unreference() is called and no references are left, it will be destroyed then.

◆ lwsac_free()

LWS_VISIBLE LWS_EXTERN void lwsac_free ( struct lwsac ** head )

#include <include/libwebsockets/lws-lwsac.h>

lwsac_free - deallocate all chunks in the lwsac and set head NULL

Parameters

head	pointer to the lwsac list object

This deallocates all chunks in the lwsac, then sets *head to NULL. All lwsac_use() pointers are invalidated in one hit without individual frees.

◆ lwsac_reference()

LWS_VISIBLE LWS_EXTERN void lwsac_reference ( struct lwsac * head )

#include <include/libwebsockets/lws-lwsac.h>

lwsac_reference() - increase the lwsac reference count

Parameters

head	pointer to the lwsac list object

Increment the reference count on the lwsac to defer destruction.

◆ lwsac_unreference()

LWS_VISIBLE LWS_EXTERN void lwsac_unreference ( struct lwsac ** head )

#include <include/libwebsockets/lws-lwsac.h>

lwsac_reference() - increase the lwsac reference count

Parameters

head	pointer to the lwsac list object

Decrement the reference count on the lwsac... if it reached 0 on a detached lwsac then the lwsac is immediately destroyed and *head set to NULL.

◆ lwsac_use()

LWS_VISIBLE LWS_EXTERN void* lwsac_use	(	struct lwsac **	head,
		size_t	ensure,
		size_t	chunk_size
	)

#include <include/libwebsockets/lws-lwsac.h>

lwsac_use - allocate / use some memory from a lwsac

Parameters

head	pointer to the lwsac list object
ensure	the number of bytes we want to use
chunk_size	0, or the size of the chunk to (over)allocate if what we want won't fit in the current tail chunk. If 0, the default value of 4000 is used. If ensure is larger, it is used instead.

This also serves to init the lwsac if *head is NULL. Basically it does whatever is necessary to return you a pointer to ensure bytes of memory reserved for the caller.

Returns NULL if OOM.

◆ lwsl_emit_stderr()

LWS_VISIBLE LWS_EXTERN void lwsl_emit_stderr	(	int	level,
		const char *	line
	)

#include <include/libwebsockets/lws-logs.h>

lwsl_emit_stderr() - helper log emit function writes to stderr

Parameters

level	one of LLL_ log level indexes
line	log string

You use this by passing the function pointer to lws_set_log_level(), to set it as the log emit function, it is not called directly.

It prepends a system timestamp like [2018/11/13 07:41:57:3989]

If stderr is a tty, then ansi colour codes are added.

◆ lwsl_emit_stderr_notimestamp()

LWS_VISIBLE LWS_EXTERN void lwsl_emit_stderr_notimestamp	(	int	level,
		const char *	line
	)

#include <include/libwebsockets/lws-logs.h>

lwsl_emit_stderr_notimestamp() - helper log emit function writes to stderr

Parameters

level	one of LLL_ log level indexes
line	log string

You use this by passing the function pointer to lws_set_log_level(), to set it as the log emit function, it is not called directly.

If stderr is a tty, then ansi colour codes are added.

◆ lwsl_emit_syslog()

LWS_VISIBLE LWS_EXTERN void lwsl_emit_syslog	(	int	level,
		const char *	line
	)

#include <include/libwebsockets/lws-logs.h>

lwsl_emit_syslog() - helper log emit function writes to system log

Parameters

level	one of LLL_ log level indexes
line	log string

You use this by passing the function pointer to lws_set_log_level(), to set it as the log emit function, it is not called directly.

◆ lwsl_hexdump()

LWS_VISIBLE LWS_EXTERN void lwsl_hexdump	(	const void *	buf,
		size_t	len
	)

#include <include/libwebsockets/lws-logs.h>

lwsl_hexdump() - helper to hexdump a buffer (DEBUG builds only)

Parameters

buf	buffer start to dump
len	length of buffer to dump

Calls through to lwsl_hexdump_level(LLL_DEBUG, ... for compatability. It's better to use lwsl_hexdump_level(level, ... directly so you can control the visibility.

◆ lwsl_hexdump_level()

LWS_VISIBLE LWS_EXTERN void lwsl_hexdump_level	(	int	level,
		const void *	vbuf,
		size_t	len
	)

#include <include/libwebsockets/lws-logs.h>

lwsl_hexdump_level() - helper to hexdump a buffer at a selected debug level

Parameters

level	one of LLL_ constants
vbuf	buffer start to dump
len	length of buffer to dump

If level is visible, does a nice hexdump -C style dump of vbuf for len bytes. This can be extremely convenient while debugging.

◆ lwsl_timestamp()

LWS_VISIBLE LWS_EXTERN int lwsl_timestamp	(	int	level,
		char *	p,
		int	len
	)

#include <include/libwebsockets/lws-logs.h>

lwsl_timestamp: generate logging timestamp string

Parameters

level	logging level
p	char * buffer to take timestamp
len	length of p

returns length written in p

◆ lwsl_visible()

LWS_VISIBLE LWS_EXTERN int lwsl_visible ( int level )

#include <include/libwebsockets/lws-logs.h>

lwsl_visible() - returns true if the log level should be printed

Parameters

level one of LLL_ log level indexes

This is useful if you have to do work to generate the log content, you can skip the work if the log level used to print it is not actually enabled at runtime.

Macros

Typedefs

Enumerations

Functions

Detailed Description

Logging

Allocated Chunks

Function Documentation

◆ lws_set_log_level()

◆ lwsac_detach()

◆ lwsac_free()

◆ lwsac_reference()

◆ lwsac_unreference()

◆ lwsac_use()

◆ lwsl_emit_stderr()

◆ lwsl_emit_stderr_notimestamp()

◆ lwsl_emit_syslog()

◆ lwsl_hexdump()

◆ lwsl_hexdump_level()

◆ lwsl_timestamp()

◆ lwsl_visible()