• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1// -*- mode:doc; -*-
2// vim: set syntax=asciidoc tw=0
3
4coap_logging(3)
5===============
6:doctype: manpage
7:man source:   coap_logging
8:man version:  @PACKAGE_VERSION@
9:man manual:   libcoap Manual
10
11NAME
12----
13coap_logging,
14coap_log,
15coap_log_emerg,
16coap_log_alert,
17coap_log_crit,
18coap_log_err,
19coap_log_warn,
20coap_log_info,
21coap_log_notice,
22coap_log_debug,
23coap_log_oscore,
24coap_get_log_level,
25coap_set_log_level,
26coap_dtls_log,
27coap_dtls_get_log_level,
28coap_dtls_set_log_level,
29coap_set_log_handler,
30coap_package_name,
31coap_package_version,
32coap_package_build,
33coap_set_show_pdu_output,
34coap_show_pdu,
35coap_endpoint_str,
36coap_session_str,
37coap_print_addr,
38coap_print_ip_addr
39- Work with CoAP logging
40
41SYNOPSIS
42--------
43*#include <coap@LIBCOAP_API_VERSION@/coap.h>*
44
45*void coap_log(coap_log_t _level_, const char *_format_, _..._);*
46
47*void coap_log_emerg(const char *_format_, _..._);*
48
49*void coap_log_alert(const char *_format_, _..._);*
50
51*void coap_log_crit(const char *_format_, _..._);*
52
53*void coap_log_err(const char *_format_, _..._);*
54
55*void coap_log_warn(const char *_format_, _..._);*
56
57*void coap_log_info(const char *_format_, _..._);*
58
59*void coap_log_notice(const char *_format_, _..._);*
60
61*void coap_log_debug(const char *_format_, _..._);*
62
63*void coap_log_oscore(const char *_format_, _..._);*
64
65*void coap_set_log_level(coap_log_t _level_);*
66
67*coap_log_t coap_get_log_level(void);*
68
69*void coap_dtls_log(coap_log_t _level_, const char *_format_, _..._);*
70
71*void coap_dtls_set_log_level(coap_log_t _level_);*
72
73*coap_log_t coap_dtls_get_log_level(void);*
74
75*void coap_set_log_handler(coap_log_handler_t _handler_);*
76
77*const char *coap_package_name(void);*
78
79*const char *coap_package_version(void);*
80
81*const char *coap_package_build(void);*
82
83*void coap_set_show_pdu_output(int _use_fprintf_);*
84
85*void coap_show_pdu(coap_log_t _level_, const coap_pdu_t *_pdu_);*
86
87*const char *coap_endpoint_str(const coap_endpoint_t *_endpoint_);*
88
89*const char *coap_session_str(const coap_session_t *_session_);*
90
91*size_t coap_print_addr(const coap_address_t *_address_,
92unsigned char *_buffer_, size_t _length_);*
93
94*const char *coap_print_ip_addr(const coap_address_t *_address_,
95char *_buffer_, size_t _length_);*
96
97For specific (D)TLS library support, link with
98*-lcoap-@LIBCOAP_API_VERSION@-notls*, *-lcoap-@LIBCOAP_API_VERSION@-gnutls*,
99*-lcoap-@LIBCOAP_API_VERSION@-openssl*, *-lcoap-@LIBCOAP_API_VERSION@-mbedtls*
100or *-lcoap-@LIBCOAP_API_VERSION@-tinydtls*.   Otherwise, link with
101*-lcoap-@LIBCOAP_API_VERSION@* to get the default (D)TLS library support.
102
103DESCRIPTION
104-----------
105The logging sub-system supports logging at different levels, and depending on
106the selected logging level, outputs the appropriate information.
107
108Logging by default is to stderr or stdout depending on the logging level of
109the log entry.  It ia possible to send the logging information to an
110application logging callback handler for processing by the application.
111
112Logging levels (*coap_log_t*) are defined as follows (based on the *syslog*()
113names and values):
114
115*COAP_LOG_EMERG*::
116Emergency level (0).
117
118*COAP_LOG_ALERT*::
119Alert level (1).
120
121*COAP_LOG_CRIT*::
122Critical level (2).
123
124*COAP_LOG_ERR*::
125Error level (3).
126
127*COAP_LOG_WARN*::
128Warning level (the default) (4).
129
130*COAP_LOG_NOTICE*::
131Notice level (5).
132
133*COAP_LOG_INFO*::
134Information level (6).
135
136*COAP_LOG_DEBUG*::
137Debug level (7).
138
139With additional level:
140
141*COAP_LOG_OSCORE*::
142Debug OSCORE information (8).
143
144*NOTE:* The maximum logging level in the libcoap library may have been updated
145by the use of './configure --enable-max-logging-level=X' (where X is 0 to 8 inclusive)
146which may disable some of the higher logging levels to save code space.
147
148FUNCTIONS
149---------
150
151*Function: coap_log()*
152
153The *coap_log*() function is used to log information at the appropriate _level_.
154The rest of the parameters follow the standard *printf*() function format.
155Where possible, the coap_log_*() functions should be used instead.
156
157*Function: coap_log_emerg()*
158
159The *coap_log_emerg*() function provides a wrapper to the *coap_log*() function
160with _level_ set to COAP_LOG_EMERG.
161The parameters follow the standard *printf*() function format.
162
163*Function: coap_log_alert()*
164
165The *coap_log_alert*() function provides a wrapper to the *coap_log*() function
166with _level_ set to COAP_LOG_ALERT.
167The parameters follow the standard *printf*() function format.
168
169*Function: coap_log_crit()*
170
171The *coap_log_crit*() function provides a wrapper to the *coap_log*() function
172with _level_ set to COAP_LOG_CRIT.
173The parameters follow the standard *printf*() function format.
174
175*Function: coap_log_err()*
176
177The *coap_log_err*() function provides a wrapper to the *coap_log*() function
178with _level_ set to COAP_LOG_ERR.
179The parameters follow the standard *printf*() function format.
180
181*Function: coap_log_warn()*
182
183The *coap_log_warn*() function provides a wrapper to the *coap_log*() function
184with _level_ set to COAP_LOG_WARN.
185The parameters follow the standard *printf*() function format.
186
187*Function: coap_log_notice()*
188
189The *coap_log_notice*() function provides a wrapper to the *coap_log*() function
190with _level_ set to COAP_LOG_NOTICE.
191The parameters follow the standard *printf*() function format.
192
193*Function: coap_log_info()*
194
195The *coap_log_info*() function provides a wrapper to the *coap_log*() function
196with _level_ set to COAP_LOG_INFO.
197The parameters follow the standard *printf*() function format.
198
199*Function: coap_log_debug()*
200
201The *coap_log_debug*() function provides a wrapper to the *coap_log*() function
202with _level_ set to COAP_LOG_DEBUG.
203The parameters follow the standard *printf*() function format.
204
205*Function: coap_log_oscore()*
206
207The *coap_log_oscore*() function provides a wrapper to the *coap_log*() function
208with _level_ set to COAP_LOG_OSCORE.
209The parameters follow the standard *printf*() function format.
210
211*Function: coap_set_log_level()*
212
213The *coap_set_log_level*() function is used to set the current logging _level_
214for output by any subsequent *coap_log*() calls.  Output is only logged if the
215*coap_log*() _level_ definition is smaller than or equal to the current logging
216_level_.
217
218*Function: coap_get_log_level()*
219
220The *coap_get_log_level*() function is used to get the current logging level.
221
222*Function: coap_dtls_log()*
223
224The *coap_dtls_log*() function is used to log (D)TLS library information at the
225appropriate _level_.  The rest of the parameters follow the standard *printf*()
226function format.
227
228*Function: coap_dtls_set_log_level()*
229
230The *coap_dtls_set_log_level*() function is used to set the current logging
231_level_ for output by any subsequent *coap_dtls_log*() calls.  Output is only
232logged if the *coap_dtls_log*() _level_ definition is smaller than or equal to
233the current DTLS logging _level_.
234
235*Function: coap_dtls_get_log_level()*
236
237The *coap_dtls_get_log_level*() function is used to get the current logging
238level for the DTLS library.
239
240*Function: coap_set_log_handler()*
241
242The *coap_set_log_handler*()* function can be used to define an alternative
243logging handler for processing any logging messages.  The logging handler
244prototype is defined as:
245
246[source, c]
247----
248typedef void (*coap_log_handler_t) (coap_log_t level, const char *message);
249----
250
251*Function: coap_package_name()*
252
253The *coap_package_name*() function returns the name of this library.
254
255*Function: coap_package_version()*
256
257The *coap_package_version*() function returns the version of this library.
258
259*Function: coap_package_build()*
260
261The *coap_package_build*() function returns the git information (as in
262"git describe --tags") for the build of this library or version of this
263library if git is not used.
264
265*Function: coap_set_show_pdu_output()*
266
267The *coap_set_show_pdu_output*() function defines whether the output from
268*coap_show_pdu*() is to be either sent to stdout/stderr, or output using
269*coap_log*().  _use_fprintf_ is set to 1 for stdout/stderr (the default), and
270_use_fprintf_ is set to 0 for *coap_log*().
271
272*Function: coap_show_pdu()*
273
274The *coap_show_pdu*() function is used to decode the _pdu_, outputting as
275appropriate for logging _level_.  Where the output goes is dependent on
276*coap_set_show_pdu_output*().
277
278*NOTE:* If _pdu_ has not been associated with a CoAP session (i.e. not a
279received PDU or coap_send() not yet called), then the output assumes that
280this _pdu_ is of type unreliable.
281
282*Function: coap_endpoint_str()*
283
284The *coap_endpoint_str*() function returns a description string of the
285_endpoint_.
286
287*Function: coap_session_str()*
288
289The *coap_session_str*() function is used to get a string containing the
290information about the _session_.
291
292*Function: coap_print_addr()*
293
294The *coap_print_addr*() function returns the length of the  description string
295containing the IP address and port from _address_, updating _buffer_ which has a
296maximum length _length_.
297
298*Function: coap_print_ip_addr()*
299
300The *coap_print_ip_addr*() function returns a description string of the
301IP address only for _address_. _buffer_ is updated, which has a maximum length of
302_length_.
303
304RETURN VALUES
305-------------
306
307*coap_package_name*(), *coap_package_version*() and
308*coap_package_build*() return the appropriate zero-terminated character
309string.
310
311*coap_get_log_level*() returns the current logging level.
312
313*coap_dtls_get_log_level*() returns the current logging level
314for the DTLS library specifics.
315
316*coap_endpoint_str*() returns a description string of the
317_endpoint_.
318
319*coap_session_str*() returns a description string of the
320_session_.
321
322*coap_print_addr*() returns the length of _buffer_ that has been
323updated with an ascii readable IP address and port for _address_.
324
325*coap_print_ip_addr*() returns a pointer to the ascii readable
326IP address only for _address_.
327
328SEE ALSO
329--------
330*coap_context*(3) and *coap_session*(3)
331
332FURTHER INFORMATION
333-------------------
334See
335
336"https://rfc-editor.org/rfc/rfc7252[RFC7252: The Constrained Application Protocol (CoAP)]"
337
338for further information.
339
340BUGS
341----
342Please report bugs on the mailing list for libcoap:
343libcoap-developers@lists.sourceforge.net or raise an issue on GitHub at
344https://github.com/obgm/libcoap/issues
345
346AUTHORS
347-------
348The libcoap project <libcoap-developers@lists.sourceforge.net>
349