'\" t
.\"     Title: coap_logging
.\"    Author: [see the "AUTHORS" section]
.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
.\"      Date: 10/28/2023
.\"    Manual: libcoap Manual
.\"    Source: coap_logging 4.3.4
.\"  Language: English
.\"
.TH "COAP_LOGGING" "3" "10/28/2023" "coap_logging 4\&.3\&.4" "libcoap Manual"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
coap_logging, coap_log, coap_log_emerg, coap_log_alert, coap_log_crit, coap_log_err, coap_log_warn, coap_log_info, coap_log_notice, coap_log_debug, coap_log_oscore, coap_get_log_level, coap_set_log_level, coap_dtls_log, coap_dtls_get_log_level, coap_dtls_set_log_level, coap_set_log_handler, coap_package_name, coap_package_version, coap_package_build, coap_set_show_pdu_output, coap_show_pdu, coap_endpoint_str, coap_session_str, coap_print_addr, coap_print_ip_addr \- Work with CoAP logging 
.SH "SYNOPSIS"
.sp
\fB#include <coap3/coap\&.h>\fR
.sp
\fBvoid coap_log(coap_log_t \fR\fB\fIlevel\fR\fR\fB, const char *\fR\fB\fIformat\fR\fR\fB, \fR\fB\fI\&...\fR\fR\fB);\fR
.sp
\fBvoid coap_log_emerg(const char *\fR\fB\fIformat\fR\fR\fB, \fR\fB\fI\&...\fR\fR\fB);\fR
.sp
\fBvoid coap_log_alert(const char *\fR\fB\fIformat\fR\fR\fB, \fR\fB\fI\&...\fR\fR\fB);\fR
.sp
\fBvoid coap_log_crit(const char *\fR\fB\fIformat\fR\fR\fB, \fR\fB\fI\&...\fR\fR\fB);\fR
.sp
\fBvoid coap_log_err(const char *\fR\fB\fIformat\fR\fR\fB, \fR\fB\fI\&...\fR\fR\fB);\fR
.sp
\fBvoid coap_log_warn(const char *\fR\fB\fIformat\fR\fR\fB, \fR\fB\fI\&...\fR\fR\fB);\fR
.sp
\fBvoid coap_log_info(const char *\fR\fB\fIformat\fR\fR\fB, \fR\fB\fI\&...\fR\fR\fB);\fR
.sp
\fBvoid coap_log_notice(const char *\fR\fB\fIformat\fR\fR\fB, \fR\fB\fI\&...\fR\fR\fB);\fR
.sp
\fBvoid coap_log_debug(const char *\fR\fB\fIformat\fR\fR\fB, \fR\fB\fI\&...\fR\fR\fB);\fR
.sp
\fBvoid coap_log_oscore(const char *\fR\fB\fIformat\fR\fR\fB, \fR\fB\fI\&...\fR\fR\fB);\fR
.sp
\fBvoid coap_set_log_level(coap_log_t \fR\fB\fIlevel\fR\fR\fB);\fR
.sp
\fBcoap_log_t coap_get_log_level(void);\fR
.sp
\fBvoid coap_dtls_log(coap_log_t \fR\fB\fIlevel\fR\fR\fB, const char *\fR\fB\fIformat\fR\fR\fB, \fR\fB\fI\&...\fR\fR\fB);\fR
.sp
\fBvoid coap_dtls_set_log_level(coap_log_t \fR\fB\fIlevel\fR\fR\fB);\fR
.sp
\fBcoap_log_t coap_dtls_get_log_level(void);\fR
.sp
\fBvoid coap_set_log_handler(coap_log_handler_t \fR\fB\fIhandler\fR\fR\fB);\fR
.sp
\fBconst char *coap_package_name(void);\fR
.sp
\fBconst char *coap_package_version(void);\fR
.sp
\fBconst char *coap_package_build(void);\fR
.sp
\fBvoid coap_set_show_pdu_output(int \fR\fB\fIuse_fprintf\fR\fR\fB);\fR
.sp
\fBvoid coap_show_pdu(coap_log_t \fR\fB\fIlevel\fR\fR\fB, const coap_pdu_t *\fR\fB\fIpdu\fR\fR\fB);\fR
.sp
\fBconst char *coap_endpoint_str(const coap_endpoint_t *\fR\fB\fIendpoint\fR\fR\fB);\fR
.sp
\fBconst char *coap_session_str(const coap_session_t *\fR\fB\fIsession\fR\fR\fB);\fR
.sp
\fBsize_t coap_print_addr(const coap_address_t *\fR\fB\fIaddress\fR\fR\fB, unsigned char *\fR\fB\fIbuffer\fR\fR\fB, size_t \fR\fB\fIlength\fR\fR\fB);\fR
.sp
\fBconst char *coap_print_ip_addr(const coap_address_t *\fR\fB\fIaddress\fR\fR\fB, char *\fR\fB\fIbuffer\fR\fR\fB, size_t \fR\fB\fIlength\fR\fR\fB);\fR
.sp
For specific (D)TLS library support, link with \fB\-lcoap\-3\-notls\fR, \fB\-lcoap\-3\-gnutls\fR, \fB\-lcoap\-3\-openssl\fR, \fB\-lcoap\-3\-mbedtls\fR or \fB\-lcoap\-3\-tinydtls\fR\&. Otherwise, link with \fB\-lcoap\-3\fR to get the default (D)TLS library support\&.
.SH "DESCRIPTION"
.sp
The logging sub\-system supports logging at different levels, and depending on the selected logging level, outputs the appropriate information\&.
.sp
Logging by default is to stderr or stdout depending on the logging level of the log entry\&. It ia possible to send the logging information to an application logging callback handler for processing by the application\&.
.sp
Logging levels (\fBcoap_log_t\fR) are defined as follows (based on the \fBsyslog\fR() names and values):
.PP
\fBCOAP_LOG_EMERG\fR
.RS 4
Emergency level (0)\&.
.RE
.PP
\fBCOAP_LOG_ALERT\fR
.RS 4
Alert level (1)\&.
.RE
.PP
\fBCOAP_LOG_CRIT\fR
.RS 4
Critical level (2)\&.
.RE
.PP
\fBCOAP_LOG_ERR\fR
.RS 4
Error level (3)\&.
.RE
.PP
\fBCOAP_LOG_WARN\fR
.RS 4
Warning level (the default) (4)\&.
.RE
.PP
\fBCOAP_LOG_NOTICE\fR
.RS 4
Notice level (5)\&.
.RE
.PP
\fBCOAP_LOG_INFO\fR
.RS 4
Information level (6)\&.
.RE
.PP
\fBCOAP_LOG_DEBUG\fR
.RS 4
Debug level (7)\&.
.RE
.sp
With additional level:
.PP
\fBCOAP_LOG_OSCORE\fR
.RS 4
Debug OSCORE information (8)\&.
.RE
.sp
\fBNOTE:\fR The maximum logging level in the libcoap library may have been updated by the use of \fI\&./configure \-\-enable\-max\-logging\-level=X\fR (where X is 0 to 8 inclusive) which may disable some of the higher logging levels to save code space\&.
.SH "FUNCTIONS"
.sp
\fBFunction: coap_log()\fR
.sp
The \fBcoap_log\fR() function is used to log information at the appropriate \fIlevel\fR\&. The rest of the parameters follow the standard \fBprintf\fR() function format\&. Where possible, the coap_log_*() functions should be used instead\&.
.sp
\fBFunction: coap_log_emerg()\fR
.sp
The \fBcoap_log_emerg\fR() function provides a wrapper to the \fBcoap_log\fR() function with \fIlevel\fR set to COAP_LOG_EMERG\&. The parameters follow the standard \fBprintf\fR() function format\&.
.sp
\fBFunction: coap_log_alert()\fR
.sp
The \fBcoap_log_alert\fR() function provides a wrapper to the \fBcoap_log\fR() function with \fIlevel\fR set to COAP_LOG_ALERT\&. The parameters follow the standard \fBprintf\fR() function format\&.
.sp
\fBFunction: coap_log_crit()\fR
.sp
The \fBcoap_log_crit\fR() function provides a wrapper to the \fBcoap_log\fR() function with \fIlevel\fR set to COAP_LOG_CRIT\&. The parameters follow the standard \fBprintf\fR() function format\&.
.sp
\fBFunction: coap_log_err()\fR
.sp
The \fBcoap_log_err\fR() function provides a wrapper to the \fBcoap_log\fR() function with \fIlevel\fR set to COAP_LOG_ERR\&. The parameters follow the standard \fBprintf\fR() function format\&.
.sp
\fBFunction: coap_log_warn()\fR
.sp
The \fBcoap_log_warn\fR() function provides a wrapper to the \fBcoap_log\fR() function with \fIlevel\fR set to COAP_LOG_WARN\&. The parameters follow the standard \fBprintf\fR() function format\&.
.sp
\fBFunction: coap_log_notice()\fR
.sp
The \fBcoap_log_notice\fR() function provides a wrapper to the \fBcoap_log\fR() function with \fIlevel\fR set to COAP_LOG_NOTICE\&. The parameters follow the standard \fBprintf\fR() function format\&.
.sp
\fBFunction: coap_log_info()\fR
.sp
The \fBcoap_log_info\fR() function provides a wrapper to the \fBcoap_log\fR() function with \fIlevel\fR set to COAP_LOG_INFO\&. The parameters follow the standard \fBprintf\fR() function format\&.
.sp
\fBFunction: coap_log_debug()\fR
.sp
The \fBcoap_log_debug\fR() function provides a wrapper to the \fBcoap_log\fR() function with \fIlevel\fR set to COAP_LOG_DEBUG\&. The parameters follow the standard \fBprintf\fR() function format\&.
.sp
\fBFunction: coap_log_oscore()\fR
.sp
The \fBcoap_log_oscore\fR() function provides a wrapper to the \fBcoap_log\fR() function with \fIlevel\fR set to COAP_LOG_OSCORE\&. The parameters follow the standard \fBprintf\fR() function format\&.
.sp
\fBFunction: coap_set_log_level()\fR
.sp
The \fBcoap_set_log_level\fR() function is used to set the current logging \fIlevel\fR for output by any subsequent \fBcoap_log\fR() calls\&. Output is only logged if the \fBcoap_log\fR() \fIlevel\fR definition is smaller than or equal to the current logging \fIlevel\fR\&.
.sp
\fBFunction: coap_get_log_level()\fR
.sp
The \fBcoap_get_log_level\fR() function is used to get the current logging level\&.
.sp
\fBFunction: coap_dtls_log()\fR
.sp
The \fBcoap_dtls_log\fR() function is used to log (D)TLS library information at the appropriate \fIlevel\fR\&. The rest of the parameters follow the standard \fBprintf\fR() function format\&.
.sp
\fBFunction: coap_dtls_set_log_level()\fR
.sp
The \fBcoap_dtls_set_log_level\fR() function is used to set the current logging \fIlevel\fR for output by any subsequent \fBcoap_dtls_log\fR() calls\&. Output is only logged if the \fBcoap_dtls_log\fR() \fIlevel\fR definition is smaller than or equal to the current DTLS logging \fIlevel\fR\&.
.sp
\fBFunction: coap_dtls_get_log_level()\fR
.sp
The \fBcoap_dtls_get_log_level\fR() function is used to get the current logging level for the DTLS library\&.
.sp
\fBFunction: coap_set_log_handler()\fR
.sp
The \fBcoap_set_log_handler\fR()* function can be used to define an alternative logging handler for processing any logging messages\&. The logging handler prototype is defined as:
.sp
.if n \{\
.RS 4
.\}
.nf
typedef void (*coap_log_handler_t) (coap_log_t level, const char *message);
.fi
.if n \{\
.RE
.\}
.sp
\fBFunction: coap_package_name()\fR
.sp
The \fBcoap_package_name\fR() function returns the name of this library\&.
.sp
\fBFunction: coap_package_version()\fR
.sp
The \fBcoap_package_version\fR() function returns the version of this library\&.
.sp
\fBFunction: coap_package_build()\fR
.sp
The \fBcoap_package_build\fR() function returns the git information (as in "git describe \-\-tags") for the build of this library or version of this library if git is not used\&.
.sp
\fBFunction: coap_set_show_pdu_output()\fR
.sp
The \fBcoap_set_show_pdu_output\fR() function defines whether the output from \fBcoap_show_pdu\fR() is to be either sent to stdout/stderr, or output using \fBcoap_log\fR()\&. \fIuse_fprintf\fR is set to 1 for stdout/stderr (the default), and \fIuse_fprintf\fR is set to 0 for \fBcoap_log\fR()\&.
.sp
\fBFunction: coap_show_pdu()\fR
.sp
The \fBcoap_show_pdu\fR() function is used to decode the \fIpdu\fR, outputting as appropriate for logging \fIlevel\fR\&. Where the output goes is dependent on \fBcoap_set_show_pdu_output\fR()\&.
.sp
\fBNOTE:\fR If \fIpdu\fR has not been associated with a CoAP session (i\&.e\&. not a received PDU or coap_send() not yet called), then the output assumes that this \fIpdu\fR is of type unreliable\&.
.sp
\fBFunction: coap_endpoint_str()\fR
.sp
The \fBcoap_endpoint_str\fR() function returns a description string of the \fIendpoint\fR\&.
.sp
\fBFunction: coap_session_str()\fR
.sp
The \fBcoap_session_str\fR() function is used to get a string containing the information about the \fIsession\fR\&.
.sp
\fBFunction: coap_print_addr()\fR
.sp
The \fBcoap_print_addr\fR() function returns the length of the description string containing the IP address and port from \fIaddress\fR, updating \fIbuffer\fR which has a maximum length \fIlength\fR\&.
.sp
\fBFunction: coap_print_ip_addr()\fR
.sp
The \fBcoap_print_ip_addr\fR() function returns a description string of the IP address only for \fIaddress\fR\&. \fIbuffer\fR is updated, which has a maximum length of \fIlength\fR\&.
.SH "RETURN VALUES"
.sp
\fBcoap_package_name\fR(), \fBcoap_package_version\fR() and \fBcoap_package_build\fR() return the appropriate zero\-terminated character string\&.
.sp
\fBcoap_get_log_level\fR() returns the current logging level\&.
.sp
\fBcoap_dtls_get_log_level\fR() returns the current logging level for the DTLS library specifics\&.
.sp
\fBcoap_endpoint_str\fR() returns a description string of the \fIendpoint\fR\&.
.sp
\fBcoap_session_str\fR() returns a description string of the \fIsession\fR\&.
.sp
\fBcoap_print_addr\fR() returns the length of \fIbuffer\fR that has been updated with an ascii readable IP address and port for \fIaddress\fR\&.
.sp
\fBcoap_print_ip_addr\fR() returns a pointer to the ascii readable IP address only for \fIaddress\fR\&.
.SH "SEE ALSO"
.sp
\fBcoap_context\fR(3) and \fBcoap_session\fR(3)
.SH "FURTHER INFORMATION"
.sp
See
.sp
"RFC7252: The Constrained Application Protocol (CoAP)"
.sp
for further information\&.
.SH "BUGS"
.sp
Please report bugs on the mailing list for libcoap: libcoap\-developers@lists\&.sourceforge\&.net or raise an issue on GitHub at https://github\&.com/obgm/libcoap/issues
.SH "AUTHORS"
.sp
The libcoap project <libcoap\-developers@lists\&.sourceforge\&.net>