From 10aec1099239488b7a54fed2865286cb8904cd9c Mon Sep 17 00:00:00 2001 From: schwarze Date: Sat, 29 Apr 2023 15:38:14 +0000 Subject: [PATCH] New manual page written by Ted Bullock, dropping the empty RETURN VALUES section and adding the missing "#include " below EXAMPLES. --- lib/libevent/event_set_log_callback.3 | 137 ++++++++++++++++++++++++++ 1 file changed, 137 insertions(+) create mode 100644 lib/libevent/event_set_log_callback.3 diff --git a/lib/libevent/event_set_log_callback.3 b/lib/libevent/event_set_log_callback.3 new file mode 100644 index 00000000000..d4c18180193 --- /dev/null +++ b/lib/libevent/event_set_log_callback.3 @@ -0,0 +1,137 @@ +.\" $OpenBSD: event_set_log_callback.3,v 1.1 2023/04/29 15:38:14 schwarze Exp $ +.\" Copyright (c) 2023 Ted Bullock +.\" +.\" Permission to use, copy, modify, and distribute this software for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES +.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF +.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR +.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES +.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN +.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF +.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.Dd $Mdocdate: April 29 2023 $ +.Dt EVENT_SET_LOG_CALLBACK 3 +.Os +.Sh NAME +.Nm event_set_log_callback +.Nd set callback for diagnostics +.Sh SYNOPSIS +.In event.h +.Ft typedef void +.Fo (*event_log_cb) +.Fa "int sev" +.Fa "const char *msg" +.Fc +.Ft void +.Fo event_set_log_callback +.Fa "event_log_cb cb" +.Fc +.Sh DESCRIPTION +The event library uses an optional callback function configured using +.Fn event_set_log_callback +to report error and diagnostic messages from many functions. +By default the library does not report diagnostics. +After executing the callback to report an error the event library invokes +.Xr exit 3 ; +this happens even if no callback is configured. +.Pp +.Fa cb +is a function pointer to a callback with the following parameters: +.Bl -tag -width 4n +.It Fa sev : +represents the severity of the message and may be one of: +.Bl -tag -width "_EVENT_LOG_DEBUG" +.It Dv _EVENT_LOG_DEBUG +Messages for debugging purposes. +These message are suppressed by the library unless it is compiled with +.Dv USE_DEBUG . +.It Dv _EVENT_LOG_MSG +Messages providing information. +.It Dv _EVENT_LOG_WARN +Messages indicating non-fatal issues. +.It Dv _EVENT_LOG_ERR +Messages indicating fatal issues. +The library terminates the program by calling +.Xr exit 3 +after reporting the message. +.El +.It Fa msg : +an ASCII string containing the message. +.El +.Pp +Default behavior is restored and callbacks are prevented if +.Fa cb +is +.Dv NULL . +.Sh EXAMPLES +The following C program illustrates use of +.Fn event_set_log_callback . +The callback function +.Fn cb +includes logic to identify the severity levels of diagnostic messages. +.Bd -literal -offset indent +#include +#include +#include + +void +cb(int sev, const char *msg) +{ + switch (sev) { + case _EVENT_LOG_DEBUG: + printf("DEBUG: %s\en", msg); + break; + case _EVENT_LOG_MSG: + printf("INFO: %s\en", msg); + break; + case _EVENT_LOG_WARN: + printf("WARNING: %s\en", msg); + break; + case _EVENT_LOG_ERR: + printf("ERROR: %s\en", msg); + break; + } +} + +int +main(int argc, char *argv[]) +{ + struct event_base *eb; + /* Redirect diagnostic messages to `cb` callback */ + event_set_log_callback(cb); + /* Report the kernel notification method */ + setenv("EVENT_SHOW_METHOD", "", 1); + /* Initialize library; failures won't return */ + eb = event_base_new(); + /* Disable diagnostic messages */ + event_set_log_callback(NULL); + + /* Do something with the event library here */ + + /* Deallocate memory */ + event_base_free(eb); + return 0; +} +.Ed +.Sh SEE ALSO +.Xr event_base_new 3 , +.Xr exit 3 +.Sh HISTORY +.Fn event_set_log_callback +first appeared in libevent-1.0c and has been available since +.Ox 3.8 . +.Sh AUTHORS +The event library was written by +.An -nosplit +.An Niels Provos . +.Pp +.Fn event_set_log_callback +and the diagnostic reporting system was written by +.An Nick Mathewson . +.Pp +This manual page was written by +.An Ted Bullock Aq Mt tbullock@comlore.com . -- 2.20.1