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_get_log_level, 16coap_set_log_level, 17coap_set_log_handler, 18coap_package_name, 19coap_package_version, 20coap_set_show_pdu_output, 21coap_show_pdu, 22coap_endpoint_str, 23coap_session_str 24- Work with CoAP logging 25 26SYNOPSIS 27-------- 28*#include <coap@LIBCOAP_API_VERSION@/coap.h>* 29 30*void coap_log(coap_log_t _level_, const char *_format_, ...);* 31 32*void coap_set_log_level(coap_log_t _level_);* 33 34*coap_log_t coap_get_log_level(void);* 35 36*void coap_dtls_set_log_level(int _level_);* 37 38*int coap_dtls_get_log_level(void);* 39 40*void coap_set_log_handler(coap_log_handler_t _handler_);* 41 42*const char *coap_package_name(void);* 43 44*const char *coap_package_version(void);* 45 46*void coap_set_show_pdu_output(int _use_fprintf_);* 47 48*void coap_show_pdu(coap_log_t _level_, const coap_pdu_t *_pdu_);* 49 50*const char *coap_endpoint_str(const coap_endpoint_t *_endpoint_);* 51 52*const char *coap_session_str(const coap_session_t *_session_);* 53 54For specific (D)TLS library support, link with 55*-lcoap-@LIBCOAP_API_VERSION@-notls*, *-lcoap-@LIBCOAP_API_VERSION@-gnutls*, 56*-lcoap-@LIBCOAP_API_VERSION@-openssl*, *-lcoap-@LIBCOAP_API_VERSION@-mbedtls* 57or *-lcoap-@LIBCOAP_API_VERSION@-tinydtls*. Otherwise, link with 58*-lcoap-@LIBCOAP_API_VERSION@* to get the default (D)TLS library support. 59 60DESCRIPTION 61----------- 62The logging sub-system supports logging at different levels, and depending on 63the selected logging level, outputs the appropriate information. 64 65Logging by default is to stderr or stdout depending on the logging level of 66the log entry. It ia possible to send the logging information to an 67application logging callback handler for processing by the application. 68 69The *coap_log*() function is used to log information at the appropriate _level_. 70The rest of the parameters follow the standard *printf*() function format. 71 72Logging levels (*coap_log_t*) are defined by (the same as for *syslog*()), which 73are numerically incrementing in value: 74 75*LOG_EMERG*:: 76Emergency level (0). 77 78*LOG_ALERT*:: 79Alert level (1). 80 81*LOG_CRIT*:: 82Critical level (2). 83 84*LOG_ERR*:: 85Error level (3). 86 87*LOG_WARNING*:: 88Warning level (the default) (4). 89 90*LOG_NOTICE*:: 91Notice level (5). 92 93*LOG_INFO*:: 94Information level (6). 95 96*LOG_DEBUG*:: 97Debug level (7). 98 99The *coap_set_log_level*() function is used to set the current logging _level_ 100for output by any subsequent *coap_log*() calls. Output is only logged if the 101*coap_log*() _level_ definition is smaller than or equal to the current logging 102_level_. 103 104The *coap_get_log_level*() function is used to get the current logging level. 105 106The *coap_dtls_set_log_level*() function is used to set the logging _level_ 107for output by the DTLS library for specific DTLS information. Usually, both 108*coap_set_log_level*() and *coap_dtls_set_log_level*() would be set to the 109same _level_ value. If the logging level is set to greater than LOG_DEBUG, 110the underlying TLS library may get more verbose in its output. 111 112The *coap_dtls_get_log_level*() function is used to get the current logging 113level for the DTLS library. 114 115The *coap_set_log_handler*()* function can be used to define an alternative 116logging handler for processing the logging messages. The logging handler 117prototype is defined as: 118 119[source, c] 120---- 121typedef void (*coap_log_handler_t) (coap_log_t level, const char *message); 122---- 123 124The *coap_package_name*() function returns the name of this library. 125 126The *coap_package_version*() function returns the version of this library. 127 128The *coap_set_show_pdu_output*() function defines whether the output from 129*coap_show_pdu*() is to be either sent to stdout/stderr, or output using 130*coap_log*(). _use_fprintf_ is set to 1 for stdout/stderr (the default), and 131_use_fprintf_ is set to 0 for *coap_log*(). 132 133The *coap_show_pdu*() function is used to decode the _pdu_, outputting as 134appropriate for logging _level_. Where the output goes is dependent on 135*coap_set_show_pdu_output*(). 136 137The *coap_endpoint_str*() function returns a description string of the 138_endpoint_. 139 140The *coap_session_str*() function is used to get a string containing the 141information about the _session_. 142 143RETURN VALUES 144------------- 145 146The *coap_package_name*() and *coap_package_version*() return the appropriate 147zero-terminated character string. 148 149The *coap_get_log_level*() function returns the current logging level. 150 151The *coap_dtls_get_log_level*() function returns the current logging level 152for the DTLS library specifics. 153 154The *coap_endpoint_str*() function returns a description string of the 155_endpoint_. 156 157The *coap_session_str*() function returns a description string of the 158_session_. 159 160SEE ALSO 161-------- 162*coap_context*(3) and *coap_session*(3) 163 164FURTHER INFORMATION 165------------------- 166See "RFC7252: The Constrained Application Protocol (CoAP)" for further 167information. 168 169BUGS 170---- 171Please report bugs on the mailing list for libcoap: 172libcoap-developers@lists.sourceforge.net or raise an issue on GitHub at 173https://github.com/obgm/libcoap/issues 174 175AUTHORS 176------- 177The libcoap project <libcoap-developers@lists.sourceforge.net> 178