Hi folks,
I'm writing manual pages for the libevent variant bundled with OpenBSD,
this is a documentation project that I started in something like 2012
but got pulled away from due to life circumstances. I've returned to
it after reading an old Things to Do - *urgent* list I left in a binder
over a decade ago. heh.
The impetus is that the event(3) manual page isn't all that good for
documenting how to use the library and it is missing functions that are
included in the API and available in the shared library.
Upstream of course has moved on to version 2.x, as far as I can tell
there is no more maintenance being done on the 1.4 version that OpenBSD
ships except the work that is done internally in the OS.
Anyway, here is what I came up with for a few functions after reading
the source tree. I also went back through historical releases to see
how the API evolved over time.
I'm planning to finish off documenting the rest of the library, if
folks have feedback, I'm interested.
Take Care,
event_init.3
============
.\" Copyright (c) 2023 Ted Bullock <tbull...@comlore.com>
.\"
.\" 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: January 9 2023 $
.Dt EVENT_INIT 3
.Os
.Sh NAME
.Nm event_base_new ,
.Nm event_init
.Nd initializes an
.Vt event_base
instance
.Sh SYNOPSIS
.In event.h
.Ft "struct event_base *"
.Fn event_base_new void
.Ft "struct event_base *"
.Fn event_init void
.Sh DESCRIPTION
The functions
.Fn event_base_new
and
.Fn event_init
initialize the
.Lb libevent
and need to be called prior to scheduling an event or
starting the event-loop. The two functions are similar, although global
variables are set when calling
.Fn event_init
to help simplify the API for programs requiring only one event-loop.
.Pp
The
.Lb libevent
API is generally not thread-safe unless only one
.Vt "event_base"
instance is accessible per thread or care is taken to lock access.
.Pp
These functions allocate memory that should be freed using
.Xr event_base_free 3 .
.Pp
Diagnostic and error messages are retrievable from these functions by
configuring a message log callback with
.Xr event_set_log_callback 3 .
.Pp
After a call to
.Xr fork 2
some notification methods will not persist and need to reinitiliazed with
.Xr event_reinit 3 .
.Sh RETURN VALUES
The
.Fn event_base_new
and
.Fn event_init
functions return a
.Vt "struct event_base"
pointer.
If the functions fail, for example, due to a lack of memory, they do
.Em NOT
return.
.Sh ENVIRONMENT
Programs using the
.Lb libevent
are configurable with environment variables prior to calling
.Fn event_base_new
or
.Fn event_init .
.Bl -tag
.It Ev Sy EVENT_SHOW_METHOD
If the log callback is configured, report which kernel notification method the
library is using.
.It Ev Sy EVENT_NOKQUEUE
Disable library support for
.Xr kqueue 2
.It Ev Sy EVENT_NOPOLL
Disable library support for
.Xr poll 2
.It Ev Sy EVENT_NOSELECT
Disable library support for
.Xr select 2
.El
.Sh EXAMPLES
In this example code a new
.Vt "struct event_base"
is initialized with support for logging.
This example also applies to
.Fn event_base_new ,
the difference being that internal global variables are configured to simplify
other parts of the API.
.Bd -literal -offset indent
#include <stdio.h>
#include <event.h>
void cb(int sev, const char* msg)
{
printf("%d: %s\n", sev, msg);
}
int main()
{
event_set_log_callback(cb);
struct event_base *base = event_init();
if (base == NULL) {
printf("event_init failed, will not return\\n");
return 1;
}
/* do something with the event library here */
event_base_free(base);
return 0;
}
.Ed
.Sh SEE ALSO
.Xr event_set_log_callback 3 ,
.Xr event_base_free 3 ,
.Xr event_dispatch 3
.Sh HISTORY
The function
.Fn event_init
first appeared in
.Lb libevent-0.1
although it's protoype has changed various times since that release. In
.Lb libevent-1.4.1beta
.Fn event_base_new
was added and
.Fn event_init
was once again changed to wrap around the new function.
.Pp
Environment variable options first appeared in
.Lb libevent-0.7a .
.Sh AUTHORS
The
.Lb libevent
was written by
.An -nosplit
.An Niels Provos
and
.An Nick Mathewson
.Pp
This manual was written by
.An Ted Bullock Aq Mt tbull...@comlore.com
event_set_log_callback.3
========================
.\" Copyright (c) 2023 Ted Bullock <tbull...@comlore.com>
.\"
.\" 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: January 15 2023 $
.Dt EVENT_SET_LOG_CALLBACK 3
.Os
.Sh NAME
.Nm event_set_log_callback
.Nd Defines a function to be called when libevent generates a log message.
.Sh SYNOPSIS
.Ft void
.Fn event_set_log_callback(void (*cb)(int severity, const char *msg))
.Sh DESCRIPTION
.Pp
The
.Fn event_set_log_callback
sets the callback function to be called when a log message is generated by
libevent.
.Pp
The callback function takes two arguments: the severity of the message and the
message text. The severity argument is an integer value representing the
severity of the message, with the following levels:
.Bl -tag
.It Dv _EVENT_LOG_DEBUG Pq 0 Pc
Messages for debugging purposes.
.It Dv _EVENT_LOG_MSG Pq 1 Pc
Messages for providing information.
.It Dv _EVENT_LOG_WARN Pq 2 Pc
Messages for non-fatal issues.
.It Dv _EVENT_LOG_ERR Pq 3 Pc
Messages for fatal issues; the library will stop the program after sending the
message to the log callbacks by calling
.Xr exit 3 .
.El
.Pp
If the callback function provided is a null pointer, the behavior is the same
as if no callback was provided at all.
.Pp
The message text is a null-terminated string.
.Sh RETURN VALUES
.Pp
This function does not return a value.
.Sh SEE ALSO
.Xr event 3 ,
.Xr event_init 3 ,
.Xr exit 3
.Sh HISTORY
.Pp
The event_set_log_callback function was first implemented in
.Lb libevent
version 1.1 released on May 14, 2005.
.Sh AUTHORS
The
.Lb libevent
was written by
.An -nosplit
.An Niels Provos
and
.An Nick Mathewson
.Pp
This manual was written by
.An Ted Bullock Aq Mt tbull...@comlore.com
event_reinit.3
==============
.\" Copyright (c) 2023 Ted Bullock <tbull...@comlore.com>
.\"
.\" 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: January 16 2023 $
.Dt EVENT_REINIT 3
.Os
.Sh NAME
.Nm event_reinit
.Nd Reinitialize the event library after a fork
.Sh SYNOPSIS
.In event.h
.Ft int
.Fn event_reinit "struct event_base *base"
.Sh DESCRIPTION
The function
.Fn event_reinit
is used to reinitialize the
.Lb libevent .
This is typically used after a
.Xr fork 2
call in the child process.
.Pp
The
.Fn event_reinit
function takes a single argument, which is a pointer to the
.Vt event_base
structure that was previously initialized with
.Xr event_init 3 .
The function reinitializes the internal state of the event library,
including the event notification mechanism and the event queue.
.Pp
If the function cannot initialize the kernel notification method, typically
.Xr kqueue 2 ,
.Xr poll 2
or
.Xr select 2
it will use the log callback to post the error and call
.Xr exit 3
to terminate the child process with return value of 1.
.Sh RETURN VALUES
The function
.Fn event_reinit
returns 0 on success and -1 when it is unable to reinitialize any scheduled
events registered to the
.Vt event_base .
.Sh EXAMPLES
This example program demonstrates how to use the
.Fn event_reinit
function from the libevent library to reinitialize the event library after a
fork. It also shows one way to handle errors and customize the way log
messages are handled.
.Bd -literal
#include <event.h>
#include <stdio.h>
#include <unistd.h>
#include <sys/wait.h>
void log_cb(int sev, const char *msg)
{
printf("[EVENT LOG] %s(%d)\\n", msg, sev);
}
int main()
{
event_set_log_callback(log_cb);
struct event_base *base = event_init();
pid_t pid = fork();
if (pid == 0) {
/* Child process */
if (event_reinit(base) == -1) {
printf("Child: failed to reinitialize events\\n");
return 1;
}
printf("libevent reinitialized in child process.\\n");
} else {
/* Parent process */
int status;
wait(&status);
if(WIFEXITED(status) && WEXITSTATUS(status) == 1) {
printf("Parent: got fatal error from child\\n");
return 1;
}
printf("libevent initialized in parent process.\\n");
}
event_base_free(base);
return 0;
}
.Ed
.Sh SEE ALSO
.Xr event_init 3 ,
.Xr event_set_log_callback 3 ,
.Xr fork 2
.Sh HISTORY
The first version of the
.Lb libevent
to include
.Fn event_reinit
was version 1.4.1-beta which was released on December 21, 2007.
.Sh AUTHORS
The
.Lb libevent
was written by
.An -nosplit
.An Niels Provos
and
.An Nick Mathewson
.Pp
This manual was written by
.An Ted Bullock Aq Mt tbull...@comlore.com
--
Ted Bullock <tbull...@comlore.com>
