@@@ much mess, mostly manpages

[mLib] / sel / sel.3.in

diff --git a/sel/sel.3 b/sel/sel.3.in
similarity index 86%
rename from sel/sel.3
rename to sel/sel.3.in
index da55fe8..8c99a8c 100644 (file)
--- a/sel/sel.3
+++ b/sel/sel.3.in
@@ -1,7 +1,34 @@
 .\" -*-nroff-*-
-.TH sel 3 "22 May 1999" "Straylight/Edgeware" "mLib utilities library"
-.SH NAME
-sel \- low level interface for waiting for I/O
+.\"
+.\" Manual for event-driven I/O core
+.\"
+.\" (c) 1999, 2001, 2005, 2007, 2009, 2023, 2024 Straylight/Edgeware
+.\"
+.
+.\"----- Licensing notice ---------------------------------------------------
+.\"
+.\" This file is part of the mLib utilities library.
+.\"
+.\" mLib is free software: you can redistribute it and/or modify it under
+.\" the terms of the GNU Library General Public License as published by
+.\" the Free Software Foundation; either version 2 of the License, or (at
+.\" your option) any later version.
+.\"
+.\" mLib is distributed in the hope that it will be useful, but WITHOUT
+.\" ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+.\" FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Library General Public
+.\" License for more details.
+.\"
+.\" You should have received a copy of the GNU Library General Public
+.\" License along with mLib.  If not, write to the Free Software
+.\" Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307,
+.\" USA.
+.
+.\"--------------------------------------------------------------------------
+.so ../defs.man \" @@@PRE@@@
+.
+.\"--------------------------------------------------------------------------
+.TH sel 3mLib "22 May 1999" "Straylight/Edgeware" "mLib utilities library"
 .\" @sel_init
 .\" @sel_initfile
 .\" @sel_addfile
@@ -13,7 +40,14 @@ sel \- low level interface for waiting for I/O
 .\" @sel_rmhook
 .\" @sel_fdmerge
 .\" @sel_select
+.
+.\"--------------------------------------------------------------------------
+.SH NAME
+sel \- low level interface for waiting for I/O
+.
+.\"--------------------------------------------------------------------------
 .SH SYNOPSIS
+.
 .nf
 .B "#include <mLib/sel.h>"
 .PP
@@ -71,7 +105,10 @@ sel \- low level interface for waiting for I/O
 .PP
 .BI "int sel_select(sel_state *" s );
 .fi
+.
+.\"--------------------------------------------------------------------------
 .SH "OVERVIEW"
+.
 The
 .B sel
 subsystem provides a structured way of handling I/O in a non-blocking
@@ -91,7 +128,10 @@ should consider
 .BR sel 's
 data structures to be opaque except where described here, and not fiddle
 around inside them.  Some things may become more sophisticated later.
+.
+.\"--------------------------------------------------------------------------
 .SH "IMPORTANT CONCEPTS"
+.
 The system is based around two concepts:
 .I multiplexors
 and
@@ -141,7 +181,10 @@ interface.  For examples, see
 .BR selbuf (3)
 and
 .BR conn (3).
+.
+.\"--------------------------------------------------------------------------
 .SH "PROGRAMMING INTERFACE"
+.
 .SS "Multiplexors"
 A multiplexor is represented using the type
 .B sel_state
@@ -162,6 +205,7 @@ initialization, addition to multiplexor, and removal from a
 multiplexor.  It's convenient to separate addition and removal from
 initialization because file selectors often get added and removed many
 times over during their lifetimes.
+.
 .SS "File selectors"
 A file selector is initialized by the
 .B sel_initfile
@@ -242,6 +286,7 @@ of the
 structure is exported.  It contains the file descriptor in which the
 selector is interested.  You may not modify this value, but it's useful
 to be able to read it out \- it saves having to keep a copy.
+.
 .SS "Timer selectors"
 Timer selectors are simpler.  There are only two operations provided on
 timer selectors: addition and removal.  Initialization is performed as
@@ -293,6 +338,7 @@ Note that timer events are a one-shot thing.  Once they've happened, the
 timer selector is removed and the event can't happen again.  This is
 normally what you want.  Removing a timer is only useful (or safe!)
 before the timer event has been sent.
+.
 .SS "Performing I/O"
 Finally, the function
 .B sel_select
@@ -303,6 +349,7 @@ everything went according to plan,
 returns zero.  Otherwise it returns \-1, and the global variable
 .B errno
 is set appropriately.
+.
 .SS "Hook functions"
 In order to interface other I/O multiplexing systems to this one, it's
 possible to register
@@ -403,7 +450,10 @@ the function sets in
 all of the descriptors set in
 .I fd
 and returns an accurate file descriptor count as its result.
+.
+.\"--------------------------------------------------------------------------
 .SH "OTHER NOTES"
+.
 Although the naming seems to suggest that this is all
 based around the BSD-ish
 .BR select (2)
@@ -413,11 +463,19 @@ more general than that.  An implementation which worked off System V-ish
 instead would be possible to make, and would look just the same from the
 outside.  Some work would be needed to make the hook functions work,
 though.
+.
+.\"--------------------------------------------------------------------------
 .SH "SEE ALSO"
+.
 .BR select (2),
 .BR poll (2),
 .BR conn (3),
 .BR selbuf (3),
 .BR mLib (3).
+.
+.\"--------------------------------------------------------------------------
 .SH AUTHOR
+.
 Mark Wooding, <mdw@distorted.org.uk>
+.
+.\"----- That's all, folks --------------------------------------------------