1.\" $OpenBSD: event_set_log_callback.3,v 1.2 2023/05/01 07:04:38 jsg Exp $ 2.\" Copyright (c) 2023 Ted Bullock <tbullock@comlore.com> 3.\" 4.\" Permission to use, copy, modify, and distribute this software for any 5.\" purpose with or without fee is hereby granted, provided that the above 6.\" copyright notice and this permission notice appear in all copies. 7.\" 8.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES 9.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF 10.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR 11.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 12.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN 13.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF 14.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 15.\" 16.Dd $Mdocdate: May 1 2023 $ 17.Dt EVENT_SET_LOG_CALLBACK 3 18.Os 19.Sh NAME 20.Nm event_set_log_callback 21.Nd set callback for diagnostics 22.Sh SYNOPSIS 23.In event.h 24.Ft typedef void 25.Fo (*event_log_cb) 26.Fa "int sev" 27.Fa "const char *msg" 28.Fc 29.Ft void 30.Fo event_set_log_callback 31.Fa "event_log_cb cb" 32.Fc 33.Sh DESCRIPTION 34The event library uses an optional callback function configured using 35.Fn event_set_log_callback 36to report error and diagnostic messages from many functions. 37By default the library does not report diagnostics. 38After executing the callback to report an error the event library invokes 39.Xr exit 3 ; 40this happens even if no callback is configured. 41.Pp 42.Fa cb 43is a function pointer to a callback with the following parameters: 44.Bl -tag -width 4n 45.It Fa sev : 46represents the severity of the message and may be one of: 47.Bl -tag -width "_EVENT_LOG_DEBUG" 48.It Dv _EVENT_LOG_DEBUG 49Messages for debugging purposes. 50These message are suppressed by the library unless it is compiled with 51.Dv USE_DEBUG . 52.It Dv _EVENT_LOG_MSG 53Messages providing information. 54.It Dv _EVENT_LOG_WARN 55Messages indicating non-fatal issues. 56.It Dv _EVENT_LOG_ERR 57Messages indicating fatal issues. 58The library terminates the program by calling 59.Xr exit 3 60after reporting the message. 61.El 62.It Fa msg : 63an ASCII string containing the message. 64.El 65.Pp 66Default behavior is restored and callbacks are prevented if 67.Fa cb 68is 69.Dv NULL . 70.Sh EXAMPLES 71The following C program illustrates use of 72.Fn event_set_log_callback . 73The callback function 74.Fn cb 75includes logic to identify the severity levels of diagnostic messages. 76.Bd -literal -offset indent 77#include <event.h> 78#include <stdio.h> 79#include <stdlib.h> 80 81void 82cb(int sev, const char *msg) 83{ 84 switch (sev) { 85 case _EVENT_LOG_DEBUG: 86 printf("DEBUG: %s\en", msg); 87 break; 88 case _EVENT_LOG_MSG: 89 printf("INFO: %s\en", msg); 90 break; 91 case _EVENT_LOG_WARN: 92 printf("WARNING: %s\en", msg); 93 break; 94 case _EVENT_LOG_ERR: 95 printf("ERROR: %s\en", msg); 96 break; 97 } 98} 99 100int 101main(int argc, char *argv[]) 102{ 103 struct event_base *eb; 104 /* Redirect diagnostic messages to `cb` callback */ 105 event_set_log_callback(cb); 106 /* Report the kernel notification method */ 107 setenv("EVENT_SHOW_METHOD", "", 1); 108 /* Initialize library; failures won't return */ 109 eb = event_base_new(); 110 /* Disable diagnostic messages */ 111 event_set_log_callback(NULL); 112 113 /* Do something with the event library here */ 114 115 /* Deallocate memory */ 116 event_base_free(eb); 117 return 0; 118} 119.Ed 120.Sh SEE ALSO 121.Xr event_base_new 3 , 122.Xr exit 3 123.Sh HISTORY 124.Fn event_set_log_callback 125first appeared in libevent-1.0c and has been available since 126.Ox 3.8 . 127.Sh AUTHORS 128The event library was written by 129.An -nosplit 130.An Niels Provos . 131.Pp 132.Fn event_set_log_callback 133and the diagnostic reporting system was written by 134.An Nick Mathewson . 135.Pp 136This manual page was written by 137.An Ted Bullock Aq Mt tbullock@comlore.com . 138