From: schwarze <schwarze@openbsd.org>
Date: Sun, 9 Apr 2023 14:30:24 +0000 (+0000)
Subject: Explain what it means that an API function "requires event_init(3)"
X-Git-Url: http://artulab.com/gitweb/?a=commitdiff_plain;h=921d8f04919c5f54f19878ea51321c1bbd29b417;p=openbsd

Explain what it means that an API function "requires event_init(3)"
in one place, not in two places, reducing duplication of text.

Joint work with Ted Bullock.  OK jmc@.
---

diff --git a/lib/libevent/event_base_new.3 b/lib/libevent/event_base_new.3
index 3275ab494e7..4a7dc4769da 100644
--- a/lib/libevent/event_base_new.3
+++ b/lib/libevent/event_base_new.3
@@ -1,4 +1,4 @@
-.\" $OpenBSD: event_base_new.3,v 1.2 2023/04/06 20:52:18 schwarze Exp $
+.\" $OpenBSD: event_base_new.3,v 1.3 2023/04/09 14:30:24 schwarze Exp $
 .\" Copyright (c) 2023 Ted Bullock <tbullock@comlore.com>
 .\"
 .\" Permission to use, copy, modify, and distribute this software for any
@@ -13,7 +13,7 @@
 .\" 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 6 2023 $
+.Dd $Mdocdate: April 9 2023 $
 .Dt EVENT_BASE_NEW 3
 .Os
 .Sh NAME
@@ -73,11 +73,17 @@ behaves like
 except it additionally saves a pointer to the returned structure
 in an internal global variable.
 It is designed for programs that need only one single event loop.
-Invoking most functions documented in the event library to require
-.Fn event_init
-without first calling
+.Pp
+If
 .Fn event_init
-generates a segmentation fault.
+was not invoked before using an event API function that requires it,
+or if such a function is called after
+.Fn event_base_free
+has destroyed the structure that was returned from
+.Fn event_init ,
+a
+.Dv NULL
+pointer access occurs unless otherwise documented.
 .Pp
 After calling
 .Xr fork 2 ,
@@ -135,15 +141,6 @@ pointer argument triggers an
 .Xr assert 3
 call.
 .Pp
-Functions documented to require
-.Fn event_init
-generate a segmentation fault if invoked after
-.Fn event_base_free
-destroyed the internal global
-.Vt event_base
-structure that was created by
-.Fn event_init .
-.Pp
 Errors and diagnostics from many event library functions are reported using
 the log callback system configured with
 .Xr event_set_log_callback 3 .