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