SUBDIRS += trace
libmLib_la_LIBADD += trace/libtrace.la
+## At this point we should construct the library.
+SUBDIRS += .
+
+## Examples.
+SUBDIRS += test/example
+
+###--------------------------------------------------------------------------
+### Manual.
+
+EXTRA_DIST += defs.man
+
+EXTRA_DIST += mLib.3.in
+LIBMANS += mLib.3
+
###--------------------------------------------------------------------------
### Testing.
## Line buffering.
pkginclude_HEADERS += lbuf.h
libbuf_la_SOURCES += lbuf.c
+EXTRA_DIST += lbuf.3.in
LIBMANS += lbuf.3
## Packet buffering.
pkginclude_HEADERS += pkbuf.h
libbuf_la_SOURCES += pkbuf.c
+EXTRA_DIST += pkbuf.3.in
LIBMANS += pkbuf.3
###----- That's all, folks --------------------------------------------------
.\" -*-nroff-*-
-.TH lbuf 3 "6 July 1999" "Straylight/Edgeware" "mLib utilities library"
-.SH "NAME"
-lbuf \- split lines out of asynchronously received blocks
-.\" @lbuf_flush
+.\"
+.\" Manual for line buffering
+.\"
+.\" (c) 1999--2003, 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 lbuf 3mLib "6 July 1999" "Straylight/Edgeware" "mLib utilities library"
.\" @lbuf_close
.\" @lbuf_free
.\" @lbuf_snarf
.\" @lbuf_setsize
.\" @lbuf_init
.\" @lbuf_destroy
+.
+.\"--------------------------------------------------------------------------
+.SH "NAME"
+lbuf \- split lines out of asynchronously received blocks
+.
+.\"--------------------------------------------------------------------------
.SH "SYNOPSIS"
+.
.nf
.ta 2n
.B "#include <mLib/lbuf.h>"
.B "typedef void lbuf_func(char *" s ", size_t " len ", void *" p );
.PP
.BI "void lbuf_flush(lbuf *" b ", char *" p ", size_t " len );
+.\" @lbuf_flush
.BI "void lbuf_close(lbuf *" b );
.BI "size_t lbuf_free(lbuf *" b ", char **" p );
.BI "void lbuf_snarf(lbuf *" b ", const void *" p ", size_t " sz );
.BI "void lbuf_init(lbuf *" b ", lbuf_func *" func ", void *" p );
.BI "void lbuf_destroy(lbuf *" b );
.fi
+.
+.\"--------------------------------------------------------------------------
.SH "DESCRIPTION"
+.
The declarations in
.B <mLib/lbuf.h>
implement a handy object called a
structure should normally be considered opaque (see the section on
.B Disablement
for an exception to this).
+.
.SS "Initialization and finalization"
The function
.B lbuf_init
A line buffer must be destroyed after use by calling
.BR lbuf_destroy ,
passing it the address of the buffer block.
+.
.SS "Inserting data into the buffer"
There are two interfaces for inserting data into the buffer. One's much
simpler than the other, although it's less expressive.
function is trivially implemented in terms of the more complex
.BR lbuf_free / lbuf_flush
interface.
+.
.SS "Line breaking"
By default, the line buffer considers a line to end with either a simple
linefeed character (the normal Unix convention) or a
memory. Instead, the buffer will truncate overly long lines (silently)
and return only the initial portion. It will ignore the rest of the
line completely.
+.
.SS "Line-handler functions"
Completed lines, as already said, are passed to the caller's
line-handler function. It is given three arguments: the address
may be null to signify end-of-file; in this case, the length
.I len
will be zero. See the next section.
+.
.SS "Flushing the remaining data"
When the client program knows that there's no more data arriving (for
example, an end-of-file condition exists on its data source) it should
handler, if there is any, and then call the handler one final time with
a null pointer rather than the address of a text line to inform it of
the end-of-file.
+.
.SS "Disablement"
The line buffer is intended to be used in higher-level program objects,
such as the buffer selector described in
the interface so much that it wouldn't have any advantage over the more
general
.BR lbuf_free / lbuf_flush .
+.
+.\"--------------------------------------------------------------------------
.SH "SEE ALSO"
+.
.BR selbuf (3),
.BR mLib (3).
+.
+.\"--------------------------------------------------------------------------
.SH "AUTHOR"
+.
Mark Wooding, <mdw@distorted.org.uk>
+.
+.\"----- That's all, folks --------------------------------------------------
.\" -*-nroff-*-
-.TH pkbuf 3 "16 July 2000" "Straylight/Edgeware" "mLib utilities library"
-.SH "NAME"
-pkbuf \- split packets out of asynchronously received blocks
+.\"
+.\" Manual for packet splitting
+.\"
+.\" (c) 1999--2003, 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 pkbuf 3mLib "16 July 2000" "Straylight/Edgeware" "mLib utilities library"
.\" @pkbuf_flush
.\" @pkbuf_close
.\" @pkbuf_free
.\" @pkbuf_want
.\" @pkbuf_init
.\" @pkbuf_destroy
+.
+.\"--------------------------------------------------------------------------
+.SH "NAME"
+pkbuf \- split packets out of asynchronously received blocks
+.
+.\"--------------------------------------------------------------------------
.SH "SYNOPSIS"
+.
.nf
.ta 2n
.B "#include <mLib/pkbuf.h>"
.BI "void pkbuf_init(pkbuf *" pk ", pkbuf_func *" func ", void *" p );
.BI "void pkbuf_destroy(pkbuf *" pk );
.fi
-.SH "DESCRIPTION"
+.
+.\"--------------------------------------------------------------------------
+SH "DESCRIPTION"
+.
The declarations in
.B <mLib/pkbuf.h>
implement a
structure should normally be considered opaque (see the section on
.B Disablement
for an exception to this).
+.
.SS "Initialization and finalization"
The function
.B pkbuf_init
A packet buffer must be destroyed after use by calling
.BR pkbuf_destroy ,
passing it the address of the buffer block.
+.
.SS "Inserting data into the buffer"
There are two interfaces for inserting data into the buffer. One's much
simpler than the other, although it's less expressive.
function is trivially implemented in terms of the more complex
.BR pkbuf_free / pkbuf_flush
interface.
+.
.SS "Packet breaking and the handler function"
The function
.B pkbuf_want
The pointer which was set up in the call to
.BR pkbuf_init .
.PP
+.
.SS "Flushing the remaining data"
When the client program knows that there's no more data arriving (for
example, an end-of-file condition exists on its data source) it should
.BR pkbuf_close .
This will call the handler one final time with a null pointer to inform
it of the end-of-file.
+.
.SS "Disablement"
The packet buffer is intended to be used in higher-level program
objects, such as the packet selector described in
the interface so much that it wouldn't have any advantage over the more
general
.BR pkbuf_free / pkbuf_flush .
+.
+.\"--------------------------------------------------------------------------
.SH "SEE ALSO"
+.
.BR lbuf (3),
.BR selpk (3),
.BR mLib (3).
+.
+.\"--------------------------------------------------------------------------
.SH "AUTHOR"
+.
Mark Wooding, <mdw@distorted.org.uk>
+.
+.\"----- That's all, folks --------------------------------------------------
## Codec base.
pkginclude_HEADERS += codec.h
libcodec_la_SOURCES += codec.c
+EXTRA_DIST += codec.3.in
LIBMANS += codec.3
## null
## Simple binary base-conversion codecs.
pkginclude_HEADERS += base64.h base32.h hex.h
libcodec_la_SOURCES += baseconv.c
+EXTRA_DIST += base64.3.in
LIBMANS += base64.3
## form-urlencoded
pkginclude_HEADERS += url.h
libcodec_la_SOURCES += url.c
+EXTRA_DIST += url.3.in
LIBMANS += url.3
## Test program.
bin_PROGRAMS += bincode
+EXTRA_DIST += bincode.1.in
PROGMANS += bincode.1
bincode_SOURCES = bincode.c
.\" -*-nroff-*-
-.TH base64 3 "20 June 1999" "Straylight/Edgeware" "mLib utilities library"
-.SH NAME
-base64, base32, hex \- obsolete binary encoding functions
+.\"
+.\" Manual for old-fashioned binary encoding and decoding
+.\"
+.\" (c) 1999, 2001, 2004, 2005, 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 base64 3mLib "20 June 1999" "Straylight/Edgeware" "mLib utilities library"
.\" @base64_encode
.\" @base64_decode
.\" @base64_init
.\" @hex_encode
.\" @hex_decode
.\" @hex_init
+.
+.\"--------------------------------------------------------------------------
+.SH NAME
+base64, base32, hex \- obsolete binary encoding functions
+.
+.\"--------------------------------------------------------------------------
.SH SYNOPSIS
+.
.nf
.B "#include <mLib/base64.h>"
.B "#include <mLib/base32.h>"
.BI " dstr *" d );
.BI "void hex_init(hex_ctx *" ctx );
.fi
+.
+.\"--------------------------------------------------------------------------
.SH DESCRIPTION
+.
The
.BR base64 ,
.BR base32 ,
in the case of Base64 and Base32 encodings, it also ignores
.RB ` = '
characters in the string.
+.
+.\"--------------------------------------------------------------------------
.SH "SEE ALSO"
+.
.BR codec (3),
.BR dstr (3),
.BR mLib (3).
+.
+.\"--------------------------------------------------------------------------
.SH AUTHOR
+.
Mark Wooding, <mdw@distorted.org.uk>
+.
+.\"----- That's all, folks --------------------------------------------------
.\" nroff
+.\"
+.\" Manual for `bincode' utility
+.\"
+.\" (c) 2009, 2014, 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 bincode 1 "9 January 2009" "Straylight/Edgeware" "mLib utilities library"
+.
+.\"--------------------------------------------------------------------------
.SH NAME
bincode \- binary-to-text encoding and decoding
+.
+.\"--------------------------------------------------------------------------
.SH SYNOPSIS
+.
.B bincode
.RB [ \-de]
.RB [ \-f
.RB [ \-o
.IR output ]
.RI [ file ...]
+.
+.\"--------------------------------------------------------------------------
.SH DESCRIPTION
+.
The
.B bincode
program encodes binary data as plain text (suitable, for example, for
text mode when decoding.
.PP
If an error is encountered, the output may be partially written.
+.
+.\"--------------------------------------------------------------------------
.SH "SEE ALSO"
+.
.BR codec (3).
+.
+.\"--------------------------------------------------------------------------
.SH "AUTHOR"
+.
Mark Wooding, <mdw@distorted.org.uk>
-.PP
+.
+.\"----- That's all, folks --------------------------------------------------
+
.\" -*-nroff-*-
-.TH codec 3 "9 January 2009" "Straylight/Edgeware" "mLib utilities library"
-.SH NAME
-codec \- binary encoding and decoding
+.\"
+.\" Manual for new-fangled binary encoding and decoding
+.\"
+.\" (c) 2009, 2014, 2015, 2019, 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 codec 3mLib "9 January 2009" "Straylight/Edgeware" "mLib utilities library"
.\" @codec_class
.\" @codec_strerror
.\" @null_codec_class
.\" @base32_class
.\" @base32hex_class
.\" @hex_class
+.
+.\"--------------------------------------------------------------------------
+.SH NAME
+codec \- binary encoding and decoding
+.
+.\"--------------------------------------------------------------------------
.SH SYNOPSIS
+.
.nf
.B "#include <mLib/codec.h>"
.B "#include <mLib/base64.h>"
.PP
.BI "const char *codec_strerror(int " err ");"
.fi
+.
+.\"--------------------------------------------------------------------------
.SH DESCRIPTION
+.
The
.B codec
system provides an object-based interface to functions which encode
binary data as plain text and decode the result to recover the original
binary data. The interface makes it easy to support multiple encodings
and select an appropriate one at runtime.
+.
.SS "The codec_class structure"
The
.B codec_class
corresponding encoder would produce (with
.I maxline
= 0 to inhibit line-breaking).
+.
.SS "The codec and codec_ops structures"
The
.B codec
.B codec_strerror
function converts these error codes to brief, (moderately)
human-readable strings.
+.
.SS "Provided codecs"
The library provides a number of standard codecs.
.TP
Implements hex encoding, defined by RFC4648 under the name Base16. For
compatibility with that specification, output is in upper case by
default.
+.
+.\"--------------------------------------------------------------------------
.SH "SEE ALSO"
+.
.BR bincode (1),
.BR dstr (3),
.BR mLib (3).
+.
+.\"--------------------------------------------------------------------------
.SH AUTHOR
+.
Mark Wooding, <mdw@distorted.org.uk>
+.
+.\"----- That's all, folks --------------------------------------------------
.\" -*-nroff-*-
-.de VS
-.sp 1
-.in +5n
-.ft B
-.nf
-..
-.de VE
-.ft R
-.in -5n
-.sp 1
-.fi
-..
-.ie t \{\
-. de VP
-. sp .4v
-..
-\}
-.el \{\
-. de VP
-. sp
-..
-\}
-.TH url 3 "20 June 1999" "Straylight/Edgeware" "mLib utilities library"
-.SH NAME
-url \- manipulation of form-urlencoded strings
+.\"
+.\" Manual for form-urlencoding
+.\"
+.\" (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 url 3mLib "20 June 1999" "Straylight/Edgeware" "mLib utilities library"
.\" @url_initenc
.\" @url_enc
.\" @url_initdec
.\" @url_dec
+.
+.\"--------------------------------------------------------------------------
+.SH NAME
+url \- manipulation of form-urlencoded strings
+.
+.\"--------------------------------------------------------------------------
.SH SYNOPSIS
+.
.nf
.B "#include <mLib/url.h>"
.PP
.BI "void url_initdec(url_dctx *" ctx ", const char *" p );
.BI "int url_dec(url_dctx *" ctx ", dstr *" n ", dstr *" v );
.fi
+.
+.\"--------------------------------------------------------------------------
.SH DESCRIPTION
+.
The functions in
.B <mLib/url.h>
read and write `form-urlencoded' data, as specified in RFC1866. The
the use of the semicolon, and when decoding, it
.I permits
its use.)
+.
+.\"--------------------------------------------------------------------------
.SH EXAMPLE
+.
The example code below demonstrates converting between a symbol table
and a urlencoded representation. The code is untested.
.VS
url_enc(&c, d, SYM_NAME(v), v->v);
}
.VE
+.
+.\"--------------------------------------------------------------------------
.SH "SEE ALSO"
+.
.BR mLib (3).
+.
+.\"--------------------------------------------------------------------------
.SH AUTHOR
+.
Mark Wooding, <mdw@distorted.org.uk>.
+.
+.\"----- That's all, folks --------------------------------------------------
[struct/Makefile]
[sys/Makefile]
[test/Makefile]
+ [test/example/Makefile]
[trace/Makefile]
[ui/Makefile]
[utils/Makefile]
--- /dev/null
+.\" -*-nroff-*-
+.\"
+.\" Common definitions for mLib manpages
+.\"
+.\" (c) 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.
+.
+.\"--------------------------------------------------------------------------
+.\" Preliminary definitions.
+.
+.\" String definitions and font selection.
+.ie t \{\
+. ds o \(bu
+. ds ss \s8\u
+. ds se \d\s0
+. ds us \s8\d
+. ds ue \u\s0
+. ds *d \(*d
+. ds <= \<>=
+. ds >= \(>=
+. ds , \h'\w'\ 'u/2u'
+. if \n(.g \{\
+. fam P
+. ev an-1
+. fam P
+. ev
+. \}
+.\}
+.el \{\
+. ds o o
+. ds ss ^
+. ds se
+. ds us _
+. ds ue
+. ds *d \,\fIdelta\/\fP
+. ds <= <=
+. ds >= >=
+. ds , \ \"
+.\}
+..
+.
+.\" hP TEXT -- start an indented paragraph with TEXT hanging off to the left
+.de hP
+. IP
+. ft B
+\h'-\w'\\$1\ 'u'\\$1\ \c
+. ft P
+..
+.
+.\" .VS ... .VE -- present a code sample; separate paragraphs with `.VP'
+.de VS
+. sp
+. RS
+. nf
+. ft B
+..
+.ie t \{\
+. de VP
+. sp .4v
+..
+.\}
+.el \{\
+. de VP
+. sp
+..
+.\}
+.de VE
+. ft R
+. fi
+. RE
+. sp
+..
+.
+.\"----- That's all, folks --------------------------------------------------
## CRC32.
pkginclude_HEADERS += crc32.h
libhash_la_SOURCES += crc32.c
+EXTRA_DIST += crc32.3.in
LIBMANS += crc32.3
bin_PROGRAMS += crc-mktab
crc_mktab_SOURCES = crc-mktab.c
crc_mktab_LDADD = $(UTIL_LIBS)
+EXTRA_DIST += crc-mktab.1.in
PROGMANS += crc-mktab.1
nodist_libhash_la_SOURCES += ../precomp/crc32-tab.c
noinst_LTLIBRARIES += libunihash.la
libunihash_la_SOURCES = unihash.c
libhash_la_LIBADD += libunihash.la
+EXTRA_DIST += unihash.3.in
LIBMANS += unihash.3
bin_PROGRAMS += unihash-mkstatic
unihash_mkstatic_SOURCES = unihash-mkstatic.c
unihash_mkstatic_LDADD = libunihash.la $(UTIL_LIBS)
+EXTRA_DIST += unihash-mkstatic.1.in
PROGMANS += unihash-mkstatic.1
nodist_libhash_la_SOURCES += ../precomp/unihash-global.c
.\" nroff
-.ie t \{\
-. ds ss \s8\u
-. ds se \d\s0
-.\}
-.el \{\
-. ds ss ^
-. ds se
-.\}
+.\"
+.\" Manual for CRC table generator
+.\"
+.\" (c) 2003, 2005, 2007, 2009, 2019, 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 crc-mktab 1 "9 November 2003" "Straylight/Edgeware" "mLib utilities library"
+.
+.\"--------------------------------------------------------------------------
.SH NAME
crc-mktab \- construct CRC tables for efficient computation
+.
+.\"--------------------------------------------------------------------------
.SH SYNOPSIS
+.
.B crc-mktab
.RB [ \-Ccr ]
.RB [ \-s
\c
.RB [ \-o
.IR filename ]
+.
+.\"--------------------------------------------------------------------------
.SH DESCRIPTION
+.
The
.B crc-mktab
program constructs tables for efficient computation of CRC (cyclic
option.
.TP
.BI "\-i, \-\-include=" header
+.RS
Request that generated C source include the named
.I header
file. Inserts a
line of the form
-.PP
-.nf
-.BI " #include """ header """"
-.fi
.IP
+.BI "#include """ header """"
+.PP
at the top of the generated C source. The default is not to include a
header file. This option does nothing without the
.B \-c
option.
+.RE
.TP
.BI "\-g, \-\-guard=" macro
+.RS
Use the named
.I macro
as a guard against multiple inclusion of the generated header file.
Inserts a pair of lines of the form
-.PP
-.nf
-.BI " #ifndef " macro
-.BI " #define " macro
-.fi
.IP
-at the top of the generated header, and a line
-.PP
.nf
-.BI " #endif"
+.BI "#ifndef " macro
+.BI "#define " macro
.fi
+.PP
+at the top of the generated header, and a line
.IP
+.BI "#endif"
+.PP
at the end. The default guard macro name is built from the output file
name specified with
.B \-o
This option does nothing with the
.B \-c
option.
+.RE
.TP
.BI "\-b, \-\-bits=" bits
Specifies the degree of the CRC polynomial or, equivalently, the length
Describing in detail the contents of the table would take too long. For
an example of use, see the header file
.BR crc32.h .
+.
+.\"--------------------------------------------------------------------------
.SH "SEE ALSO"
+.
.BR crc32 (3).
.PP
.I A painless guide to CRC error detection algorithms
by Ross N. Williams.
+.
+.\"--------------------------------------------------------------------------
.SH "AUTHOR"
+.
Mark Wooding, <mdw@distorted.org.uk>
+.
+.\"----- That's all, folks --------------------------------------------------
+++ /dev/null
-.\" -*-nroff-*-
-.ie t \{\
-. ds ss \s8\u
-. ds se \d\s0
-.\}
-.el \{\
-. ds ss ^
-. ds se
-.\}
-.TH crc32 3 "8 May 1999" "Straylight/Edgeware" "mLib utilities library"
-.SH NAME
-crc32 \- calculate 32-bit CRC
-.\" @crc32
-.SH SYNOPSIS
-.nf
-.B "#include <mLib/crc32.h>"
-.PP
-.BI "uint32 crc32(uint32 " crc ", const void *" buf ", size_t " sz );
-.BI CRC32( result ", " crc ", " buf ", " sz )
-.fi
-.SH DESCRIPTION
-The
-.B crc32
-function calculates a 32-bit cyclic redundancy check of the data block
-at address
-.I buf
-and size
-.I sz
-passed to it.
-.PP
-The function is restartable. For a first call, pass zero as the value
-of the
-.I crc
-argument; for subsequent blocks, pass in the previous output. The final
-answer is equal to the result you'd get from computing a CRC over the
-concatenation of the individual blocks.
-.PP
-The
-.B CRC32
-macro calculates a CRC inline. The calculated CRC value is placed in
-the variable named by
-.IR result .
-Only use the macro version when efficiency is a major concern: it makes
-the code rather harder to read.
-.PP
-Note that a CRC is not cryptographically strong: it's fairly easy for an
-adversary to construct blocks of data with any desired CRC, or to modify
-a given block in a way which doesn't change its (unknown) CRC.
-.PP
-The exact behaviour of the CRC is beyond the scope of this manual;
-suffice to say that the result is, in some suitable representation, the
-remainder after division by a degree-32 polynomial in GF(2)[x].
-.SH "RETURN VALUE"
-The return value is the 32-bit CRC of the input block.
-.SH "SEE ALSO"
-.BR unihash (3),
-.BR mLib (3).
-.SH AUTHOR
-Mark Wooding, <mdw@distorted.org.uk>
--- /dev/null
+.\" -*-nroff-*-
+.\"
+.\" Manual for CRC23 calculator
+.\"
+.\" (c) 1999--2001, 2003, 2005, 2009, 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 crc32 3mLib "8 May 1999" "Straylight/Edgeware" "mLib utilities library"
+.\" @crc32
+.
+.\"--------------------------------------------------------------------------
+.SH NAME
+crc32 \- calculate 32-bit CRC
+.
+.\"--------------------------------------------------------------------------
+.SH SYNOPSIS
+.
+.nf
+.B "#include <mLib/crc32.h>"
+.PP
+.BI "uint32 crc32(uint32 " crc ", const void *" buf ", size_t " sz );
+.BI CRC32( result ", " crc ", " buf ", " sz )
+.fi
+.
+.\"--------------------------------------------------------------------------
+.SH DESCRIPTION
+.
+The
+.B crc32
+function calculates a 32-bit cyclic redundancy check of the data block
+at address
+.I buf
+and size
+.I sz
+passed to it.
+.PP
+The function is restartable. For a first call, pass zero as the value
+of the
+.I crc
+argument; for subsequent blocks, pass in the previous output. The final
+answer is equal to the result you'd get from computing a CRC over the
+concatenation of the individual blocks.
+.PP
+The
+.B CRC32
+macro calculates a CRC inline. The calculated CRC value is placed in
+the variable named by
+.IR result .
+Only use the macro version when efficiency is a major concern: it makes
+the code rather harder to read.
+.PP
+Note that a CRC is not cryptographically strong: it's fairly easy for an
+adversary to construct blocks of data with any desired CRC, or to modify
+a given block in a way which doesn't change its (unknown) CRC.
+.PP
+The exact behaviour of the CRC is beyond the scope of this manual;
+suffice to say that the result is, in some suitable representation, the
+remainder after division by a degree-32 polynomial in GF(2)[x].
+.
+.\"--------------------------------------------------------------------------
+.SH "RETURN VALUE"
+The return value is the 32-bit CRC of the input block.
+.
+.\"--------------------------------------------------------------------------
+.SH "SEE ALSO"
+.
+.BR unihash (3),
+.BR mLib (3).
+.
+.\"--------------------------------------------------------------------------
+.SH AUTHOR
+.
+Mark Wooding, <mdw@distorted.org.uk>
+.
+.\"----- That's all, folks --------------------------------------------------
.\" nroff
-.ie t \{\
-. ds ss \s8\u
-. ds se \d\s0
-.\}
-.el \{\
-. ds ss ^
-. ds se
-.\}
+.\"
+.\" Manual for universal hashing table generator
+.\"
+.\" (c) 2003, 2005, 2007, 2009, 2019, 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 unihash-mkstatic 1 "14 December 2003" "Straylight/Edgeware" "mLib utilities library"
+.
+.\"--------------------------------------------------------------------------
.SH NAME
unihash-mkstatic \- construct tables for universal hashing
+.
+.\"--------------------------------------------------------------------------
.SH SYNOPSIS
+.
.B unihash-mkstatic
.RB [ \-Cc ]
.RB [ \-s
.IR key ]
.RB [ \-o
.IR filename ]
+.
+.\"--------------------------------------------------------------------------
.SH DESCRIPTION
+.
The
.B unihash-mkstatic
program constructs tables for efficient universal hashing (see
.BR unihash (3)).
It will produce the table as either an array defined in a C source file
or as an initializer macro defined in a C header file.
+.
.SS "Options"
The program accepts no non-option arguments. The options are as
follows.
.BR uhi .
.TP
.BI "\-i, \-\-include=" header
+.RS
Request that generated C source include the named
.I header
file. Inserts a
line of the form
-.PP
-.nf
-.BI " #include """ header """"
-.fi
.IP
+.BI "#include """ header """"
+.PP
at the top of the generated C source. The default is not to include
.BR <mLib/unihash.h> ,
which is necessary to declare the
type. This option does nothing without the
.B \-c
option.
+.RE
.TP
.BI "\-g, \-\-guard=" macro
+.RS
Use the named
.I macro
as a guard against multiple inclusion of the generated header file.
Inserts a pair of lines of the form
-.PP
-.nf
-.BI " #ifndef " macro
-.BI " #define " macro
-.fi
.IP
-at the top of the generated header, and a line
-.PP
.nf
-.BI " #endif"
+.BI "#ifndef " macro
+.BI "#define " macro
.fi
+.PP
+at the top of the generated header, and a line
.IP
+.BI "#endif"
+.PP
at the end. The default guard macro name is built from the output file
name specified with
.B \-o
This option does nothing with the
.B \-c
option.
+.RE
.TP
.BI "\-k, \-\-key=" key
Specifies the hashing key as an integer. Note that if you want to
The default key is
.BR 0xe07e5bd1 ,
which is, as far as the author knows, as good as any other fixed value.
-.TP
+.
+.\"--------------------------------------------------------------------------
.SH "SEE ALSO"
+.
.BR crc-mktab (1),
.BR unihash (3).
+.
+.\"--------------------------------------------------------------------------
.SH "AUTHOR"
+.
Mark Wooding, <mdw@distorted.org.uk>
+.
+.\"----- That's all, folks --------------------------------------------------
.\" -*-nroff-*-
-.de VS
-.sp 1
-.RS
-.nf
-.ft B
-..
-.de VE
-.ft R
-.fi
-.RE
-.sp 1
-..
-.de hP
-.IP
-.ft B
-\h'-\w'\\$1\ 'u'\\$1\ \c
-.ft P
-..
-.ie t \{\
-. ds ss \s8\u
-. ds se \d\s0
-. ds us \s8\d
-. ds ue \u\s0
-. ds *d \(*d
-. ds >= \(>=
-.\}
-.el \{\
-. ds ss ^
-. ds se
-. ds us _
-. ds ue
-. ds *d \fIdelta\fP
-. ds >= >=
-.\}
-.TH unihash 3 "5 July 2003" "Straylight/Edgeware" "mLib utilities library"
-.SH NAME
-unihash \- simple and efficient universal hashing for hashtables
+.\"
+.\" Manual for universal hashing
+.\"
+.\" (c) 2003, 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 unihash 3mLib "5 July 2003" "Straylight/Edgeware" "mLib utilities library"
.\" @unihash_setkey
.\" @UNIHASH_INIT
.\" @unihash_hash
.\" @UNIHASH
.\" @unihash
+.
+.\"--------------------------------------------------------------------------
+.SH NAME
+unihash \- simple and efficient universal hashing for hashtables
+.
+.\"--------------------------------------------------------------------------
.SH SYNOPSIS
+.
.nf
.B "#include <mLib/unihash.h>"
.PP
.BI "uint32 unihash(const unihash_info *" i ", const void *" p ", size_t " sz );
.BI "uint32 UNIHASH(const unihash_info *" i ", const void *" p ", size_t " sz );
.fi
+.
+.\"--------------------------------------------------------------------------
.SH DESCRIPTION
The
.B unihash
\- in addition to the data to be hashed, the function takes as input a
32-bit key. This key should be chosen at random each time the program
runs.
+.
.SS "Preprocessing a key"
Before use, a key must be
.I preprocessed
don't contain any pointers to other data and are safe to free when
you've finished with them; or you can just allocate them statically or
on the stack if that's more convenient.
+.
.SS "Hashing data"
The function
.B unihash_hash
are convenient interfaces to
.B unihash_hash
if you only wanted to hash one chunk.
+.
.SS "Global hash info table"
There's no problem with using the same key for several purposes, as long
as it's secret from all of your adversaries. Therefore, there is a
.I before
it gets used to hash any data (otherwise your hash tables will become
messed up).
+.
.SS "Theoretical issues"
The hash function implemented by
.B unihash
dependent on any unproven assumptions (unlike many `proofs' of
cryptographic security, which actually reduce the security of some
construction to the security of its components). It's just a fact.
+.
+.\"--------------------------------------------------------------------------
.SH SEE ALSO
+.
.BR unihash-mkstatic (3),
.BR crc32 (3),
.BR mLib (3).
+.
+.\"--------------------------------------------------------------------------
.SH AUTHOR
+.
Mark Wooding (mdw@distorted.org.uk).
+.
+.\"----- That's all, folks --------------------------------------------------
.\" -*-nroff-*-
-.TH mLib 3 "7 July 1999" "Straylight/Edgeware" "mLib utilities library"
+.\"
+.\" mLib overview
+.\"
+.\" (c) 1999--2001, 2003, 2005, 2007, 2009, 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 mLib 3mLib "7 July 1999" "Straylight/Edgeware" "mLib utilities library"
+.\" @mLib
+.
+.\"--------------------------------------------------------------------------
.SH NAME
mLib \- library of miscellaneous utilities
-.\" @mLib
+.
+.\"--------------------------------------------------------------------------
.SH DESCRIPTION
+.
The
.B mLib
library is a mixed bag of things which the author finds useful in large
Even so, it's not too bad a model really.
.PP
The rest of this section describes the various chunks and layers.
+.
.SS "Exception handling"
Right at the bottom, there's a fairly primitive exception handling
system. It's provided by the
.BR exc (3)
module, and stands alone. It's used mainly by the memory allocation
modules to raise exceptions when there's no more memory to be had.
+.
.SS "Memory allocation"
The
.BR arena (3)
module maintains resource pools which can manage memory and other
resources, all of the resources held in a pool being destroyed along
with the pool itself.
+.
.SS "String handling"
The
.BR str (3)
module implements a `pool' of dynamic strings which saves lots of
allocation and deallocation when a piece of code has high string
turnover.
+.
.SS "Program identification and error reporting"
The
.BR quis (3)
module provides an interface for emitting tracing information with
configurable verbosity levels. It needs improving to be able to cope
with outputting to the system log.
+.
.SS "Other data types"
The
.BR hash (3)
.BR darray (3)
module implements dynamically resizing arrays which support Perl-like
stack operations efficiently.
+.
.SS "Miscellaneous utilities"
The
.BR crc32 (3)
module provides a generic structure for reading test vectors from files
and running them through functions. I mainly use it for testing
cryptographic transformations of various kinds.
+.
.SS "Encoding and decoding"
The
.BR base64 (3)
module does urlencoding and decoding, as defined in RFC1866.
Urlencoding encodes arbitrary (but mostly text-like) name/value pairs as
a text string containing no whitespace.
+.
.SS "Multiplexed I/O"
The
.BR sel (3)
module provides a nonblocking ident (RFC931) client. The
.BR bres (3)
module does background hostname and address resolution.
+.
+.\"--------------------------------------------------------------------------
.SH "SEE ALSO"
+.
.BR alloc (3),
.BR assoc (3),
.BR atom (3),
.BR trace (3),
.BR tv (3),
.BR url (3).
+.
+.\"--------------------------------------------------------------------------
.SH AUTHOR
+.
Mark Wooding, <mdw@distorted.org.uk>
+.
+.\"----- That's all, folks --------------------------------------------------
## Arena abstraction.
pkginclude_HEADERS += arena.h
libmem_la_SOURCES += arena.c
+EXTRA_DIST += arena.3.in
LIBMANS += arena.3
## Memory allocation with exceptions.
pkginclude_HEADERS += alloc.h
libmem_la_SOURCES += alloc.c
+EXTRA_DIST += alloc.3.in
LIBMANS += alloc.3
## Buffer extension.
pkginclude_HEADERS += growbuf.h
+EXTRA_DIST += growbuf.3.in
LIBMANS += growbuf.3
## Slab allocator.
pkginclude_HEADERS += sub.h
libmem_la_SOURCES += sub.c
+EXTRA_DIST += sub.3.in
LIBMANS += sub.3
## Pool allocator.
pkginclude_HEADERS += pool.h
libmem_la_SOURCES += pool.c pool-file.c pool-sub.c
+EXTRA_DIST += pool.3.in
LIBMANS += pool.3
###----- That's all, folks --------------------------------------------------
+++ /dev/null
-.\" -*-nroff-*-
-.TH alloc 3 "8 May 1999" "Straylight/Edgeware" "mLib utilities library"
-.\" @xmalloc
-.\" @xrealloc
-.\" @xstrdup
-.\" @xfree
-.\" @x_alloc
-.\" @x_strdup
-.\" @x_realloc
-.\" @x_free
-.SH NAME
-alloc \- mLib low-level memory allocation
-.SH SYNOPSIS
-.nf
-.B "#include <mLib/alloc.h>"
-.PP
-.BI "void *x_alloc(arena *" a ", size_t " sz );
-.BI "char *x_strdup(arena *" a ", const char *" s );
-.BI "void *x_realloc(arena *" a ", void *" p ", size_t " sz ", size_t " osz );
-.BI "void x_free(arena *" a ", void *" p );
-.PP
-.BI "void *xmalloc(size_t " sz );
-.BI "void *xrealloc(void *" p ", size_t " sz ", size_t " osz );
-.BI "char *xstrdup(const char *" s );
-.BI "void xfree(void *" p );
-.fi
-.SH DESCRIPTION
-These functions allocate and return blocks of memory. If insufficient
-memory is available, an
-.B EXC_NOMEM
-exception is raised.
-.PP
-The functions
-.BR x_alloc ,
-.BR x_realloc ,
-.BR x_strdup
-and
-.BR x_free
-work with a given arena (see
-.BR arena (3)).
-.B x_alloc
-allocates a block of a given size;
-.B x_realloc
-resizes an allocated block;
-.B x_strdup
-allocates a copy of a null-terminated string; and
-.B x_free
-releases a block.
-.RB ( x_free
-is supplied for orthogonality's sake: it's equivalent to calling the
-.BR A_FREE (3)
-macro.)
-.PP
-The
-.BR xmalloc ,
-.BR xrealloc ,
-.BR xstrdup
-and
-.BR xfree
-macros are provided as a convenient interface to failsafe memory
-allocation from the current arena
-.BR arena_global (3).
-.SH "SEE ALSO"
-.BR arena (3),
-.BR exc (3),
-.BR mLib (3).
-.SH AUTHOR
-Mark Wooding, <mdw@distorted.org.uk>
--- /dev/null
+.\" -*-nroff-*-
+.\"
+.\" Manual for general memory allocation
+.\"
+.\" (c) 1999--2002, 2005, 2009, 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 alloc 3mLib "8 May 1999" "Straylight/Edgeware" "mLib utilities library"
+.\" @xmalloc
+.\" @xrealloc
+.\" @xstrdup
+.\" @xfree
+.\" @x_alloc
+.\" @x_strdup
+.\" @x_realloc
+.\" @x_free
+.
+.\"--------------------------------------------------------------------------
+.SH NAME
+alloc \- mLib low-level memory allocation
+.
+.\"--------------------------------------------------------------------------
+.SH SYNOPSIS
+.
+.nf
+.B "#include <mLib/alloc.h>"
+.PP
+.BI "void *x_alloc(arena *" a ", size_t " sz );
+.BI "char *x_strdup(arena *" a ", const char *" s );
+.BI "void *x_realloc(arena *" a ", void *" p ", size_t " sz ", size_t " osz );
+.BI "void x_free(arena *" a ", void *" p );
+.PP
+.BI "void *xmalloc(size_t " sz );
+.BI "void *xrealloc(void *" p ", size_t " sz ", size_t " osz );
+.BI "char *xstrdup(const char *" s );
+.BI "void xfree(void *" p );
+.fi
+.
+.\"--------------------------------------------------------------------------
+.SH DESCRIPTION
+.
+These functions allocate and return blocks of memory. If insufficient
+memory is available, an
+.B EXC_NOMEM
+exception is raised.
+.PP
+The functions
+.BR x_alloc ,
+.BR x_realloc ,
+.BR x_strdup
+and
+.BR x_free
+work with a given arena (see
+.BR arena (3)).
+.B x_alloc
+allocates a block of a given size;
+.B x_realloc
+resizes an allocated block;
+.B x_strdup
+allocates a copy of a null-terminated string; and
+.B x_free
+releases a block.
+.RB ( x_free
+is supplied for orthogonality's sake: it's equivalent to calling the
+.BR A_FREE (3)
+macro.)
+.PP
+The
+.BR xmalloc ,
+.BR xrealloc ,
+.BR xstrdup
+and
+.BR xfree
+macros are provided as a convenient interface to failsafe memory
+allocation from the current arena
+.BR arena_global (3).
+.
+.\"--------------------------------------------------------------------------
+.SH "SEE ALSO"
+.
+.BR arena (3),
+.BR exc (3),
+.BR mLib (3).
+.
+.\"--------------------------------------------------------------------------
+.SH AUTHOR
+.
+Mark Wooding, <mdw@distorted.org.uk>
+.
+.\"----- That's all, folks --------------------------------------------------
.\" -*-nroff-*-
-.TH arena 3 "3 June 2000" "Straylight/Edgeware" "mLib utilities library"
-.SH "NAME"
-arena \- control of memory allocation
+.\"
+.\" Manual for configurable memory management
+.\"
+.\" (c) 2000, 2001, 2005, 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 arena 3mLib "3 June 2000" "Straylight/Edgeware" "mLib utilities library"
.\" @arena_global
.\" @arena_stdlib
.\" @arena_fakemalloc
.\" @A_ALLOC
.\" @A_REALLOC
.\" @A_FREE
+.
+.\"--------------------------------------------------------------------------
+.SH "NAME"
+arena \- control of memory allocation
+.
+.\"--------------------------------------------------------------------------
.SH "SYNOPSIS"
+.
.nf
.B "#include <mLib/arena.h>"
.PP
.BI "void *A_REALLOC(arena *" a ", void *" p ", size_t " sz ", size_t " osz );
.BI "void A_FREE(arena *" a );
.fi
+.
+.\"--------------------------------------------------------------------------
.SH "DESCRIPTION"
+.
An
.I arena
is a place from which blocks of memory may be allocated and freed. The
specifying the old size of the block. This is for the benefit of arena
handlers which can't easily find the old block's size.
.PP
+.
.SS "Defining new arenas"
An
.B arena
.I free
calls with respect to null pointers and zero-sized blocks is as
specified by the ANSI C standard.
+.
+.\"--------------------------------------------------------------------------
.SH "SEE ALSO"
+.
.BR alloc (3),
.BR mLib (3).
+.
+.\"--------------------------------------------------------------------------
.SH AUTHOR
+.
Mark Wooding, <mdw@distorted.org.uk>
+.
+.\"----- That's all, folks --------------------------------------------------
.\" -*-nroff-*-
-.TH growbuf 3 "9 March 2024" "Straylight/Edgeware" "mLib utilities library"
+.\"
+.\" Manual for buffer extension
+.\"
+.\" (c) 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 growbuf 3mLib "9 March 2024" "Straylight/Edgeware" "mLib utilities library"
.\" @GROWBUF_SIZE
.\" @GROWBUF_EXTEND
.\" @GROWBUF_REPLACE
.
+.\"--------------------------------------------------------------------------
.SH NAME
growbuf \- extend buffers efficiently
.
+.\"--------------------------------------------------------------------------
.SH SYNOPSIS
+.
.nf
.B "#include <mLib/growbuf.h>"
.PP
.BI "\h'\w'\*(mT'u'size_t " init ", size_t " granule ");"
.fi
.
+.\"--------------------------------------------------------------------------
.SH DESCRIPTION
+.
The
.B "<mLib/growbuf.h>"
header file defines macros useful for dynamically resizing buffers.
.I discards
the existing buffer contents if the buffer needs to be adjusted.
.
+.\"--------------------------------------------------------------------------
.SH "SEE ALSO"
+.
.BR arena (3),
.BR mLib (3).
.
+.\"--------------------------------------------------------------------------
.SH AUTHOR
+.
Mark Wooding, <mdw@distorted.org.uk>
+.
+.\"----- That's all, folks --------------------------------------------------
.\" -*-nroff-*-
-.de VS
-.sp 1
-.RS
-.nf
-.ft B
-..
-.de VE
-.ft R
-.fi
-.RE
-.sp 1
-..
-.TH pool 3 "7 July 2000" "Straylight/Edgeware" "mLib utilities library"
-.SH "NAME"
-pool \- resource pool management
+.\"
+.\" Manual for resource pools
+.\"
+.\" (c) 2000, 2001, 2003, 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 pool 3mLib "7 July 2000" "Straylight/Edgeware" "mLib utilities library"
.\" @pool_alloc
.\" @pool_strdup
.\" @pool_init
.\" @pool_fopen
.\" @pool_fclose
.\" @pool_subarena
+.
+.\"--------------------------------------------------------------------------
+.SH "NAME"
+pool \- resource pool management
+.
+.\"--------------------------------------------------------------------------
.SH "SYNOPSIS"
+.
.nf
.B "#include <mLib/pool.h>"
.PP
.BI "void POOL_ADD(pool *" p ", pool_resource *" r ,
.BI " void (*" dfn ")(pool_resource *" r ));
.fi
+.
+.\"--------------------------------------------------------------------------
.SH "DESCRIPTION"
+.
.SS "Overview"
A
.I "resource pool"
will automatically release any resources it has when it's destroyed.
Attaching resources to an appropriate pool can therefore be a useful way
of avoiding memory leaks.
+.
.SS "Creating and destroying pools"
A new root pool is created using
.BR pool_create ,
.BR pool_init ,
on the other hand, are
allocated from a parent pool, and may be reused after being `destroyed'.
+.
.SS "Memory allocation"
Memory is allocated from a pool by calling
.BR pool_alloc ,
.BR p->a ,
which can be passed to other components to cause them to use the pool
for memory allocation.
+.
.SS "Other resources"
Pool resources have a header of type
.B pool_resource
which will ensure that it doesn't get closed twice by accident. It's
advisable to close files by hand, to prevent the process from running
out; it's just not a disaster if you forget by accident.
+.
+.\"--------------------------------------------------------------------------
.SH "SEE ALSO"
+.
.BR alloc (3),
.BR arena (3),
.BR mLib (3),
-.BR subarena (3).
+.BR sub (3).
+.
+.\"--------------------------------------------------------------------------
.SH AUTHOR
+.
Mark Wooding, <mdw@distorted.org.uk>
+.
+.\"----- That's all, folks --------------------------------------------------
.\" -*-nroff-*-
-.de VS
-.sp 1
-.RS
-.nf
-.ft B
-..
-.de VE
-.ft R
-.fi
-.RE
-.sp 1
-..
-.TH sub 3 "8 May 1999" "Straylight/Edgeware" "mLib utilities library"
-.SH NAME
-sub \- efficient allocation and freeing of small blocks
+.\"
+.\" Manual for efficient small-block allocation
+.\"
+.\" (c) 1999, 2001, 2003, 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 sub 3mLib "8 May 1999" "Straylight/Edgeware" "mLib utilities library"
.\" @subarena_create
.\" @subarena_destroy
.\" @subarena_alloc
.\" @sub_alloc
.\" @sub_free
.\" @sub_init
-.\"
+.
.\" @A_CREATE
.\" @A_DESTROY
.\" @CREATE
.\" @DESTROY
-.\"
+.
+.\"--------------------------------------------------------------------------
+.SH NAME
+sub \- efficient allocation and freeing of small blocks
+.
+.\"--------------------------------------------------------------------------
.SH SYNOPSIS
+.
.nf
.B "#include <mLib/sub.h>"
.PP
.BI "void *CREATE(" type );
.BI "void DESTROY(" type " *" p );
.fi
+.
+.\"--------------------------------------------------------------------------
.SH DESCRIPTION
+.
The
.B subarena
collection of functions and macros implement an efficient allocator for
ought to be called before any of the other functions as a matter of good
taste, but actually the system will initialize itself the first time
it's used.
+.
+.\"--------------------------------------------------------------------------
.SH "SEE ALSO"
+.
.BR arena (3),
.BR exc (3),
.BR alloc (3),
.BR mLib (3).
+.
+.\"--------------------------------------------------------------------------
.SH AUTHOR
+.
Mark Wooding, <mdw@distorted.org.uk>
+.
+.\"----- That's all, folks --------------------------------------------------
## Core event selection.
pkginclude_HEADERS += sel.h
libsel_la_SOURCES += sel.c
+EXTRA_DIST += sel.3.in
LIBMANS += sel.3
## Waiting for buffers to fill.
pkginclude_HEADERS += selbuf.h selpk.h
libsel_la_SOURCES += selbuf.c selpk.c
+EXTRA_DIST += selbuf.3.in selpk.3.in
LIBMANS += selbuf.3 selpk.3
## RFC931 identification.
pkginclude_HEADERS += ident.h
libsel_la_SOURCES += ident.c
+EXTRA_DIST += ident.3.in
LIBMANS += ident.3
## Nonblocking connections.
pkginclude_HEADERS += conn.h
libsel_la_SOURCES += conn.c
+EXTRA_DIST += conn.3.in
LIBMANS += conn.3
## Signal handling
pkginclude_HEADERS += sig.h
libsel_la_SOURCES += sig.c
+EXTRA_DIST += sig.3.in
LIBMANS += sig.3
## Name resolution.
pkginclude_HEADERS += bres.h
+EXTRA_DIST += bres.3.in
LIBMANS += bres.3
if WITH_ADNS
.\" -*-nroff-*-
-.TH bres 3 "1 October 1999" "Straylight/Edgeware" "mLib utilities library"
-.SH NAME
-bres \- background name resolver
+.\"
+.\" Manual for background name resolution
+.\"
+.\" (c) 1999, 2001, 2003, 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 bres 3mLib "1 October 1999" "Straylight/Edgeware" "mLib utilities library"
.\" @bres_abort
.\" @bres_byname
.\" @bres_byaddr
.\" @bres_exec
.\" @bres_init
+.
+.\"--------------------------------------------------------------------------
+.SH NAME
+bres \- background name resolver
+.
+.\"--------------------------------------------------------------------------
.SH SYNOPSIS
+.
.nf
.B "#include <mLib/bres.h>"
.PP
.BI "void bres_exec(const char *" file );
.BI "void bres_init(sel_state *" sel );
.fi
+.
+.\"--------------------------------------------------------------------------
.SH DESCRIPTION
+.
The
.B bres.h
header file declares types and functions for doing translation between
For security reasons, when an address is resolved, the hostname received
is verified by performing a forward lookup. If the forward lookup fails
to return the expected IP address, an error is reported.
+.
+.\"--------------------------------------------------------------------------
.SH "SEE ALSO"
+.
.BR gethostbyname (3),
.BR gethostbyaddr (3),
.BR sel (3),
.BR mLib (3).
+.
+.\"--------------------------------------------------------------------------
.SH "AUTHOR"
+.
Mark Wooding, <mdw@distorted.org.uk>
+.
+.\"----- That's all, folks --------------------------------------------------
.\" -*-nroff-*-
-.TH conn 3 "23 May 1999" "Straylight/Edgeware" "mLib utilities library"
+.\"
+.\" Manual for asynchronous connection
+.\"
+.\" (c) 1999, 2001--2003, 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 conn 3mLib "23 May 1999" "Straylight/Edgeware" "mLib utilities library"
.\" @conn_fd
.\" @conn_init
.\" @conn_kill
+.
+.\"--------------------------------------------------------------------------
.SH NAME
conn \- selector for nonblocking connections
+.
+.\"--------------------------------------------------------------------------
.SH SYNOPSIS
+.
.nf
.B "#include <mLib/conn.h>"
.PP
.PP
.BI "void conn_kill(conn *" c );
.fi
+.
+.\"--------------------------------------------------------------------------
.SH DESCRIPTION
+.
The
.B conn
selector manages a nonblocking connection to a remote socket. The
.B conn_kill
with the address of the selector. The file descriptor is closed, and
the selector becomes safe to be discarded.
+.
+.\"--------------------------------------------------------------------------
.SH "SEE ALSO"
+.
.BR connect (2),
.BR sel (3),
.BR mLib (3).
+.
+.\"--------------------------------------------------------------------------
.SH AUTHOR
+.
Mark Wooding, <mdw@distorted.org.uk>
+.
+.\"----- That's all, folks --------------------------------------------------
.\" -*-nroff-*-
-.TH ident 3 "2 October 1999" "Straylight/Edgeware" "mLib utilities library"
-.SH "NAME"
-ident \- identd (RFC931) client
+.\"
+.\" Manual for RFC931 client
+.\"
+.\" (c) 1999, 2001, 2005, 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 ident 3mLib "2 October 1999" "Straylight/Edgeware" "mLib utilities library"
.\" @ident_abort
.\" @ident
.\" @ident_socket
+.
+.\"--------------------------------------------------------------------------
+.SH "NAME"
+ident \- identd (RFC931) client
+.
+.\"--------------------------------------------------------------------------
.SH "SYNOPSIS"
+.
.nf
.B "#include <mLib/ident>"
.PP
.BI " void (*" func ")(ident_reply *" i ", void *" p ),
.BI " void *" p );
.fi
+.
+.\"--------------------------------------------------------------------------
.SH "DESCRIPTION"
+.
The
.B ident.h
header defines some types and functions which implement an ident client
.B ident_abort
on the request block. In this case, no notification is made to the
handler function.
+.
+.\"--------------------------------------------------------------------------
.SH "SEE ALSO"
+.
.BR sel (3),
.BR mLib (3).
+.
+.\"--------------------------------------------------------------------------
.SH "AUTHOR"
+.
Mark Wooding, <mdw@distorted.org.uk>
+.
+.\"----- That's all, folks --------------------------------------------------
.\" -*-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
.\" @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
.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
.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
.BR selbuf (3)
and
.BR conn (3).
+.
+.\"--------------------------------------------------------------------------
.SH "PROGRAMMING INTERFACE"
+.
.SS "Multiplexors"
A multiplexor is represented using the type
.B sel_state
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
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
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
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
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)
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 --------------------------------------------------
.\" -*-nroff-*-
-.TH selbuf 3 "23 May 1999" "Straylight/Edgeware" "mLib utilities library"
-.SH NAME
-selbuf \- line-buffering input selector
+.\"
+.\" Manual for event-driven line buffer
+.\"
+.\" (c) 1999--2002, 2005, 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 selbuf 3mLib "23 May 1999" "Straylight/Edgeware" "mLib utilities library"
.\" @selbuf_enable
.\" @selbuf_disable
.\" @selbuf_setsize
.\" @selbuf_init
.\" @selbuf_destroy
+.
+.\"--------------------------------------------------------------------------
+.SH NAME
+selbuf \- line-buffering input selector
+.
+.\"--------------------------------------------------------------------------
.SH SYNOPSIS
+.
.nf
.B "#include <mLib/selbuf.h>"
.PP
.BI " lbuf_func *" func ", void *" p );
.BI "void selbuf_destroy(selbuf *" b );
.fi
+.
+.\"--------------------------------------------------------------------------
.SH DESCRIPTION
The
.B selbuf
When it's finished with, a line buffer selector must be destroyed by
calling
.BR selbuf_destroy .
+.
+.\"--------------------------------------------------------------------------
.SH "SEE ALSO"
+.
.BR lbuf (3),
.BR sel (3),
.BR mLib (3).
+.
+.\"--------------------------------------------------------------------------
.SH AUTHOR
+.
Mark Wooding, <mdw@distorted.org.uk>
+.
+.\"----- That's all, folks --------------------------------------------------
.\" -*-nroff-*-
-.TH selpk 3 "23 May 1999" "Straylight/Edgeware" "mLib utilities library"
-.SH NAME
-selpk \- packet-buffering input selector
+.\"
+.\" Manual for event-driven packet splitting
+.\"
+.\" (c) 2000--2003, 2005, 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 selpk 3mLib "23 May 1999" "Straylight/Edgeware" "mLib utilities library"
.\" @selpk_enable
.\" @selpk_disable
.\" @selpk_want
.\" @selpk_init
.\" @selpk_destroy
+.
+.\"--------------------------------------------------------------------------
+.SH NAME
+selpk \- packet-buffering input selector
+.
.SH SYNOPSIS
.nf
.B "#include <mLib/selpk.h>"
.BI " pkbuf_func *" func ", void *" p );
.BI "void selpk_destroy(selpk *" b );
.fi
+.
+.\"--------------------------------------------------------------------------
.SH DESCRIPTION
+.
The
.B selpk
subsystem is a selector which integrates with the
.PP
When it's finished with, a packet selector must be destroyed by calling
.BR selpk_destroy .
+.
+.\"--------------------------------------------------------------------------
.SH "SEE ALSO"
+.
.BR pkbuf (3),
.BR sel (3),
.BR selbuf (3),
.BR mLib (3).
+.
+.\"--------------------------------------------------------------------------
.SH AUTHOR
+.
Mark Wooding, <mdw@distorted.org.uk>
+.
+.\"----- That's all, folks --------------------------------------------------
.\" -*-nroff-*-
-.TH sel 3 "23 July 1999" "Straylight/Edgeware" "mLib utilities library"
-.SH NAME
-sig \- more controlled signal handling
+.\"
+.\" Manual for in-band signal handling
+.\"
+.\" (c) 1999, 2001, 2005, 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 "23 July 1999" "Straylight/Edgeware" "mLib utilities library"
.\" @sig_init
.\" @sig_add
.\" @sig_remove
+.
+.\"--------------------------------------------------------------------------
+.SH NAME
+sig \- more controlled signal handling
+.
+.\"--------------------------------------------------------------------------
.SH SYNOPSIS
+.
.nf
.B "#include <mLib/sig.h>"
.PP
.BI "void sig_remove(sig *" s );
.BI "void sig_init(sel_state *" s );
.fi
+.
+.\"--------------------------------------------------------------------------
.SH "DESCRIPTION"
+.
The
.B sig
subsystem uses the I/O multiplexing capabilities of
.B sig
structure you passed to
.BR sig_add .
+.
.SS "Multiple signal handlers"
You may have multiple signal handlers for a signal. All of them are
called in some unspecified order when the signal occurs.
there are no handlers already registered. When the last handler for a
signal is removed, its disposition is restored to its initial remembered
state.
+.
+.\"--------------------------------------------------------------------------
.SH "BUGS AND CAVEATS"
+.
The
.B sig
system attempts to set the
.B SA_NOCLDSTOP
flag is also set, so that stopped child processes aren't reported by a
signal. This is normally right, but ought to be configurable.
+.
+.\"--------------------------------------------------------------------------
+.SH "SEE ALSO"
+.
+.BR signal (2),
+.BR sel (3),
+.BR mLib (3).
+.
+.\"--------------------------------------------------------------------------
.SH "AUTHOR"
+.
Mark Wooding, <mdw@distorted.org.uk>
+.
+.\"----- That's all, folks --------------------------------------------------
## Dynamic strings.
pkginclude_HEADERS += dstr.h dspool.h
libstruct_la_SOURCES += dstr.c dstr-putf.c dspool.c
+EXTRA_DIST += dstr.3.in dspool.3.in
LIBMANS += dstr.3 dspool.3
check_PROGRAMS += t/dstr-putf.t
## Buffers.
pkginclude_HEADERS += buf.h
libstruct_la_SOURCES += buf.c buf-dstr.c buf-float.c buf-putf.c
+EXTRA_DIST += buf.3.in
LIBMANS += buf.3
## Dynamic arrays.
pkginclude_HEADERS += darray.h
libstruct_la_SOURCES += darray.c
+EXTRA_DIST += darray.3.in
LIBMANS += darray.3
check_PROGRAMS += t/darray.t
## Hash tables.
pkginclude_HEADERS += hash.h
libstruct_la_SOURCES += hash.c
+EXTRA_DIST += hash.3.in
LIBMANS += hash.3
## Symbol tables.
pkginclude_HEADERS += sym.h
libstruct_la_SOURCES += sym.c
+EXTRA_DIST += sym.3.in
LIBMANS += sym.3
check_PROGRAMS += t/sym.t
## Atoms.
pkginclude_HEADERS += atom.h
libstruct_la_SOURCES += atom.c
+EXTRA_DIST += atom.3.in
LIBMANS += atom.3
## Association tables.
pkginclude_HEADERS += assoc.h
libstruct_la_SOURCES += assoc.c
+EXTRA_DIST += assoc.3.in
LIBMANS += assoc.3
check_PROGRAMS += t/assoc.t
.\" -*-nroff-*-
-.de VS
-.sp 1
-.RS
-.nf
-.ft B
-..
-.de VE
-.ft R
-.fi
-.RE
-.sp 1
-..
-.TH assoc 3 "23 January 2001" "Straylight/Edgeware" "mLib utilities library"
-.SH NAME
-assoc \- tables indexed by atoms
+.\"
+.\" Manual for association tables based on atoms
+.\"
+.\" (c) 2001, 2005, 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 assoc 3mLib "23 January 2001" "Straylight/Edgeware" "mLib utilities library"
.\" @assoc_create
.\" @assoc_destroy
.\" @assoc_find
.\" @assoc_remove
.\" @assoc_mkiter
.\" @assoc_next
-.\"
+.
.\" @ASSOC_ATOM
-.\"
+.
+.\"--------------------------------------------------------------------------
+.SH NAME
+assoc \- tables indexed by atoms
+.
+.\"--------------------------------------------------------------------------
.SH SYNOPSIS
+.
.nf
.B "#include <mLib/assoc.h>"
.PP
.BI "void assoc_mkiter(assoc_iter *" i ", assoc_table *" t );
.BI "void *assoc_next(assoc_iter *" i );
.fi
+.
+.\"--------------------------------------------------------------------------
.SH DESCRIPTION
+.
An
.I "association table"
is a data structure which maps atoms (see
All of the above structures should be considered
.IR opaque :
don't try looking inside.
+.
.SS "Creation and destruction"
The
.B assoc_table
.BR assoc_destroy .
Any bits of user data attached to values should previously have been
destroyed.
+.
.SS "Adding, searching and removing"
Most of the actual work is done by the function
.BR assoc_find .
.BR assoc_remove ,
passing the association table itself, and the value block that needs
removing.
+.
.SS "Enquiries about associations"
Given a pointer
.I a
to an association, the expression
.BI ASSOC_ATOM( a )
has as its value a poinetr to the atom which is that association's key.
+.
.SS "Enumerating associations"
Enumerating the values in an association table is fairly simple.
Allocate an
.PP
When you've finished with an iterator, it's safe to just throw it away.
You don't need to call any functions beforehand.
+.
+.\"--------------------------------------------------------------------------
.SH SEE ALSO
+.
.BR atom (3),
.BR hash (3),
.BR sym (3),
.BR mLib (3).
+.
+.\"--------------------------------------------------------------------------
.SH AUTHOR
+.
Mark Wooding, <mdw@distorted.org.uk>
+.
+.\"----- That's all, folks --------------------------------------------------
.\" -*-nroff-*-
-.de VS
-.sp 1
-.RS
-.nf
-.ft B
-..
-.de VE
-.ft R
-.fi
-.RE
-.sp 1
-..
-.TH atom 3 "21 January 2001" "Straylight/Edgeware" "mLib utilities library"
-.SH NAME
-atom \- atom table manager
+.\"
+.\" Manual for atom interning
+.\"
+.\" (c) 2001, 2005, 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 atom 3mLib "21 January 2001" "Straylight/Edgeware" "mLib utilities library"
.\" @atom_createtable
.\" @atom_destroytable
.\" @atom_intern
.\" @atom_hash
.\" @atom_mkiter
.\" @atom_next
-.\"
+.
.\" @ATOM_GLOBAL
.\" @INTERN
.\" @GENSYM
.\" @ATOM_NAME
.\" @ATOM_LEN
.\" @ATOM_HASH
-.\"
+.
+.\"--------------------------------------------------------------------------
+.SH NAME
+atom \- atom table manager
+.
.SH SYNOPSIS
+.
.nf
.B "#include <mLib/atom.h>"
.PP
.PP
.BI "extern atom_table *ATOM_GLOBAL;"
.fi
+.
+.\"--------------------------------------------------------------------------
.SH DESCRIPTION
The
.B atom
.B atom_createtable
and free it when you're finished using
.BR atom_destroytable .
+.
.SS "Creating atoms from strings"
The process of making atoms from strings is called
.IR interning .
the atom's length as reported by the
.B ATOM_LEN
macro.
+.
.SS "Uninterned atoms"
You can make an atom which is guaranteed to be distinct from every other
atom, and has no sensible text string, by calling
is an atom-table-specific sequence number. This text is there as a
debugging convenience, and doesn't mean that the uninterned atom has the
same address as an interned atom with the same text.
+.
.SS "Other enquiries about atoms"
Atoms can be interrogated to find their names and hashes. The macro
.B ATOM_NAME
atom as a key in some other structure. There are lower-case function
versions of these, which have the same effect. There is little point in
using the functions.
+.
.SS "Enumerating atoms"
You can iterate over the atoms in an atom table. The
.B atom_mkiter
.B atom_next
returns the next atom from the iterator. Atoms are not returned in any
particular order.
+.
+.\"--------------------------------------------------------------------------
.SH SEE ALSO
+.
.BR assoc (3),
.BR hash (3),
.BR mLib (3).
+.
+.\"--------------------------------------------------------------------------
.SH AUTHOR
+.
Mark Wooding, <mdw@distorted.org.uk>
+.
+.\"----- That's all, folks --------------------------------------------------
.\" -*-nroff-*-
-.de VS
-.sp 1
-.RS
-.nf
-.ft B
-..
-.de VE
-.ft R
-.fi
-.RE
-.sp 1
-..
-.de hP
-.IP
-.ft B
-\h'-\w'\\$1\ 'u'\\$1\ \c
-.ft P
-..
-.ie t .ds o \(bu
-.el .ds o o
+.\"
+.\" Manual for buffer handling
+.\"
+.\" (c) 2005, 2007, 2009, 2017, 2023, 2024 Straylight/Edgeware
+.\"
.
-.TH buf 3 "23 September 2005" "Straylight/Edgeware" "mLib utilities library"
+.\"----- 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.
.
-.SH NAME
-buf \- reading and writing stuff in buffers
+.\"--------------------------------------------------------------------------
+.so ../defs.man \" @@@PRE@@@
+.
+.\"--------------------------------------------------------------------------
+.TH buf 3mLib "23 September 2005" "Straylight/Edgeware" "mLib utilities library"
.\" @BBASE
.\" @BLIM
.\" @BCUR
.\" @buf_vputstrf
.\" @dbuf_putstrf
.\" @dbuf_vputstrf
+.\" @buf_printops
.
.\" @buf_getu8
.\" @buf_getu16
.\" @DBUF_ENCLOSE64_B
.\" @DBUF_ENCLOSEZ
.
+.\"--------------------------------------------------------------------------
+.SH NAME
+buf \- reading and writing stuff in buffers
+.
+.\"--------------------------------------------------------------------------
.SH SYNOPSIS
+.
.nf
.B "#include <mLib/dstr.h>"
.PP
.BI "int dbuf_getf" suff "(dbuf *" db ", double *" x );
.fi
.
+.\"--------------------------------------------------------------------------
.SH DESCRIPTION
The
.B buf
Both functions return the number of bytes written on success
or \-1 on failure.
Note that these functions apply no length framing or termination.
+They are implemented using
+.BR gprintf (3);
+the output operations table is exposed as
+.BR buf_printops ;
+the functions expect the output pointer to be the address of the output
+.BR buf .
.PP
Functions which deal with block lengths assume the length is prefixed to
the data, and don't include themselves. They come in all of the integer
and also restore its current position to its base and
clear its broken flag.
.
+.\"--------------------------------------------------------------------------
.SH "SEE ALSO"
+.
.BR bits (3),
.BR control (3),
.BR dstr (3),
+.BR gprintf (3),
.BR mLib (3).
.
+.\"--------------------------------------------------------------------------
.SH AUTHOR
+.
Mark Wooding, <mdw@distorted.org.uk>
+.
+.\"----- That's all, folks --------------------------------------------------
.\" -*-nroff-*-
-.de VS
-.sp 1
-.RS
-.nf
-.ft B
-..
-.de VE
-.ft R
-.fi
-.RE
-.sp 1
-..
-.de hP
-.IP
-.ft B
-\h'-\w'\\$1\ 'u'\\$1\ \c
-.ft P
-..
-.ie t .ds o \(bu
-.el .ds o o
-.TH darray 3 "21 October 1999" "Straylight/Edgeware" "mLib utilities library"
-.SH "NAME"
-darray \- dense, dynamically resizing arrays
+.\"
+.\" Manual for dynamically growing arrays
+.\"
+.\" (c) 1999--2001, 2005, 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 darray 3mLib "21 October 1999" "Straylight/Edgeware" "mLib utilities library"
.\" @DA_INIT
.\" @DA_DECL
.\" @DA_CREATE
.\" @da_ensure
.\" @da_shunt
.\" @da_tidy
+.
+.\"--------------------------------------------------------------------------
+.SH "NAME"
+darray \- dense, dynamically resizing arrays
+.
+.\"--------------------------------------------------------------------------
.SH "SYNOPSIS"
+.
.nf
.B "#include <mLib/darray.h>"
.PP
.BI "void *da_shunt(da_base *" b ", void *" v ", size_t " sz ", size_t " n );
.BI "void *da_tidy(da_base *" b ", void *" v ", size_t " sz );
.fi
+.
+.\"--------------------------------------------------------------------------
.SH "DESCRIPTION"
+.
The
.B <mLib/darray.h>
header file declares a collection of types, macros and functions which
.PP
The macros described here may evaluate their arguments multiple times
unless otherwise specified.
+.
.SS "Creation and destruction"
Each element type must have its own array
type declared using the
Arrays may be disposed of using the
.B DA_DESTROY
macro, which again takes the address of the array.
+.
.SS "Storage allocation"
.PP
Space for new array elements may be reserved using the
accepts the address of an array. It reduces the length of the array to
zero. No storage is deallocated. Resetting arrays might not be a good
idea if the objects in the array are dynamically allocated.
+.
.SS "Accessing array elements"
If
.I a
unsigned (e.g., if it's based on
.BR DA_LEN ).
There are unsafe versions of both these macros too.
+.
.SS "Stack operations"
Dynamic arrays support Perl-like stack operations. Given an array
(pointer)
.B DA_LAST
are lvalues referring to the first and last elements in the array
respectively. They are unsafe if the array is empty.
+.
.SS "Low-level details"
This section describes low-level details of the dynamic array
implementation. You should try to avoid making use of this information
.TP
.B da_tidy
Reallocate the array to use the smallest amount of memory possible.
+.
+.\"--------------------------------------------------------------------------
.SH "SEE ALSO"
+.
.BR exc (3),
.BR mLib (3).
+.
+.\"--------------------------------------------------------------------------
.SH "AUTHOR"
+.
Mark Wooding, <mdw@distorted.org.uk>
+.
+.\"----- That's all, folks --------------------------------------------------
.\" -*-nroff-*-
-.de VS
-.sp 1
-.in +5n
-.ft B
-.nf
-..
-.de VE
-.ft R
-.in -5n
-.sp 1
-.fi
-..
-.TH dspool 3 "20 June 1999" "Straylight/Edgeware" "mLib utilities library"
-.SH NAME
-dspool \- pools of preallocated dynamic strings
+.\"
+.\" Manual for string pools
+.\"
+.\" (c) 1999, 2001, 2005, 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 dspool 3mLib "20 June 1999" "Straylight/Edgeware" "mLib utilities library"
.\" @dspool_create
.\" @dspool_destroy
.\" @dspool_get
.\" @dspool_put
-.\"
+.
.\" @DSGET
.\" @DSPUT
-.\"
+.
+.\"--------------------------------------------------------------------------
+.SH NAME
+dspool \- pools of preallocated dynamic strings
+.
+.\"--------------------------------------------------------------------------
.SH SYNOPSIS
+.
.nf
.B "#include <mLib/dspool.h>"
.PP
.BI "void DSGET(dspool *" p ", " d );
.BI "void DSPUT(dspool *" p ", dstr *" d );
.fi
+.
+.\"--------------------------------------------------------------------------
.SH DESCRIPTION
+.
A dynamic string pool maintains a collection of `spare' dynamic
strings. Some pieces of code require high turnover of strings, and
allocating and freeing them entails a large amount of overhead. A
is entirely equivalent to the function
.B dspool_put
except for improved performance.
+.
+.\"--------------------------------------------------------------------------
.SH CAVEATS
+.
The string pool allocator requires the suballocator (see
.BR sub (3)
for details). You must ensure that
.B sub_init
is called before any strings are allocated from a string pool.
+.
+.\"--------------------------------------------------------------------------
.SH SEE ALSO
+.
.BR dstr (3),
.BR sub (3),
.BR mLib (3).
+.
+.\"--------------------------------------------------------------------------
.SH AUTHOR
+.
Mark Wooding, <mdw@distorted.org.uk>
+.
+.\"----- That's all, folks --------------------------------------------------
.\" -*-nroff-*-
-.de VS
-.sp 1
-.RS
-.nf
-.ft B
-..
-.de VE
-.ft R
-.fi
-.RE
-.sp 1
-..
-.de hP
-.IP
-.ft B
-\h'-\w'\\$1\ 'u'\\$1\ \c
-.ft P
-..
-.ie t .ds o \(bu
-.el .ds o o
-.TH dstr 3 "8 May 1999" "Straylight/Edgeware" "mLib utilities library"
-.SH NAME
-dstr \- a simple dynamic string type
+.\"
+.\" Manual for dynamic strings
+.\"
+.\" (c) 1999--2003, 2005, 2007, 2009, 2013, 2014, 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 dstr 3mLib "8 May 1999" "Straylight/Edgeware" "mLib utilities library"
.\" @dstr_create
.\" @dstr_destroy
.\" @dstr_reset
.\" @dstr_ensure
.\" @dstr_tidy
-.\"
+.
.\" @dstr_putc
.\" @dstr_putz
.\" @dstr_puts
.\" @dstr_putf
+.\" @dstr_vputf
+.\" @dstr_printops
.\" @dstr_putd
.\" @dstr_putm
.\" @dstr_putline
.\" @dstr_write
-.\"
+.
.\" @DSTR_INIT
.\" @DCREATE
.\" @DDESTROY
.\" @DPUTD
.\" @DPUTM
.\" @DWRITE
-.\"
+.
+.\"--------------------------------------------------------------------------
+.SH NAME
+dstr \- a simple dynamic string type
+.
+.\"--------------------------------------------------------------------------
.SH SYNOPSIS
+.
.nf
.B "#include <mLib/dstr.h>"
.PP
.BI "void DPUTM(dstr *" d ", const void *" p ", size_t " sz );
.BI "size_t DWRITE(const dstr *" d ", FILE *" fp );
.fi
+.
+.\"--------------------------------------------------------------------------
.SH DESCRIPTION
+.
The header
.B dstr.h
declares a type for representing dynamically extending strings, and a
Many of the functions which act on dynamic strings have macro
equivalents. These equivalent macros may evaluate their arguments
multiple times.
+.
.SS "Underlying type"
A
.B dstr
.BR arena_stdlib (3);
you can set it to point to any other arena of your choice before the
buffer is allocated.
+.
.SS "Creation and destruction"
The caller is responsible for allocating the
.B dstr
which does the same job as the
.B dstr_reset
function.
+.
.SS "Extending a string"
All memory allocation for strings is done by the function
.BR dstr_ensure .
fail on reducing a block's size. Secondly, tidying an empty string with no
buffer allocated for it causes allocation of a buffer large enough for
the terminating null byte.)
+.
.SS "Contributing data to a string"
There are a collection of functions which add data to a string. All of
these functions add their new data to the
format string and an arbitrary number of arguments to format and writes
the resulting text to the end of a dynamic string, returning the number
of characters so written. A terminating zero byte is also appended.
-The formatting is intended to be convenient and safe rather than
-efficient, so don't expect blistering performance. Similarly, there may
-be differences between the formatting done by
-.B dstr_putf
-and
-.BR sprintf (3)
-because the former has to do most of its work itself. In particular,
-.B dstr_putf
-understands the POSIX
-.RB ` n$ '
-positional parameter notation accepted by many Unix C libraries, even if
-the underlying C library does not. There is no macro equivalent of
+There is no macro equivalent of
.BR dstr_putf .
.PP
The function
.BR va_list ,
so that it gets updated properly on exit.)
.PP
+The
+.B dstr_putf
+and
+.B dstr_vputf
+functions are implemented using
+.BR gprintf (3).
+The output operations table is exposed as
+.BR dstr_printops ;
+the functions expect the output pointer to be the address of the output
+.BR dstr
+.PP
The function
.B dstr_putd
appends the contents of one dynamic string to another. A null
.I not
inserted in the buffer. A terminating null is appended, as by
.BR dstr_putz .
+.
.SS "Other functions"
The
.B dstr_write
The macro
.B DWRITE
is equivalent.
+.
+.\"--------------------------------------------------------------------------
.SH "SECURITY CONSIDERATIONS"
+.
The implementation of the
.B dstr
functions is designed to do string handling in security-critical
.B dstr_putf
functions are quite complicated, and could do with some checking by
independent people who know what they're doing.
+.
+.\"--------------------------------------------------------------------------
.SH "SEE ALSO"
+.
.BR exc (3),
+.BR gprintf (3),
.BR mLib (3).
+.
+.\"--------------------------------------------------------------------------
.SH AUTHOR
+.
Mark Wooding, <mdw@distorted.org.uk>
+.
+.\"----- That's all, folks --------------------------------------------------
.\" -*-nroff-*-
-.de VS
-.sp 1
-.RS
-.nf
-.ft B
-..
-.de VE
-.ft R
-.fi
-.RE
-.sp 1
-..
-.de hP
-.IP
-.ft B
-\h'-\w'\\$1\ 'u'\\$1\ \c
-.ft P
-..
-.ie t \{\
-. ds o \(bu
-. de VP
-. sp .4v
-..
-\}
-.el \{\
-. ds o o
-. de VP
-. sp
-..
-\}
-.TH hash 3 "2 August 1999" "Straylight/Edgeware" "mLib utilities library"
-.SH "NAME"
-hash \- low-level hashtable implementation
+.\"
+.\" Manual for hash table framework
+.\"
+.\" (c) 1999, 2001, 2003, 2005, 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 hash 3mLib "2 August 1999" "Straylight/Edgeware" "mLib utilities library"
.\" @hash_create
.\" @hash_destroy
.\" @hash_bin
.\" @hash_remove
.\" @hash_mkiter
.\" @hash_next
-.\"
+.
.\" @HASH_BIN
.\" @HASH_MKITER
.\" @HASH_NEXT
-.\"
+.
+.\"--------------------------------------------------------------------------
+.SH "NAME"
+hash \- low-level hashtable implementation
+.
+.\"--------------------------------------------------------------------------
.SH "SYNOPSIS"
+.
.nf
.B "#include <mLib/hash.h>"
.PP
.BI "void HASH_MKITER(hash_iter *" i ", hash_table *" t );
.BI "void HASH_NEXT(hash_iter *" i ", " b );
.fi
+.
+.\"--------------------------------------------------------------------------
.SH "OVERVIEW"
+.
The
.B hash
functions provide the basis for an extensible hashtable implementation.
decisions. If you just want a prepackaged solution, see
.BR sym (3)
which provides one.
+.
+.\"--------------------------------------------------------------------------
.SH "IMPLEMENTATION DETAILS"
+.
Each item in the hashtable is assigned a 32-bit integer
.IR hash :
a number computed somehow from the item's data such that two items which
The hash for this item. This must be the full 32-bit hash for the
current item. It is used during hashtable expansion to determine which
bin an item should be moved to.
+.
+.\"--------------------------------------------------------------------------
.SH "FUNCTIONALITY PROVIDED"
+.
This section describes the functions and macros provided for building
hashtables. Code examples are given throughout. They assume the
following definitions:
source file
.B sym.c
presents a more realistic example, but is rather more complex.
+.
.SS "Initialization and finalization"
An empty hashtable is initialized by calling
.B hash_create
}
.VE
.sp -1
+.
.SS "Searching, adding and removing"
Items must be searched for and added by hand.
.PP
.B hash_remove
will unlink a given item from its bin list, after which point it is safe
to remove.
+.
.SS "Iteration"
Iteration allows code to be performed on all the items in a hashtable.
This is done using an
which is updated to contain the address of the next item.
.PP
The finalization code above contained an example of iteration.
+.
+.\"--------------------------------------------------------------------------
.SH "SEE ALSO"
+.
.BR sym (3),
.BR mLib (3).
+.
+.\"--------------------------------------------------------------------------
.SH "AUTHOR"
+.
Mark Wooding, <mdw@distorted.org.uk>
+.
+.\"----- That's all, folks --------------------------------------------------
.\" -*-nroff-*-
-.de VS
-.sp 1
-.RS
-.nf
-.ft B
-..
-.de VE
-.ft R
-.fi
-.RE
-.sp 1
-..
-.ie t \{\
-. de VP
-. sp .4v
-..
-\}
-.el \{\
-. de VP
-. sp
-..
-\}
-.TH sym 3 "8 May 1999" "Straylight/Edgeware" "mLib utilities library"
-.SH NAME
-sym \- symbol table manager
+.\"
+.\" Manual for symbol table
+.\"
+.\" (c) 1999, 2001, 2003, 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 sym 3mLib "8 May 1999" "Straylight/Edgeware" "mLib utilities library"
.\" @sym_create
.\" @sym_destroy
.\" @sym_find
.\" @sym_remove
.\" @sym_mkiter
.\" @sym_next
-.\"
+.
.\" @SYM_NAME
.\" @SYM_LEN
.\" @SYM_HASH
-.\"
+.
+.\"--------------------------------------------------------------------------
+.SH NAME
+sym \- symbol table manager
+.
+.\"--------------------------------------------------------------------------
.SH SYNOPSIS
+.
.nf
.B "#include <mLib/sym.h>"
.PP
.BI "void sym_mkiter(sym_iter *" i ", sym_table *" t );
.BI "void *sym_next(sym_iter *" i );
.fi
+.
+.\"--------------------------------------------------------------------------
.SH "DESCRIPTION"
+.
The
.B sym
functions implement a data structure often described as a dictionary, a
.IR opaque :
don't try looking inside. Representations have changed in the past, and
they may change again in the future.
+.
.SS "Creation and destruction"
The
.B sym_table
.BR sym_destroy .
Any bits of user data attached to values should previously have been
destroyed.
+.
.SS "Adding, searching and removing"
Most of the actual work is done by the function
.BR sym_find .
.BR sym_remove ,
passing the symbol table itself, and the value block that needs
removing.
+.
.SS "Enquiries about symbols"
Three macros are provided to enable simple enquiries about a symbol.
Given a pointer
returns a pointer to the symbol's name; and
.BI SYM_HASH( s )
returns the symbol's hash value.
+.
.SS "Enumerating symbols"
Enumerating the values in a symbol table is fairly simple. Allocate a
.B sym_iter
.PP
When you've finished with an iterator, it's safe to just throw it away.
You don't need to call any functions beforehand.
+.
.SS "Use in practice"
In normal use, the keys are simple strings (usually identifiers from
some language), and the values are nontrivial structures providing
}
.VE
That ought to be enough examples to be getting on with.
+.
.SS Implementation
The symbol table is an extensible hashtable, using the universal hash
function described in
(probably too short, actually). Every time a symbol is found, its block
is promoted to the front of its bin chain so it gets found faster next
time.
+.
+.\"--------------------------------------------------------------------------
.SH SEE ALSO
+.
.BR hash (3),
.BR mLib (3).
+.
+.\"--------------------------------------------------------------------------
.SH AUTHOR
+.
Mark Wooding, <mdw@distorted.org.uk>
+.
+.\"----- That's all, folks --------------------------------------------------
## Daemons.
pkginclude_HEADERS += daemonize.h
libsys_la_SOURCES += daemonize.c
+EXTRA_DIST += daemonize.3.in
LIBMANS += daemonize.3
## Environment variables.
pkginclude_HEADERS += env.h
libsys_la_SOURCES += env.c
+EXTRA_DIST += env.3.in
LIBMANS += env.3
## File and descriptor flags.
pkginclude_HEADERS += fdflags.h
libsys_la_SOURCES += fdflags.c
+EXTRA_DIST += fdflags.3.in
LIBMANS += fdflags.3
## File descriptor passing.
pkginclude_HEADERS += fdpass.h
libsys_la_SOURCES += fdpass.c
+EXTRA_DIST += fdpass.3.in
LIBMANS += fdpass.3
check_PROGRAMS += t/fdpass.t
## Watching files for modification.
pkginclude_HEADERS += fwatch.h
libsys_la_SOURCES += fwatch.c
+EXTRA_DIST += fwatch.3.in
LIBMANS += fwatch.3
## File locking.
pkginclude_HEADERS += lock.h
libsys_la_SOURCES += lock.c
+EXTRA_DIST += lock.3.in
LIBMANS += lock.3
## File descriptor juggling.
pkginclude_HEADERS += mdup.h
libsys_la_SOURCES += mdup.c
+EXTRA_DIST += mdup.3.in
LIBMANS += mdup.3
check_PROGRAMS += t/mdup.t
## Time arithmetic.
pkginclude_HEADERS += tv.h
libsys_la_SOURCES += tv.c
+EXTRA_DIST += tv.3.in
LIBMANS += tv.3
###----- That's all, folks --------------------------------------------------
+++ /dev/null
-.\" -*-nroff-*-
-.TH daemonize 3 "6 January 2007" "Straylight/Edgeware" "mLib utilities library"
-.SH NAME
-daemonize \- become a background process
-.\" @detachtty
-.\" @daemonize
-.SH SYNOPSIS
-.nf
-.B "#include <mLib/daemonize.h>"
-.PP
-.B "void detachtty(void);"
-.B "int daemonize(void);"
-.fi
-.SH DESCRIPTION
-The
-.B daemonize
-function causes the current process to become a background process. It
-detaches from its controlling terminal and arranges never to acquire
-another controlling terminal. If it fails for some reason (probably
-because
-.BR fork (2)
-failed),
-.B daemonize
-returns \-1 and sets
-.BR errno ;
-on success, it returns 0.
-.PP
-The
-.B detachtty
-does half of the job of
-.BR daemonize :
-it detaches from its controlling terminal, and calls
-.BR setsid (2)
-and
-.BR fork (2)
-so that it can't acquire a new controlling terminal in future. Errors
-are ignored.
-.SH SEE ALSO
-.BR mLib (3).
-.SH AUTHOR
-Mark Wooding, <mdw@distorted.org.uk>
--- /dev/null
+.\" -*-nroff-*-
+.\"
+.\" Manual for daemonization
+.\"
+.\" (c) 2007, 2009, 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 daemonize 3mLib "6 January 2007" "Straylight/Edgeware" "mLib utilities library"
+.\" @detachtty
+.\" @daemonize
+.
+.\"--------------------------------------------------------------------------
+.SH NAME
+daemonize \- become a background process
+.
+.\"--------------------------------------------------------------------------
+.SH SYNOPSIS
+.
+.nf
+.B "#include <mLib/daemonize.h>"
+.PP
+.B "void detachtty(void);"
+.B "int daemonize(void);"
+.fi
+.
+.\"--------------------------------------------------------------------------
+.SH DESCRIPTION
+.
+The
+.B daemonize
+function causes the current process to become a background process. It
+detaches from its controlling terminal and arranges never to acquire
+another controlling terminal. If it fails for some reason (probably
+because
+.BR fork (2)
+failed),
+.B daemonize
+returns \-1 and sets
+.BR errno ;
+on success, it returns 0.
+.PP
+The
+.B detachtty
+does half of the job of
+.BR daemonize :
+it detaches from its controlling terminal, and calls
+.BR setsid (2)
+and
+.BR fork (2)
+so that it can't acquire a new controlling terminal in future. Errors
+are ignored.
+.
+.\"--------------------------------------------------------------------------
+.SH SEE ALSO
+.
+.BR mLib (3).
+.
+.\"--------------------------------------------------------------------------
+.SH AUTHOR
+.
+Mark Wooding, <mdw@distorted.org.uk>
+.
+.\"----- That's all, folks --------------------------------------------------
.\" -*-nroff-*-
-.TH env 3 "26 July 1999" "Straylight/Edgeware" "mLib utilities library"
-.SH "NAME"
-env \- efficient fiddling with environment variables
+.\"
+.\" Manual for environment variable table
+.\"
+.\" (c) 1999, 2001, 2005, 2009, 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 env 3mLib "26 July 1999" "Straylight/Edgeware" "mLib utilities library"
.\" @env_get
.\" @env_put
.\" @env_import
.\" @env_export
.\" @env_destroy
+.
+.\"--------------------------------------------------------------------------
+.SH "NAME"
+env \- efficient fiddling with environment variables
+.
+.\"--------------------------------------------------------------------------
.SH "SYNOPSIS"
+.
.nf
.B "#include <mLib/env.h>"
.PP
.BI "void env_import(sym_table *" t ", char **" env );
.BI "char **env_export(sym_table *" t );
.fi
+.
+.\"--------------------------------------------------------------------------
.SH "DESCRIPTION"
+.
The functions in the
.B "<mLib/env.h>"
header manipulate environment variables stored in a hash table.
.B env_destroy
function frees an environment symbol table, together with all of the
environment variables.
+.
+.\"--------------------------------------------------------------------------
.SH "SEE ALSO"
+.
.BR sym (3),
.BR mLib (3).
+.
+.\"--------------------------------------------------------------------------
.SH "AUTHOR"
+.
Mark Wooding, <mdw@distorted.org.uk>
+.
+.\"----- That's all, folks --------------------------------------------------
+++ /dev/null
-.\" -*-nroff-*-
-.de VS
-.sp 1
-.RS
-.nf
-.ft B
-..
-.de VE
-.ft R
-.fi
-.RE
-.sp 1
-..
-.TH fdflags 3 "23 July 1999" "Straylight/Edgeware" "mLib utilities library"
-.SH "NAME"
-fdflags \- set file and file descriptor flags
-.\" @fdflags
-.SH "SYNOPSIS"
-.nf
-.B "#include <mLib/fdflags.h>"
-.PP
-.ta \w'\fBint fdflags('u
-.BI "int fdflags(int " fd ,
-.BI " unsigned " fbic ", unsigned " fxor ,
-.BI " unsigned " fdbic ", unsigned " fdxor );
-.fi
-.SH "DESCRIPTION"
-.B fdflags
-is a convenience function for setting file and file descriptor flags
-using
-.BR fcntl (2).
-.PP
-The file flags are read using
-.BR F_GETFL ,
-the new flags are calculated as
-.sp 1
-.RS
-.I new-flags
-=
-.BI ( old-flags
-.B &
-.BI ~ fbic )
-.B ^
-.I fxor
-.RE
-.sp 1
-and the result written back using
-.BR F_SETFL .
-.PP
-Similarly the file descriptor flags are read using
-.BR F_GETFD ,
-the new flags calculated as
-.sp 1
-.RS
-.I new-flags
-=
-.BI ( old-flags
-.B &
-.BI ~ fdbic )
-.B ^
-.I fdxor
-.RE
-.sp 1
-and the result written back using
-.BR F_SETFD .
-.PP
-If all went well,
-.B fdflags
-returns zero; if there was an error, \-1 is returned.
-.SH "EXAMPLES"
-To set the non-blocking and close-on-exec flags:
-.VS
-fdflags(fd, O_NONBLOCK, O_NONBLOCK, FD_CLOEXEC, FD_CLOEXEC);
-.VE
-To clear the non-blocking and close-on-exec flags:
-.VS
-fdflags(fd, O_NONBLOCK, 0, FD_CLOEXEC, 0);
-.VE
-.sp -1
-.SH "SEE ALSO"
-.BR mLib (3).
-.SH "AUTHOR"
-Mark Wooding, <mdw@distorted.org.uk>
--- /dev/null
+.\" -*-nroff-*-
+.\"
+.\" Manual for file descriptor flags
+.\"
+.\" (c) 1999, 2001, 2005, 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 fdflags 3mLib "23 July 1999" "Straylight/Edgeware" "mLib utilities library"
+.\" @fdflags
+.
+.\"--------------------------------------------------------------------------
+.SH "NAME"
+fdflags \- set file and file descriptor flags
+.
+.\"--------------------------------------------------------------------------
+.SH "SYNOPSIS"
+.
+.nf
+.B "#include <mLib/fdflags.h>"
+.PP
+.ta \w'\fBint fdflags('u
+.BI "int fdflags(int " fd ,
+.BI " unsigned " fbic ", unsigned " fxor ,
+.BI " unsigned " fdbic ", unsigned " fdxor );
+.fi
+.
+.\"--------------------------------------------------------------------------
+.SH "DESCRIPTION"
+.
+.B fdflags
+is a convenience function for setting file and file descriptor flags
+using
+.BR fcntl (2).
+.PP
+The file flags are read using
+.BR F_GETFL ,
+the new flags are calculated as
+.sp 1
+.RS
+.I new-flags
+=
+.BI ( old-flags
+.B &
+.BI ~ fbic )
+.B ^
+.I fxor
+.RE
+.sp 1
+and the result written back using
+.BR F_SETFL .
+.PP
+Similarly the file descriptor flags are read using
+.BR F_GETFD ,
+the new flags calculated as
+.sp 1
+.RS
+.I new-flags
+=
+.BI ( old-flags
+.B &
+.BI ~ fdbic )
+.B ^
+.I fdxor
+.RE
+.sp 1
+and the result written back using
+.BR F_SETFD .
+.PP
+If all went well,
+.B fdflags
+returns zero; if there was an error, \-1 is returned.
+.
+.\"--------------------------------------------------------------------------
+.SH "EXAMPLES"
+.
+To set the non-blocking and close-on-exec flags:
+.VS
+fdflags(fd, O_NONBLOCK, O_NONBLOCK, FD_CLOEXEC, FD_CLOEXEC);
+.VE
+To clear the non-blocking and close-on-exec flags:
+.VS
+fdflags(fd, O_NONBLOCK, 0, FD_CLOEXEC, 0);
+.VE
+.sp -1
+.
+.\"--------------------------------------------------------------------------
+.SH "SEE ALSO"
+.
+.BR mLib (3).
+.
+.\"--------------------------------------------------------------------------
+.SH "AUTHOR"
+.
+Mark Wooding, <mdw@distorted.org.uk>
+.
+.\"----- That's all, folks --------------------------------------------------
+++ /dev/null
-.\" -*-nroff-*-
-.TH fdpass 3 "28 November 2003" "Straylight/Edgeware" "mLib utilities library"
-.SH NAME
-fdpass \- file descriptor passing
-.\" @fdpass_send
-.\" @fdpass_recv
-.SH SYNOPSIS
-.nf
-.B "#include <mLib/fdpass.h>"
-.PP
-.BI "ssize_t fdpass_send(int " sock ", int " fd ", const void *" p ", size_t " sz );
-.BI "ssize_t fdpass_recv(int " sock ", int *" fd ", void *" p ", size_t " sz );
-.fi
-.SH DESCRIPTION
-The function
-.B fdpass_send
-sends the file descriptor
-.I fd
-as ancillary data attached to the buffer pointed to by
-.I p
-of length
-.I sz
-over the Unix-domain socket
-.IR sock .
-It returns the amount of data sent, or \-1 on error. For more details,
-see
-.BR sendmsg (2)
-and
-.BR unix (7).
-.PP
-The function
-.B fdpass_recv
-receives at most
-.I sz
-bytes of data into the buffer pointed to by
-.IR p ,
-together with at most one file descriptor passed as ancillary data,
-which is written to the integer pointed to by
-.IR fd .
-Other file descriptors received are closed; any other ancillary messages
-are ignored. If no file descriptor is received,
-.BI * fd
-is set to \-1. The function returns the number of bytes read, or \-1 on
-error. For more details, see
-.BR recvmsg (2)
-and
-.BR unix (7).
-.SH "SEE ALSO"
-.BR recvmsg (2),
-.BR sendmsg (2),
-.BR mLib (3),
-.BR unix (7).
-.SH AUTHOR
-Mark Wooding, <mdw@distorted.org.uk>
--- /dev/null
+.\" -*-nroff-*-
+.\"
+.\" Manual for file descriptor passing
+.\"
+.\" (c) 2003, 2005, 2007, 2009, 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 fdpass 3mLib "28 November 2003" "Straylight/Edgeware" "mLib utilities library"
+.\" @fdpass_send
+.\" @fdpass_recv
+.
+.\"--------------------------------------------------------------------------
+.SH NAME
+fdpass \- file descriptor passing
+.
+.\"--------------------------------------------------------------------------
+.SH SYNOPSIS
+.
+.nf
+.B "#include <mLib/fdpass.h>"
+.PP
+.BI "ssize_t fdpass_send(int " sock ", int " fd ", const void *" p ", size_t " sz );
+.BI "ssize_t fdpass_recv(int " sock ", int *" fd ", void *" p ", size_t " sz );
+.fi
+.
+.\"--------------------------------------------------------------------------
+.SH DESCRIPTION
+.
+The function
+.B fdpass_send
+sends the file descriptor
+.I fd
+as ancillary data attached to the buffer pointed to by
+.I p
+of length
+.I sz
+over the Unix-domain socket
+.IR sock .
+It returns the amount of data sent, or \-1 on error. For more details,
+see
+.BR sendmsg (2)
+and
+.BR unix (7).
+.PP
+The function
+.B fdpass_recv
+receives at most
+.I sz
+bytes of data into the buffer pointed to by
+.IR p ,
+together with at most one file descriptor passed as ancillary data,
+which is written to the integer pointed to by
+.IR fd .
+Other file descriptors received are closed; any other ancillary messages
+are ignored. If no file descriptor is received,
+.BI * fd
+is set to \-1. The function returns the number of bytes read, or \-1 on
+error. For more details, see
+.BR recvmsg (2)
+and
+.BR unix (7).
+.
+.\"--------------------------------------------------------------------------
+.SH "SEE ALSO"
+.
+.BR recvmsg (2),
+.BR sendmsg (2),
+.BR mLib (3),
+.BR unix (7).
+.
+.\"--------------------------------------------------------------------------
+.SH AUTHOR
+.
+Mark Wooding, <mdw@distorted.org.uk>
+.
+.\"----- That's all, folks --------------------------------------------------
+++ /dev/null
-.\" -*-nroff-*-
-.TH fwatch 3 "3 February 2001" "Straylight/Edgeware" "mLib utilities library"
-.SH NAME
-fwatch \- watch a file for changes
-.\" @fwatch_init
-.\" @fwatch_initfd
-.\" @fwatch_update
-.\" @fwatch_updatefd
-.SH SYNOPSIS
-.nf
-.B "#include <mLib/fwatch.h>"
-.PP
-.B "typedef struct { ...\& } fwatch;"
-.PP
-.BI "void fwatch_init(fwatch *" f ", const char *" name );
-.BI "void fwatch_initfd(fwatch *" f ", int " fd );
-.BI "int fwatch_update(fwatch *" f ", const char *" name );
-.BI "int fwatch_updatefd(fwatch *" f ", int " fd );
-.fi
-.SH DESCRIPTION
-These functions watch a file for changes. Use
-.B fwatch_init
-or
-.B fwatch_initfd
-to initialize a
-.B fwatch
-block with information about a file; then later, the functions
-.B fwatch_update
-and
-.B fwatch_updatefd
-will update the information in the structure and inform you whether the
-file changed.
-.PP
-The
-.B fwatch
-functions can't return errors: they remember errors as part of the file
-state instead. The
-.B update
-functions return zero if the file has not changed or nonzero if it has.
-.SH SEE ALSO
-.BR mLib (3).
-.SH AUTHOR
-Mark Wooding, <mdw@distorted.org.uk>
--- /dev/null
+.\" -*-nroff-*-
+.\"
+.\" Manual for watching for file changes
+.\"
+.\" (c) 2001, 2005, 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 fwatch 3mLib "3 February 2001" "Straylight/Edgeware" "mLib utilities library"
+.\" @fwatch_init
+.\" @fwatch_initfd
+.\" @fwatch_update
+.\" @fwatch_updatefd
+.
+.\"--------------------------------------------------------------------------
+.SH NAME
+fwatch \- watch a file for changes
+.
+.\"--------------------------------------------------------------------------
+.SH SYNOPSIS
+.
+.nf
+.B "#include <mLib/fwatch.h>"
+.PP
+.B "typedef struct { ...\& } fwatch;"
+.PP
+.BI "void fwatch_init(fwatch *" f ", const char *" name );
+.BI "void fwatch_initfd(fwatch *" f ", int " fd );
+.BI "int fwatch_update(fwatch *" f ", const char *" name );
+.BI "int fwatch_updatefd(fwatch *" f ", int " fd );
+.fi
+.
+.\"--------------------------------------------------------------------------
+.SH DESCRIPTION
+.
+These functions watch a file for changes. Use
+.B fwatch_init
+or
+.B fwatch_initfd
+to initialize a
+.B fwatch
+block with information about a file; then later, the functions
+.B fwatch_update
+and
+.B fwatch_updatefd
+will update the information in the structure and inform you whether the
+file changed.
+.PP
+The
+.B fwatch
+functions can't return errors: they remember errors as part of the file
+state instead. The
+.B update
+functions return zero if the file has not changed or nonzero if it has.
+.
+.\"--------------------------------------------------------------------------
+.SH SEE ALSO
+.
+.BR mLib (3).
+.
+.\"--------------------------------------------------------------------------
+.SH AUTHOR
+.
+Mark Wooding, <mdw@distorted.org.uk>
+.
+.\"----- That's all, folks --------------------------------------------------
+++ /dev/null
-.\" -*-nroff-*-
-.TH lock 3 "23 May 1999" "Straylight/Edgeware" "mLib utilities library"
-.SH NAME
-lock \- oversimplified file locking interface
-.\" @lock_file
-.SH SYNOPSIS
-.nf
-.B "#include <mLib/lock.h>"
-.PP
-.ta 2n
-.B "enum {"
-.B " LOCK_UNLOCK = ...,"
-.B " LOCK_EXCL = ...,"
-.B " LOCK_NONEXCL = ..."
-.B "};"
-.PP
-.BI "int lock_file(int " fd ", unsigned " how );
-.fi
-.SH DESCRIPTION
-The
-.B lock_file
-function provides an extremely simplistic interface to POSIX
-.BR fcntl (2)
-locking. It locks only entire files, not sections of files. It doesn't
-have a nonblocking `is this file locked?' function.
-.PP
-On entry,
-.I fd
-should be a file descriptor on an open file, and
-.I how
-is a constant which describes how the file is to be locked. The
-possible values of
-.I how
-are:
-.TP
-.B LOCK_EXCL
-Lock the file exclusively. Attempts to lock the file exclusively or
-nonexclusively will fail until the file is unlocked.
-.TP
-.B LOCK_NONEXCL
-Lock the file nonexclusively. Until the file is unlocked, attempts to
-lock it exclusively will fail, but other nonexclusive locks will
-succeed.
-.TP
-.B LOCK_UNLOCK
-Unlocks a locked file. Any locks afterwards can succeed.
-.PP
-The
-.B lock_file
-function will block if it can't obtain a lock immediately. It will time
-itself out after a short while (10 seconds in the current
-implementation) if the lock doesn't become available.
-.PP
-If the call succeeds,
-.B lock_file
-returns zero. On failure, \-1 is returned, and
-.B errno
-is set to an appropriate value. Most of the error returns are from
-.BR fcntl (2)
-(q.v.). If the lock operation times out,
-.B errno
-is set to
-.BR EINTR .
-.SH "SEE ALSO"
-.BR fcntl (2),
-.BR mLib (3).
-.SH AUTHOR
-Mark Wooding, <mdw@distorted.org.uk>
--- /dev/null
+.\" -*-nroff-*-
+.\"
+.\" Manual for file locking
+.\"
+.\" (c) 1999, 2001, 2005, 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 lock 3mLib "23 May 1999" "Straylight/Edgeware" "mLib utilities library"
+.\" @lock_file
+.
+.\"--------------------------------------------------------------------------
+.SH NAME
+lock \- oversimplified file locking interface
+.
+.\"--------------------------------------------------------------------------
+.SH SYNOPSIS
+.
+.nf
+.B "#include <mLib/lock.h>"
+.PP
+.ta 2n
+.B "enum {"
+.B " LOCK_UNLOCK = ...,"
+.B " LOCK_EXCL = ...,"
+.B " LOCK_NONEXCL = ..."
+.B "};"
+.PP
+.BI "int lock_file(int " fd ", unsigned " how );
+.fi
+.
+.\"--------------------------------------------------------------------------
+.SH DESCRIPTION
+.
+The
+.B lock_file
+function provides an extremely simplistic interface to POSIX
+.BR fcntl (2)
+locking. It locks only entire files, not sections of files. It doesn't
+have a nonblocking `is this file locked?' function.
+.PP
+On entry,
+.I fd
+should be a file descriptor on an open file, and
+.I how
+is a constant which describes how the file is to be locked. The
+possible values of
+.I how
+are:
+.TP
+.B LOCK_EXCL
+Lock the file exclusively. Attempts to lock the file exclusively or
+nonexclusively will fail until the file is unlocked.
+.TP
+.B LOCK_NONEXCL
+Lock the file nonexclusively. Until the file is unlocked, attempts to
+lock it exclusively will fail, but other nonexclusive locks will
+succeed.
+.TP
+.B LOCK_UNLOCK
+Unlocks a locked file. Any locks afterwards can succeed.
+.PP
+The
+.B lock_file
+function will block if it can't obtain a lock immediately. It will time
+itself out after a short while (10 seconds in the current
+implementation) if the lock doesn't become available.
+.PP
+If the call succeeds,
+.B lock_file
+returns zero. On failure, \-1 is returned, and
+.B errno
+is set to an appropriate value. Most of the error returns are from
+.BR fcntl (2)
+(q.v.). If the lock operation times out,
+.B errno
+is set to
+.BR EINTR .
+.
+.\"--------------------------------------------------------------------------
+.SH "SEE ALSO"
+.
+.BR fcntl (2),
+.BR mLib (3).
+.
+.\"--------------------------------------------------------------------------
+.SH AUTHOR
+.
+Mark Wooding, <mdw@distorted.org.uk>
+.
+.\"----- That's all, folks --------------------------------------------------
.\" -*-nroff-*-
-.de VS
-.sp 1
-.RS
-.nf
-.ft B
-..
-.de VE
-.ft R
-.fi
-.RE
-.sp 1
-..
-.de hP
-.IP
-.ft B
-\h'-\w'\\$1\ 'u'\\$1\ \c
-.ft P
-..
-.ie t \{\
-. ds o \(bu
-. de VP
-. sp .4v
-..
-\}
-.el \{\
-. ds o o
-. de VP
-. sp
-..
-\}
-.TH mdup 3 "4 January" "Straylight/Edgeware" "mLib utilities library"
+.\"
+.\" Manual for descriptor juggling
+.\"
+.\" (c) 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 mdup 3mLib "4 January" "Straylight/Edgeware" "mLib utilities library"
+.\" @mdup
+.
+.\"--------------------------------------------------------------------------
.SH NAME
mdup \- renumber file descriptors
+.
+.\"--------------------------------------------------------------------------
.SH SYNOPSIS
+.
.nf
.B "#include <mLib/mdup.h>"
.PP
.PP
.BI "int mdup(mdup_fd *" v ", size_t " n ");"
.fi
+.
+.\"--------------------------------------------------------------------------
.SH DESCRIPTION
+.
The
.B mdup
function renumbers file descriptors, using the
function is capable of arbitrary file descriptor remappings. In
particular, it works correctly even if the desired remappings contain
cycles.
+.
.SS "Background: the problem that mdup solves"
The
.B mdup
.B mdup
has taken responsibility for closing the other descriptors for the
wanted ends of the pipes.
+.
+.\"--------------------------------------------------------------------------
.SH "SEE ALSO"
+.
.BR dup (2),
.BR dup2 (2),
.BR mLib (3).
+.
+.\"--------------------------------------------------------------------------
.SH AUTHOR
+.
Mark Wooding, <mdw@distorted.org.uk>
+.
+.\"----- That's all, folks --------------------------------------------------
.\" -*-nroff-*-
-.TH tv 3 "22 May 1999" "Straylight/Edgeware" "mLib utilities library"
-.SH NAME
-tv \- arithmetic on \fBstruct timeval\fR objects
+.\"
+.\" Manual for timeval arithmetic
+.\"
+.\" (c) 1999, 2001, 2005, 2009, 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 tv 3mLib "22 May 1999" "Straylight/Edgeware" "mLib utilities library"
.\" @tv_add
.\" @tv_addl
.\" @tv_sub
.\" @tv_subl
.\" @tv_cmp
-.\"
+.
.\" @TV_ADD
.\" @TV_ADDL
.\" @TV_SUB
.\" @TV_SUBL
.\" @TV_CMP
-.\"
+.
+.\"--------------------------------------------------------------------------
+.SH NAME
+tv \- arithmetic on \fBstruct timeval\fR objects
+.
+.\"--------------------------------------------------------------------------
.SH SYNOPSIS
+.
.nf
.B "#include <mLib/tv.h>"
.PP
.BI "int TV_CMP(const struct timeval *" a ", " op ,
.BI " const struct timeval *" b );
.fi
+.
+.\"--------------------------------------------------------------------------
.SH DESCRIPTION
+.
The
.B <mLib/tv.h>
header file provides functions and macros which perform simple
and
.IR y ,
it returns -1 if
-.IR x " < " y ,
+.IR x "\ <\ " y ,
zero if
-.IR x " == " y ,
+.IR x "\ =\ " y ,
or 1 if
-.IR x " > " y .
+.IR x "\ >\ " y .
Hence, the result can be compared against zero in a relatively intuitive
way (as for
.BR strcmp (3),
although I can't see why there'd be a problem. (If there is one, then
my implementation has it too, because they're the same. I don't
document the restriction because I don't think it exists.)
+.
+.\"--------------------------------------------------------------------------
.SH "SEE ALSO"
+.
.BR mLib (3).
+.
+.\"--------------------------------------------------------------------------
.SH AUTHOR
+.
Mark Wooding, <mdw@distorted.org.uk>
+.
+.\"----- That's all, folks --------------------------------------------------
$(MAKE) -C $(top_builddir) all
.PHONY: check-build
+###--------------------------------------------------------------------------
+### Additional utilities.
+
+EXTRA_DIST += template-canonify
+
###--------------------------------------------------------------------------
### Test directories.
noinst_LTLIBRARIES = libtest.la
libtest_la_SOURCES =
+SUBDIRS =
+
###--------------------------------------------------------------------------
### Component files.
## Benchmarking.
pkginclude_HEADERS += bench.h
libtest_la_SOURCES += bench.c
+EXTRA_DIST += bench.3.in
LIBMANS += bench.3
## Old `testrig' testing framework.
pkginclude_HEADERS += testrig.h
libtest_la_SOURCES += testrig.c
+EXTRA_DIST += testrig.3.in
LIBMANS += testrig.3
## New `tvec' testing framework.
libtest_la_SOURCES += tvec-output.c
libtest_la_SOURCES += tvec-types.c
libtest_la_SOURCES += tvec-main.c
+EXTRA_DIST += tvec.3.in
+EXTRA_DIST += tvec-types.3.in
+EXTRA_DIST += tvec-adhoc.3.in
+EXTRA_DIST += tvec-main.3.in
+EXTRA_DIST += tvec-env.3.in
+EXTRA_DIST += tvec-tyimpl.3.in
+EXTRA_DIST += tvec-output.3.in
LIBMANS += tvec.3
LIBMANS += tvec-types.3
LIBMANS += tvec-adhoc.3
LIBMANS += tvec-output.3
libtest_la_SOURCES += tvec-bench.c
+EXTRA_DIST += tvec-bench.3.in
LIBMANS += tvec-bench.3
libtest_la_SOURCES += tvec-remote.c
+EXTRA_DIST += tvec-remote.3.in
LIBMANS += tvec-remote.3
libtest_la_SOURCES += tvec-timeout.c
+EXTRA_DIST += tvec-timeout.3.in
LIBMANS += tvec-timeout.3
check_PROGRAMS += t/tvec.t
.\" -*-nroff-*-
-.ie t .ds , \h'\w'\ 'u/2u'
-.el .ds , \ \"
-.TH bench 3 "9 March 2024" "Straylight/Edgeware" "mLib utilities library"
+.\"
+.\" Manual for benchmarking core
+.\"
+.\" (c) 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 bench 3mLib "9 March 2024" "Straylight/Edgeware" "mLib utilities library"
.\" @bench_createtimer
.\" @bench_init
.\" @bench_destroy
.\" @bench_calibrate
.\" @bench_measure
.
+.\"--------------------------------------------------------------------------
+.SH NAME
+bench \- low-level benchmarking tools
+.
+.\"--------------------------------------------------------------------------
.SH SYNOPSIS
+.
.nf
.B "#include <mLib/bench.h>"
.PP
.BI " double " base ", bench_fn *" fn ", void *" ctx );
.fi
.
+.\"--------------------------------------------------------------------------
.SH DESCRIPTION
+.
The header file
.B "<mLib/bench.h>"
provides declarations and defintions
is set in
.BR f .
.
+.\"--------------------------------------------------------------------------
.SH "SEE ALSO"
+.
+.BR tvec-bench (3),
.BR mLib (3).
.
+.\"--------------------------------------------------------------------------
.SH AUTHOR
+.
Mark Wooding, <mdw@distorted.org.uk>
+.
+.\"----- That's all, folks --------------------------------------------------
--- /dev/null
+### -*-makefile-*-
+###
+### Build file for test vector example
+###
+### (c) 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.
+
+include $(top_srcdir)/vars.am
+
+noinst_PROGRAMS =
+
+###--------------------------------------------------------------------------
+### The test vector framework example.
+
+noinst_PROGRAMS += testex
+testex_SOURCES =
+
+testex_SOURCES += testex.c
+testex_SOURCES += exfunc.c
+testex_SOURCES += example.h
+
+###----- That's all, folks --------------------------------------------------
--- /dev/null
+/* -*-c-*-
+ *
+ * Example test program
+ *
+ * (c) 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.
+ */
+
+#ifndef MLIB_EXAMPLE_H
+#define MLIB_EXAMPLE_H
+
+#ifdef __cplusplus
+ extern "C" {
+#endif
+
+/*----- Header files ------------------------------------------------------*/
+
+#include <stddef.h>
+
+/*----- Functions provided ------------------------------------------------*/
+
+extern int add(int /*x*/, int /*y*/);
+ /* Return the sum X + Y. */
+
+extern int greet(char */*buf*/, size_t /*sz*/, const char */*name*/);
+ /* Generate a personalized greeting, mentioning NAME. The greeting is
+ * written to the output buffer BUF, which has space for SZ characters.
+ * Return zero on success, or -1 on error.
+ */
+
+/*----- That's all, folks -------------------------------------------------*/
+
+#ifdef __cplusplus
+ }
+#endif
+
+#endif
--- /dev/null
+/* -*-c-*-
+ *
+ * Example functionality to test
+ *
+ * (c) 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.
+ */
+
+/*----- Header files ------------------------------------------------------*/
+
+#include <stdio.h>
+#include <string.h>
+
+#include "example.h"
+
+/*----- Main code ---------------------------------------------------------*/
+
+/* Return the sum X + Y. */
+int add(int x, int y)
+ { return (x + y); }
+
+/* Generate a personalized greeting, mentioning NAME. The greeting is
+ * written to the output buffer BUF, which has space for SZ characters.
+ * Return zero on success, or -1 on error.
+ */
+int greet(char *buf, size_t sz, const char *name)
+{
+ if (sz < strlen(name) + 9) return (-1);
+ sprintf(buf, "Hello, %s!", name);
+ return (0);
+}
+
+/*----- That's all, folks -------------------------------------------------*/
--- /dev/null
+/* -*-c-*-
+ *
+ * Example test program
+ *
+ * (c) 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.
+ */
+
+/*----- Header files ------------------------------------------------------*/
+
+#include "tvec.h"
+
+#include "example.h"
+
+/*----- Register allocation -----------------------------------------------*/
+
+enum {
+ /* add */ /* greet */
+ RZ, RMSG = RZ,
+ RRC,
+
+ NROUT,
+
+ RX = NROUT, RNAME = RX,
+ RY, RSZ = RY,
+
+ NREG
+};
+
+/*----- Addition test -----------------------------------------------------*/
+
+void test_add(const struct tvec_reg *in, struct tvec_reg *out, void *ctx)
+ { out[RZ].v.i = add(in[RX].v.i, in[RY].v.i); }
+
+static const struct tvec_regdef add_regs[] = {
+ { "x", &tvty_int, RX, 0, { &tvrange_int } },
+ { "y", &tvty_int, RY, 0, { &tvrange_int } },
+ { "z", &tvty_int, RZ, 0, { &tvrange_int } },
+ TVEC_ENDREGS
+};
+
+#define ADD_TEST \
+ { "add", add_regs, 0, test_add }
+
+/*----- Greeting test -----------------------------------------------------*/
+
+void test_greet(const struct tvec_reg *in, struct tvec_reg *out, void *ctx)
+{
+ tvec_alloctext(&out[RMSG].v, in[RSZ].v.u);
+ out[RRC].v.i = greet(out[RMSG].v.text.p, in[RSZ].v.u, in[RNAME].v.text.p);
+ out[RMSG].v.text.sz = strlen(out[RMSG].v.text.p);
+}
+
+static const struct tvec_regdef greet_regs[] = {
+ { "name", &tvty_text, RNAME, 0 },
+ { "sz", &tvty_size, RSZ, 0, { &tvrange_size } },
+ { "msg", &tvty_text, RMSG, TVRF_UNSET },
+ { "rc", &tvty_int, RRC, 0, { &tvrange_int } },
+ TVEC_ENDREGS
+};
+
+#define GREET_TEST \
+ { "greet", greet_regs, 0, test_greet }
+
+/*----- Main program ------------------------------------------------------*/
+
+static const struct tvec_test tests[] = {
+ ADD_TEST,
+ GREET_TEST,
+ TVEC_ENDTESTS
+};
+
+static const struct tvec_config test_config =
+ { tests, NROUT, NREG, sizeof(struct tvec_reg) };
+
+int main(int argc, char *argv[])
+ { return (tvec_main(argc, argv, &test_config, 0)); }
+
+/*----- That's all, folks -------------------------------------------------*/
--- /dev/null
+;;; -*-conf-windows-*-
+
+;;;--------------------------------------------------------------------------
+[add]
+
+x = 1
+y = 2
+z = 3
+
+x = 2
+y = 3
+z = 5
+
+;;;--------------------------------------------------------------------------
+[greet]
+
+name = world
+sz = 14
+msg = Hello, world!
+rc = 0
+
+name = world
+sz = 13
+msg *
+rc = -1
+
+name = "embedded\0nul"
+sz = 32
+msg = Hello, embedded!
+rc = 0
+@outcome = xfail
+;; doesn't correctly handle names with embedded NUL characters.
+
+;;;----- That's all, folks --------------------------------------------------
#define TYPEREGS(_) \
_(int, RI, int, p, &tvrange_i16) \
_(uint, RU, uint, p, &tvrange_u16) \
+ _(size, RSZ, size, p, 0) \
_(float, RFP, float, p, 0) \
_(fltish, RFISH, float, p, &fltish_info) \
+ _(dur, RDUR, duration, p, 0) \
_(char, RCH, char, p, 0) \
_(ienum, RIE, ienum, p, &ienum_info) \
_(uenum, RUE, uenum, p, &uenum_info) \
#define test_copy_int test_copy_simple
#define test_copy_uint test_copy_simple
+#define test_copy_size test_copy_simple
#define test_copy_ienum test_copy_simple
#define test_copy_uenum test_copy_simple
#define test_copy_fenum test_copy_simple
#define test_copy_flags test_copy_simple
#define test_copy_float test_copy_simple
#define test_copy_fltish test_copy_simple
+#define test_copy_dur test_copy_simple
#define COPYREG(name, i, ty, argslot, argval) \
static DSGINIT(const) struct tvec_regdef name##_copyregs[] = { \
.\" -*-nroff-*-
-.de VS
-.sp 1
-.in +5
-.nf
-.ft B
-..
-.de VE
-.ft R
-.fi
-.in -5
-.sp 1
-..
-.TH testrig 3 "5 June 1999" "Straylight/Edgeware" "mLib utilities library"
+.\"
+.\" Manual for old-fashioned testing
+.\"
+.\" (c) 1999, 2001, 2005, 2008, 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 testrig 3mLib "5 June 1999" "Straylight/Edgeware" "mLib utilities library"
+.\" @test_do
+.\" @test_run
+.
+.\"--------------------------------------------------------------------------
.SH NAME
testrig \- generic test rig
-.\" @test_run
+.
+.\"--------------------------------------------------------------------------
.SH SYNOPSIS
+.
.nf
.B "#include <mLib/testrig.h>"
.PP
.BI "void test_run(int " argc ", char *" argv [],
.BI " const test_chunk " chunk "[], const char *" def );
.fi
+.
+.\"--------------------------------------------------------------------------
.SH DESCRIPTION
+.
.SS Structure
Test vectors are gathered together into
.I chunks
which should be processed in the same way. Chunks, in turn, are grouped
into
.IR suites .
+.
.SS Functions
The
.B test_do
argument is (the address of) an array of
.I "chunk definitions"
describing the layout of the test vector file.
+.
.SS "Test vector file syntax"
Test vector files are mostly free-form. Comments begin with a hash
.RB (` # ')
or a string enclosed in quote marks (double or single). Quoted strings
may contain newlines. In either type of value, a backslash escapes the
following character.
+.
.SS "Suite definitions"
A
.I suite definition
is a pointer to an array of these structures, terminated by one with a
null
.BR name .
+.
.SS "Chunk definitions"
A
.I "chunk definition"
reads test vectors one by one, translating each value according to the
designated field type, and then passing the completed array of fields to
the test function.
+.
.SS "Field types"
A field type describes how a field is to be read and written. A field
type is described by a
(see
.BR bits (3))
instead.
+.
+.\"--------------------------------------------------------------------------
.SH "SEE ALSO"
+.
+.BR tvec (3),
.BR mLib (3).
+.
+.\"--------------------------------------------------------------------------
.SH "AUTHOR"
+.
Mark Wooding, <mdw@distorted.org.uk>
+.
+.\"----- That's all, folks --------------------------------------------------
@exit = killed | SIGALRM
time = 0.125
-z = 1
+z = 0.125
])
check_template([BUILDDIR/t/tvec.t -fh tv], [0],
[sleep: ok
.\" -*-nroff-*-
-.de VS
-.sp 1
-.RS
-.nf
-.ft B
-..
-.de VE
-.ft R
-.fi
-.RE
-.sp 1
-..
-.de hP
-.IP
-.ft B
-\h'-\w'\\$1\ 'u'\\$1\ \c
-.ft P
-..
-.ie t \{\
-. ds o \(bu
-. de VP
-. sp .4v
-..
-\}
-.el \{\
-. ds o o
-. de VP
-. sp
-..
-\}
-..
-.TH tvec-adhoc 3 "11 March 2024" "Straylight/Edgeware" "mLib utilities library"
-.SH NAME
-tvec-adhoc \- ad-hoc testing with the test vector framework
+.\"
+.\" Manual for ad-hoc testing with the test vector framework
+.\"
+.\" (c) 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 tvec-adhoc 3mLib "11 March 2024" "Straylight/Edgeware" "mLib utilities library"
.\" @tvec_adhocconfig
.\" @tvec_adhoc
.
.\" @TVEC_CLAIM
.\" @tvec_claim_eq
.
+.\"--------------------------------------------------------------------------
+.SH NAME
+tvec-adhoc \- ad-hoc testing with the test vector framework
+.
+.\"--------------------------------------------------------------------------
.SH SYNOPSIS
+.
.nf
.B "#include <mLib/tvec.h>"
.PP
+++ /dev/null
-.\" -*-nroff-*-
-.de VS
-.sp 1
-.RS
-.nf
-.ft B
-..
-.de VE
-.ft R
-.fi
-.RE
-.sp 1
-..
-.de hP
-.IP
-.ft B
-\h'-\w'\\$1\ 'u'\\$1\ \c
-.ft P
-..
-.ie t \{\
-. ds o \(bu
-. de VP
-. sp .4v
-..
-\}
-.el \{\
-. ds o o
-. de VP
-. sp
-..
-\}
-..
-.TH tvec-bench 3 "11 March 2024" "Straylight/Edgeware" "mLib utilities library"
-.SH NAME
-tvec-bench \- benchmarking with the test vector framework
-.\" @TVEC_BENCHENV
-.\" @TVEC_BENCHINIT
-.\" @tvec_benchreport
-.
-.SH SYNOPSIS
-.nf
-.B "#include <mLib/tvec.h>"
-.PP
-.ta 2n
-.B "struct tvec_benchenv {"
-.B " struct tvec_env _env;"
-.B " struct bench_state **bst;"
-.B " unsigned long niter;"
-.B " int riter, rbuf;"
-.B " const struct tvec_env *env;"
-.B "};"
-.B "struct bench_state *tvec_benchstate;"
-.B "#define TVEC_BENCHENV ..."
-.B "#define TVEC_BENCHINIT ..."
-.B "enum {"
-.B " TVBU_OP = ...,"
-.B " TVBU_BYTE = ...,"
-.B " ...,"
-.B " TVBU_LIMIT"
-.B "};"
-.PP
-.ta \w'\fBvoid tvec_benchreport('u
-.BI "void tvec_benchreport(const struct gprintf_ops *" gops ", void *" go ,
-.BI " unsigned " unit ", const struct bench_timing *" tm );
-.fi
--- /dev/null
+.\" -*-nroff-*-
+.\"
+.\" Manual for bencharking with the test-vector framework
+.\"
+.\" (c) 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 tvec-bench 3mLib "11 March 2024" "Straylight/Edgeware" "mLib utilities library"
+.\" @TVEC_BENCHENV
+.\" @TVEC_BENCHINIT
+.\" @tvec_benchreport
+.
+.\"--------------------------------------------------------------------------
+.SH NAME
+tvec-bench \- benchmarking with the test vector framework
+.
+.\"--------------------------------------------------------------------------
+.SH SYNOPSIS
+.
+.nf
+.B "#include <mLib/tvec.h>"
+.PP
+.ta 2n
+.B "struct tvec_benchenv {"
+.B " struct tvec_env _env;"
+.B " struct bench_state **bst;"
+.B " unsigned long niter;"
+.B " int riter, rbuf;"
+.B " const struct tvec_env *env;"
+.B "};"
+.B "struct bench_state *tvec_benchstate;"
+.B "#define TVEC_BENCHENV ..."
+.B "#define TVEC_BENCHINIT ..."
+.B "enum {"
+.B " TVBU_OP = ...,"
+.B " TVBU_BYTE = ...,"
+.B " ...,"
+.B " TVBU_LIMIT"
+.B "};"
+.PP
+.ta \w'\fBvoid tvec_benchreport('u
+.BI "void tvec_benchreport(const struct gprintf_ops *" gops ", void *" go ,
+.BI " unsigned " unit ", const struct bench_timing *" tm );
+.fi
for (rd = tv->test->regs; rd->name; rd++) {
if (rd->i >= tv->cfg.nrout) continue;
rin = TVEC_REG(tv, in, rd->i); rout = TVEC_REG(tv, out, rd->i);
- if (!rin->f&TVRF_LIVE) continue;
+ if (!(rin->f&TVRF_LIVE)) continue;
if (!(rout->f&TVRF_LIVE) || !rd->ty->eq(&rin->v, &rout->v, rd))
return (-1);
}
* output registers as live if the corresponding inputs are
* live. It calls the environment's @before@, @run@, and
* @after@ functions if provided; if there is no @run@ function,
- * it calls @tvec_check@ to verify the output values.
+ * then it calls the test function directly, passing it the
+ * environment's context pointer, and then calls @tvec_check@ to
+ * verify the output values.
*/
static void check(struct tvec_state *tv, struct groupstate *g)
const struct tvec_test *t = tv->test;
const struct tvec_env *env = t->env;
const struct tvec_regdef *rd;
+ struct tvec_reg *r;
unsigned f = 0;
#define f_err 1u
if (!(tv->f&TVSF_OPEN)) return;
for (rd = t->regs; rd->name; rd++) {
- if (TVEC_REG(tv, in, rd->i)->f&TVRF_LIVE) {
+ r = TVEC_REG(tv, in, rd->i);
+ if (r->f&TVRF_LIVE) {
if (rd->i < tv->cfg.nrout)
TVEC_REG(tv, out, rd->i)->f |= TVRF_LIVE;
- } else if (!(rd->f&TVRF_OPT)) {
+ } else if (!(r->f&TVRF_SEEN) && !(rd->f&TVRF_OPT)) {
tvec_error(tv, "required register `%s' not set in test `%s'",
rd->name, t->name);
f |= f_err;
{
const struct tvec_test *t = tv->test;
const struct tvec_env *env = t->env;
+ const struct tvec_regdef *rd0, *rd1;
unsigned i;
+#ifndef NDEBUG
+ /* Check that the register names and indices are distinct. */
+ for (rd0 = t->regs; rd0->name; rd0++) {
+ assert(rd0->i < tv->cfg.nreg);
+ for (rd1 = t->regs; rd1->name; rd1++)
+ if (rd0 != rd1) {
+ assert(rd0->i != rd1->i);
+ assert(STRCMP(rd0->name, !=, rd1->name));
+ }
+ }
+#endif
+
tv->output->ops->bgroup(tv->output);
tv->f &= ~(TVSF_SKIP | TVSF_MUFFLE);
tvec_initregs(tv);
*/
ungetc(ch, tv->fp);
DRESET(&d);
- if (tvec_readword(tv, &d, 0, "=:;", "register name"))
+ if (tvec_readword(tv, &d, 0, "=:*;", "register name"))
goto flush_line;
- /* Now there should be a separator. */
- tvec_skipspc(tv); ch = getc(tv->fp);
- if (ch != '=' && ch != ':')
- { tvec_syntax(tv, ch, "`=' or `:'"); goto flush_line; }
- tvec_skipspc(tv);
-
- /* If there's no test, then report an error. Set the muffle flag,
- * because there's no point in complaining about every assignment
- * in this block.
- */
- if (!tv->test) {
- if (!(tv->f&TVSF_MUFFLE)) tvec_error(tv, "no current test");
- tv->f |= TVSF_MUFFLE; goto flush_line;
- }
-
- /* Open the test. This is syntactically a stanza of settings, so
- * it's fair to report on missing register assignments.
- */
- open_test(tv);
-
+ /* See what sort of thing we have found. */
if (d.buf[0] == '@') {
/* A special register assignment. */
}
tvec_unkreg(tv, d.buf); goto flush_line;
found_var:
-
- /* Set up the register. */
- if (vd->regsz <= sizeof(rbuf))
- r = &rbuf;
- else {
- GROWBUF_REPLACE(&arena_stdlib, r_alloc, rsz, vd->regsz,
- 8*sizeof(void *), 1);
- r = r_alloc;
- }
-
- /* Read and set the value. */
- vd->def.ty->init(&r->v, &vd->def);
- if (vd->def.ty->parse(&r->v, &vd->def, tv)) goto flush_line;
- if (!(tv->f&TVSF_SKIP) && vd->setvar(tv, d.buf, &r->v, varctx))
- goto bad;
-
- /* Clean up. */
- vd->def.ty->release(&r->v, &vd->def); vd = 0;
+ rd = &vd->def;
} else {
/* A standard register. */
tvec_error(tv, "unknown register `%s' for test `%s'",
d.buf, tv->test->name);
goto flush_line;
-
found_reg:
+
/* Complain if the register is already set. */
r = TVEC_REG(tv, in, rd->i);
- if (r->f&TVRF_LIVE)
+ if (r->f&TVRF_SEEN)
{ tvec_dupreg(tv, rd->name); goto flush_line; }
+ }
+
+ /* If there's no test, then report an error. Set the muffle flag,
+ * because there's no point in complaining about every assignment
+ * in this block.
+ */
+ if (!tv->test) {
+ if (!(tv->f&TVSF_MUFFLE)) tvec_error(tv, "no current test");
+ tv->f |= TVSF_MUFFLE; goto flush_line;
+ }
- /* Parse a value and mark the register as live. */
- if (rd->ty->parse(&r->v, rd, tv)) goto flush_line;
- r->f |= TVRF_LIVE;
+ /* Open the test. This is syntactically a paragraph of settings,
+ * so it's fair to report on missing register assignments.
+ */
+ open_test(tv);
+
+ /* Now there should be a separator. */
+ tvec_skipspc(tv); ch = getc(tv->fp);
+
+ if (ch == '*') {
+ /* Register explicitly marked unset. */
+
+ if (vd) {
+ tvec_error(tv, "can't unset special variables");
+ goto flush_line;
+ }
+ if (!(rd->f&(TVRF_OPT | TVRF_UNSET))) {
+ tvec_error(tv, "register `%s' must be assigned "
+ "a value in test `%s'", rd->name, tv->test->name);
+ goto flush_line;
+ }
+ r->f |= TVRF_SEEN;
+ if (tvec_flushtoeol(tv, 0)) goto bad;
+ } else {
+ /* Common case of a proper assignment. */
+
+ /* We must have a separator. */
+ if (ch != '=' && ch != ':')
+ { tvec_syntax(tv, ch, "`=', `:', or `*'"); goto flush_line; }
+ tvec_skipspc(tv);
+
+ if (!vd) {
+ /* An ordinary register. Parse a value and mark the register
+ * as live.
+ */
+
+ if (rd->ty->parse(&r->v, rd, tv)) goto flush_line;
+ r->f |= TVRF_LIVE | TVRF_SEEN;
+ } else {
+ /* A special register defined by an environment. */
+
+ /* Set up the register. */
+ if (vd->regsz <= sizeof(rbuf))
+ r = &rbuf;
+ else {
+ GROWBUF_REPLACE(&arena_stdlib, r_alloc, rsz, vd->regsz,
+ 8*sizeof(void *), 1);
+ r = r_alloc;
+ }
+
+ /* Read and set the value. */
+ rd->ty->init(&r->v, rd);
+ if (rd->ty->parse(&r->v, rd, tv)) goto flush_line;
+ if (!(tv->f&TVSF_SKIP) && vd->setvar(tv, d.buf, &r->v, varctx))
+ goto bad;
+
+ /* Clean up. */
+ rd->ty->release(&r->v, &vd->def); vd = 0;
+ }
}
}
break;
.\" -*-nroff-*-
-.de VS
-.sp 1
-.RS
-.nf
-.ft B
-..
-.de VE
-.ft R
-.fi
-.RE
-.sp 1
-..
-.de hP
-.IP
-.ft B
-\h'-\w'\\$1\ 'u'\\$1\ \c
-.ft P
-..
-.ie t \{\
-. ds o \(bu
-. de VP
-. sp .4v
-..
-\}
-.el \{\
-. ds o o
-. de VP
-. sp
-..
-\}
-..
-.TH tvec-env 3 "11 March 2024" "Straylight/Edgeware" "mLib utilities library"
-.SH NAME
-tvec-env \- test vector framework environments
+.\"
+.\" Manual for test environments
+.\"
+.\" (c) 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 tvec-env 3mLib "11 March 2024" "Straylight/Edgeware" "mLib utilities library"
.\" @TVEG_GREG
.\" @TVEG_REG
.
.\" @tvec_initregs
.\" @tvec_releaseregs
.\" @tvec_releaseoutputs
+.
+.\"--------------------------------------------------------------------------
+.SH NAME
+tvec-env \- test vector framework environments
+.
+.\"--------------------------------------------------------------------------
.SH SYNOPSIS
+.
.nf
.B "#include <mLib/tvec.h>"
.PP
+++ /dev/null
-.\" -*-nroff-*-
-.de VS
-.sp 1
-.RS
-.nf
-.ft B
-..
-.de VE
-.ft R
-.fi
-.RE
-.sp 1
-..
-.de hP
-.IP
-.ft B
-\h'-\w'\\$1\ 'u'\\$1\ \c
-.ft P
-..
-.ie t \{\
-. ds o \(bu
-. de VP
-. sp .4v
-..
-\}
-.el \{\
-. ds o o
-. de VP
-. sp
-..
-\}
-..
-.TH tvec-main 3 "11 March 2024" "Straylight/Edgeware" "mLib utilities library"
-.SH NAME
-tvec-main \- test vector framework program frontend
-.\" @tvec_parseargs
-.\" @tvec_readstdin
-.\" @tvec_readfile
-.\" @tvec_readarg
-.\" @tvec_readdflt
-.\" @tvec_readargs
-.\" @tvec_main
-.
-.SH SYNOPSIS
-.nf
-.B "#include <mLib/tvec.h>"
-.PP
-.ta \w'\fBvoid tvec_parseargs('u
-.BI "void tvec_parseargs(int " argc ", char *" argv "[],"
-.BI " struct tvec_state *" tv_out ,
-.BI " int *" argpos_out ,
-.BI " const struct tvec_config *" config );
-.BI "int tvec_readstdin(struct tvec_state *" tv );
-.BI "int tvec_readfile(struct tvec_state *" tv ", const char *" file );
-.BI "int tvec_readarg(struct tvec_state *" tv ", const char *" arg );
-.BI "int tvec_readdflt(struct tvec_state *" tv ", const char *" file );
-.ta \w'\fBvoid tvec_readargs('u
-.BI "void tvec_readargs(int " argc ", char *" argv "[],"
-.BI " struct tvec_state *" tv ,
-.BI " int *" argpos_out ", const char *" dflt );
-.ta \w'\fBvoid tvec_main('u
-.BI "void tvec_main(int " argc ", char *" argv "[],"
-.BI " const struct tvec_config *" config ", const char *" dflt );
-.fi
--- /dev/null
+.\" -*-nroff-*-
+.\"
+.\" Manual for test-vector framework front-end
+.\"
+.\" (c) 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 tvec-main 3mLib "11 March 2024" "Straylight/Edgeware" "mLib utilities library"
+.\" @tvec_parseargs
+.\" @tvec_readstdin
+.\" @tvec_readfile
+.\" @tvec_readarg
+.\" @tvec_readdflt
+.\" @tvec_readargs
+.\" @tvec_main
+.
+.\"--------------------------------------------------------------------------
+.SH NAME
+tvec-main \- test vector framework program frontend
+.
+.\"--------------------------------------------------------------------------
+.SH SYNOPSIS
+.
+.nf
+.B "#include <mLib/tvec.h>"
+.PP
+.ta \w'\fBvoid tvec_parseargs('u
+.BI "void tvec_parseargs(int " argc ", char *" argv "[],"
+.BI " struct tvec_state *" tv_out ,
+.BI " int *" argpos_out ,
+.BI " const struct tvec_config *" config );
+.BI "int tvec_readstdin(struct tvec_state *" tv );
+.BI "int tvec_readfile(struct tvec_state *" tv ", const char *" file );
+.BI "int tvec_readarg(struct tvec_state *" tv ", const char *" arg );
+.BI "int tvec_readdflt(struct tvec_state *" tv ", const char *" file );
+.ta \w'\fBvoid tvec_readargs('u
+.BI "void tvec_readargs(int " argc ", char *" argv "[],"
+.BI " struct tvec_state *" tv ,
+.BI " int *" argpos_out ", const char *" dflt );
+.ta \w'\fBvoid tvec_main('u
+.BI "void tvec_main(int " argc ", char *" argv "[],"
+.BI " const struct tvec_config *" config ", const char *" dflt );
+.fi
.\" -*-nroff-*-
-.de VS
-.sp 1
-.RS
-.nf
-.ft B
-..
-.de VE
-.ft R
-.fi
-.RE
-.sp 1
-..
-.de hP
-.IP
-.ft B
-\h'-\w'\\$1\ 'u'\\$1\ \c
-.ft P
-..
-.ie t \{\
-. ds o \(bu
-. de VP
-. sp .4v
-..
-\}
-.el \{\
-. ds o o
-. de VP
-. sp
-..
-\}
-..
-.TH tvec-output 3 "11 March 2024" "Straylight/Edgeware" "mLib utilities library"
+.\"
+.\" Manual for test-vector framework output drivers
+.\"
+.\" (c) 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 tvec-output 3mLib "11 March 2024" "Straylight/Edgeware" "mLib utilities library"
+.\" @tvec_strlevel
+.
+.\"--------------------------------------------------------------------------
.SH NAME
tvec-output \- test vector framework output driver interface
-.\" @tvec_strlevel
.
+.\"--------------------------------------------------------------------------
.SH SYNOPSIS
+.
.nf
.B "#include <mLib/tvec.h>"
.PP
.\" -*-nroff-*-
-.de VS
-.sp 1
-.RS
-.nf
-.ft B
-..
-.de VE
-.ft R
-.fi
-.RE
-.sp 1
-..
-.de hP
-.IP
-.ft B
-\h'-\w'\\$1\ 'u'\\$1\ \c
-.ft P
-..
-.ie t \{\
-. ds o \(bu
-. de VP
-. sp .4v
-..
-\}
-.el \{\
-. ds o o
-. de VP
-. sp
-..
-\}
-..
-.TH tvec-remote 3 "11 March 2024" "Straylight/Edgeware" "mLib utilities library"
-.SH NAME
-tvec-remote \- test vector framework remote invocation
+.\"
+.\" Manual for remote testing
+.\"
+.\" (c) 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 tvec-remote 3mLib "11 March 2024" "Straylight/Edgeware" "mLib utilities library"
.\" @TVEC_REMOTEENV
.\" @TVEC_FORK
.\" @TVEC_EXEC
.
.\" @tvec_remoteserver
.
+.\"--------------------------------------------------------------------------
+.SH NAME
+tvec-remote \- test vector framework remote invocation
+.
+.\"--------------------------------------------------------------------------
.SH SYNOPSIS
+.
.nf
.B "#include <mLib/tvec.h>"
.PP
+++ /dev/null
-.\" -*-nroff-*-
-.de VS
-.sp 1
-.RS
-.nf
-.ft B
-..
-.de VE
-.ft R
-.fi
-.RE
-.sp 1
-..
-.de hP
-.IP
-.ft B
-\h'-\w'\\$1\ 'u'\\$1\ \c
-.ft P
-..
-.ie t \{\
-. ds o \(bu
-. de VP
-. sp .4v
-..
-\}
-.el \{\
-. ds o o
-. de VP
-. sp
-..
-\}
-..
-.TH tvec-timeout 3 "11 March 2024" "Straylight/Edgeware" "mLib utilities library"
-.SH NAME
-tvec-timeout \- test vector framework timeouts
-.\" @TVEC_TIMEOUTENV
-.\" @TVEC_TIMEOUTINIT
-.
-.SH SYNOPSIS
-.nf
-.B "#include <mLib/tvec.h>"
-.PP
-.ta 2n
-.B "struct tvec_timeoutenv {"
-.B " struct tvec_env _env;"
-.B " int timer;"
-.B " double t;"
-.B " const struct tvec_env *env;"
-.B "};"
-.B "#define TVEC_TIMEOUTENV ..."
-.BI "#define TVEC_TIMEOUTINIT(" timer ", " t ") ..."
-.fi
--- /dev/null
+.\" -*-nroff-*-
+.\"
+.\" Manual for test timeouts
+.\"
+.\" (c) 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 tvec-timeout 3mLib "11 March 2024" "Straylight/Edgeware" "mLib utilities library"
+.\" @TVEC_TIMEOUTENV
+.\" @TVEC_TIMEOUTINIT
+.
+.\"--------------------------------------------------------------------------
+.SH NAME
+tvec-timeout \- test vector framework timeouts
+.
+.\"--------------------------------------------------------------------------
+.SH SYNOPSIS
+.
+.nf
+.B "#include <mLib/tvec.h>"
+.PP
+.ta 2n
+.B "struct tvec_timeoutenv {"
+.B " struct tvec_env _env;"
+.B " int timer;"
+.B " double t;"
+.B " const struct tvec_env *env;"
+.B "};"
+.B "#define TVEC_TIMEOUTENV ..."
+.BI "#define TVEC_TIMEOUTINIT(" timer ", " t ") ..."
+.fi
tvec_skip(tv, "failed to set interval timer: %s", strerror(errno));
else {
if (subenv && subenv->run) subenv->run(tv, fn, tc->subctx);
- else fn(tv->in, tv->out, tc->subctx);
+ else { fn(tv->in, tv->out, tc->subctx); tvec_check(tv, 0); }
itv.it_interval.tv_sec = 0; itv.it_interval.tv_usec = 0;
itv.it_value.tv_sec = 0; itv.it_value.tv_usec = 0;
.\" -*-nroff-*-
-.de VS
-.sp 1
-.RS
-.nf
-.ft B
-..
-.de VE
-.ft R
-.fi
-.RE
-.sp 1
-..
-.de hP
-.IP
-.ft B
-\h'-\w'\\$1\ 'u'\\$1\ \c
-.ft P
-..
-.ie t \{\
-. ds o \(bu
-. de VP
-. sp .4v
-..
-\}
-.el \{\
-. ds o o
-. de VP
-. sp
-..
-\}
-..
-.TH tvec-tyimpl 3 "11 March 2024" "Straylight/Edgeware" "mLib utilities library"
-.SH NAME
-tvec-tyimpl \- test vector framework type implementation
+.\"
+.\" Manual for test-vector framework register type interface
+.\"
+.\" (c) 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 tvec-tyimpl 3mLib "11 March 2024" "Straylight/Edgeware" "mLib utilities library"
.\" @tvec_syntax
.\" @tvec_syntax_v
.
.\" @tvec_readword
.\" @tvec_readword_v
.
+.\"--------------------------------------------------------------------------
+.SH NAME
+tvec-tyimpl \- test vector framework type implementation
+.
+.\"--------------------------------------------------------------------------
.SH SYNOPSIS
+.
.nf
.B "#include <mLib/tvec.h>"
.PP
.\" -*-nroff-*-
-.de VS
-.sp 1
-.RS
-.nf
-.ft B
-..
-.de VE
-.ft R
-.fi
-.RE
-.sp 1
-..
-.de hP
-.IP
-.ft B
-\h'-\w'\\$1\ 'u'\\$1\ \c
-.ft P
-..
-.ie t \{\
-. ds o \(bu
-. de VP
-. sp .4v
-..
-\}
-.el \{\
-. ds o o
-. de VP
-. sp
-..
-\}
-..
-.TH tvec-types 3 "11 March 2024" "Straylight/Edgeware" "mLib utilities library"
-.SH NAME
-tvec-types \- test vector framework provided register types
+.\"
+.\" Manual for test-vector framework types
+.\"
+.\" (c) 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 tvec-types 3mLib "11 March 2024" "Straylight/Edgeware" "mLib utilities library"
.\" @tvty_int
.\" @tvty_uint
.\" @tvty_float
.\" @tvec_initbuffer
.\" @tvec_allocbuffer
.
+.\"--------------------------------------------------------------------------
+.SH NAME
+tvec-types \- test vector framework provided register types
+.
+.\"--------------------------------------------------------------------------
.SH SYNOPSIS
+.
.nf
.B "#include <mLib/tvec.h>"
.PP
.BI "int TVEC_CLAIMEQ_UINT(struct tvec_state *" tv ,
.BI " unsigned long " u0 ", unsigned long " u1 );
.PP
+.B "const struct tvec_regty tvty_size;"
+.PP
+.ta \w'\fBint tvec_claimeq_size('u
+.BI "int tvec_claimeq_size(struct tvec_state *" tv ,
+.BI " unsigned long " sz0 ", unsigned long " sz1 ,
+.BI " const char *" file ", unsigned " lno ,
+.BI " const char *" expr );
+.ta \w'\fBint TVEC_CLAIMEQ_SIZE('u
+.BI "int TVEC_CLAIMEQ_UINT(struct tvec_state *" tv ,
+.BI " unsigned long " sz0 ", unsigned long " sz1 );
+.PP
.B "const struct tvec_regty tvty_float;"
.PP
.ta 2n
.PP
.BI "int tvec_parsedurunit(double *" scale_out ", const char **" p_inout );
.PP
+.ta \w'\fBint tvec_claimeqish_duration('u
+.BI "int tvec_claimeqish_duration(struct tvec_state *" tv ,
+.BI " double " t0 ", double " t1 ,
+.BI " unsigned " f ", double " delta ,
+.BI " const char *" file ", unsigned " lno ,
+.BI " const char *" expr );
+.ta \w'\fBint TVEC_CLAIMEQISH_DURATION('u
+.BI "int TVEC_CLAIMEQISH_DURATION(struct tvec_state *" tv ,
+.BI " double " t0 ", double " t1 ,
+.BI " unsigned " f ", double " delta );
+.ta \w'\fBint tvec_claimeq_duration('u
+.BI "int tvec_claimeq_duration(struct tvec_state *" tv ,
+.BI " double " t0 ", double " t1 ,
+.BI " const char *" file ", unsigned " lno ,
+.BI " const char *" expr );
+.ta \w'\fBint TVEC_CLAIMEQ_DURATION('u
+.BI "int TVEC_CLAIMEQ_DURATION(struct tvec_state *" tv ,
+.BI " double " t0 ", double " t1 );
+.PP
.B "const struct tvec_regty tvty_ienum, tvty_uenum, tvty_fenum, tvty_penum;"
.PP
.B "struct tvec_iassoc { const char *tag; long i; };"
* @const struct tvec_irange *ir@ = range specification,
* or null
* @struct tvec_state *tv@ = test vector state
+ * @const char *what@ = description of value
*
* Returns: Zero on success, or @-1@ on error.
*
static int check_signed_range(long i,
const struct tvec_irange *ir,
- struct tvec_state *tv)
+ struct tvec_state *tv, const char *what)
{
if (ir && (ir->min > i || i > ir->max)) {
- tvec_error(tv, "integer %ld out of range (must be in [%ld .. %ld])",
- i, ir->min, ir->max);
+ tvec_error(tv, "%s %ld out of range (must be in [%ld .. %ld])",
+ what, i, ir->min, ir->max);
return (-1);
}
return (0);
static int check_unsigned_range(unsigned long u,
const struct tvec_urange *ur,
- struct tvec_state *tv)
+ struct tvec_state *tv, const char *what)
{
if (ur && (ur->min > u || u > ur->max)) {
- tvec_error(tv, "integer %lu out of range (must be in [%lu .. %lu])",
- u, ur->min, ur->max);
+ tvec_error(tv, "%s %lu out of range (must be in [%lu .. %lu])",
+ what, u, ur->min, ur->max);
return (-1);
}
return (0);
if (parse_unsigned_integer(&u, &q, p))
return (tvec_error(tv, "invalid unsigned integer `%s'", p));
if (*q) return (tvec_syntax(tv, *q, "end-of-line"));
- if (check_unsigned_range(u, ur, tv)) return (-1);
+ if (check_unsigned_range(u, ur, tv, "integer")) return (-1);
*u_out = u; return (0);
}
if (parse_signed_integer(&i, &q, p))
return (tvec_error(tv, "invalid signed integer `%s'", p));
if (*q) return (tvec_syntax(tv, *q, "end-of-line"));
- if (check_signed_range(i, ir, tv)) return (-1);
+ if (check_signed_range(i, ir, tv, "integer")) return (-1);
*i_out = i; return (0);
}
static const char size_units[] = "kMGTPEZY";
-/* --- @parse_size@ --- *
+/* --- @parse_szint@ --- *
*
* Arguments: @struct tvec_state *tv@ = test-vector state
- * @size_t *u_out@ = where to put the answer
+ * @unsigned long *u_out@ = where to put the answer
* @const char *delims@ = delimiters
* @const char *what@ = description of what we're parsing
*
* Use: Parse a memory size.
*/
-static int parse_size(struct tvec_state *tv, size_t *u_out,
- const char *delims, const char *what)
+static int parse_szint(struct tvec_state *tv, unsigned long *u_out,
+ const char *delims, const char *what)
{
dstr d = DSTR_INIT;
const char *p, *unit;
if (parse_unsigned_integer(&u, &p, p)) goto bad;
if (!*p) tvec_readword(tv, &d, &p, delims, 0);
- if (u > (size_t)-1) goto rangerr;
for (t = u, unit = size_units; *unit; unit++) {
- if (t > (size_t)-1/1024) f |= f_range;
+ if (t > ULONG_MAX/1024) f |= f_range;
else t *= 1024;
if (*p == *unit) {
if (f&f_range) goto rangerr;
* Arguments: @double x, y@ = two numbers to compare
* @const struct tvec_floatinfo *fi@ = floating-point info
*
- * Returns: Nonzero if the comparand @y@ is sufficiently close to the
- * reference @x@, or zero if it's definitely different.
+ * Returns: Nonzero if the comparand @x@ is sufficiently close to the
+ * reference @y@, or zero if it's definitely different.
*/
static int eqish_floating_p(double x, double y,
case TVFF_ABSDELTA:
t = x - y; if (t < 0) t = -t; return (t < fi->delta);
case TVFF_RELDELTA:
- t = 1.0 - y/x; if (t < 0) t = -t; return (t < fi->delta);
+ t = 1.0 - x/y; if (t < 0) t = -t; return (t < fi->delta);
default:
abort();
}
return (tvec_claimeq(tv, &tvty_uint, 0, file, lno, expr));
}
+/*----- Size type ---------------------------------------------------------*/
+
+/* --- @parse_size@ --- *
+ *
+ * Arguments: @union tvec_regval *rv@ = register value
+ * @const struct tvec_regdef *rd@ = register definition
+ * @struct tvec_state *tv@ = test-vector state
+ *
+ * Returns: Zero on success, %$-1$% on error.
+ *
+ * Use: Parse a register value from an input file.
+ *
+ * The input format for a size value consists of an unsigned
+ * integer followed by an optional unit specifier consisting of
+ * an SI unit prefix and (optionally) the letter `B'. */
+
+static int parse_size(union tvec_regval *rv, const struct tvec_regdef *rd,
+ struct tvec_state *tv)
+{
+ unsigned long sz;
+ int rc;
+
+ if (parse_szint(tv, &sz, ";", "size")) { rc = -1; goto end; }
+ if (check_unsigned_range(sz, rd->arg.p, tv, "size")) { rc = -1; goto end; }
+ if (tvec_flushtoeol(tv, 0)) { rc = -1; goto end; }
+ rv->u = sz; rc = 0;
+end:
+ return (rc);
+}
+
+/* --- @dump_size@ --- *
+ *
+ * Arguments: @const union tvec_regval *rv@ = register value
+ * @const struct tvec_regdef *rd@ = register definition
+ * @unsigned style@ = output style (@TVSF_...@)
+ * @const struct gprintf_ops *gops@, @void *gp@ = format output
+ *
+ * Returns: ---
+ *
+ * Use: Dump a register value to the format output.
+ *
+ * Size values are dumped with a unit specifier, with a unit
+ * prefox only if the size is an exact multiple of the relevant
+ * power of two. Unless compact style is requested, the plain
+ * decimal and hex representations of the value are also
+ * printed.
+ */
+
+static void dump_size(const union tvec_regval *rv,
+ const struct tvec_regdef *rd,
+ unsigned style,
+ const struct gprintf_ops *gops, void *go)
+{
+ format_size(gops, go, rv->u, style);
+ if (!(style&TVSF_COMPACT)) {
+ gprintf(gops, go, " ; = %lu", (unsigned long)rv->u);
+ gprintf(gops, go, " = "); format_unsigned_hex(gops, go, rv->u);
+ maybe_format_unsigned_char(gops, go, rv->u);
+ }
+}
+
+/* Size type definitions. */
+const struct tvec_regty tvty_size = {
+ init_uint, trivial_release, eq_uint,
+ tobuf_uint, frombuf_uint,
+ parse_size, dump_size
+};
+
+/* --- @tvec_claimeq_size@ --- *
+ *
+ * Arguments: @struct tvec_state *tv@ = test-vector state
+ * @unsigned long sz0, sz1@ = two sizes
+ * @const char *file@, @unsigned @lno@ = calling file and line
+ * @const char *expr@ = the expression to quote on failure
+ *
+ * Returns: Nonzero if @sz0@ and @sz1@ are equal, otherwise zero.
+ *
+ * Use: Check that values of @u0@ and @u1@ are equal. As for
+ * @tvec_claim@ above, a test case is automatically begun and
+ * ended if none is already underway. If the values are
+ * unequal, then @tvec_fail@ is called, quoting @expr@, and the
+ * mismatched values are dumped: @u0@ is printed as the output
+ * value and @u1@ is printed as the input reference.
+ */
+
+int tvec_claimeq_size(struct tvec_state *tv,
+ unsigned long sz0, unsigned long sz1,
+ const char *file, unsigned lno, const char *expr)
+{
+ tv->out[0].v.u = sz0; tv->in[0].v.u = sz1;
+ return (tvec_claimeq(tv, &tvty_size, 0, file, lno, expr));
+}
+
/*----- Floating-point type -----------------------------------------------*/
/* --- @int_float@ --- *
* @const char *file@, @unsigned @lno@ = calling file and line
* @const char *expr@ = the expression to quote on failure
*
- * Returns: Nonzero if @f0@ and @u1@ are sufficiently close, otherwise
+ * Returns: Nonzero if @f0@ and @f1@ are sufficiently close, otherwise
* zero.
*
* Use: Check that values of @f0@ and @f1@ are sufficiently close.
* %$y$% when %$|x - y| < \delta$%.
*
* * If @f&TVFF_EQMASK@ is @TVFF_RELDELTA@, then %$x$% matches
- * %$y$% when %$|1 - y/x| < \delta$%. (Note that this
- * criterion is asymmetric FIXME
+ * %$y$% when %$|1 - x/y| < \delta$%. (Note that this
+ * criterion is asymmetric. Write %$x \approx_\delta y$%
+ * if and only if %$|1 - x/y < \delta$%. Then, for example,
+ * if %$y/(1 + \delta) < x < y (1 - \delta)$%, then
+ * %$x \approx_\delta y$%, but %$y \not\approx_\delta x$%.)
*/
int tvec_claimeqish_float(struct tvec_state *tv,
* @const char *file@, @unsigned @lno@ = calling file and line
* @const char *expr@ = the expression to quote on failure
*
- * Returns: Nonzero if @f0@ and @u1@ are identical, otherwise zero.
+ * Returns: Nonzero if @f0@ and @f1@ are identical, otherwise zero.
*
* Use: Check that values of @f0@ and @f1@ are identical. The
* function is exactly equivalent to @tvec_claimeqish_float@
parse_duration, dump_duration
};
+/* --- @tvec_claimeqish_duration@ --- *
+ *
+ * Arguments: @struct tvec_state *tv@ = test-vector state
+ * @double to, t1@ = two durations
+ * @unsigned f@ = flags (@TVFF_...@)
+ * @double delta@ = maximum tolerable difference
+ * @const char *file@, @unsigned @lno@ = calling file and line
+ * @const char *expr@ = the expression to quote on failure
+ *
+ * Returns: Nonzero if @t0@ and @t1@ are sufficiently close, otherwise
+ * zero.
+ *
+ * Use: Check that values of @t0@ and @t1@ are sufficiently close.
+ * This is essentially the same as @tvec_claimeqish_float@, only
+ * it dumps the values as durations on a mismatch.
+ */
+
+int tvec_claimeqish_duration(struct tvec_state *tv,
+ double t0, double t1, unsigned f, double delta,
+ const char *file, unsigned lno,
+ const char *expr)
+{
+ struct tvec_floatinfo fi;
+ union tvec_misc arg;
+
+ fi.f = f; fi.min = fi.max = 0.0; fi.delta = delta; arg.p = &fi;
+ tv->out[0].v.f = t0; tv->in[0].v.f = t1;
+ return (tvec_claimeq(tv, &tvty_duration, &arg, file, lno, expr));
+}
+
+/* --- @tvec_claimeq_duration@ --- *
+ *
+ * Arguments: @struct tvec_state *tv@ = test-vector state
+ * @double t0, t1@ = two durations
+ * @const char *file@, @unsigned @lno@ = calling file and line
+ * @const char *expr@ = the expression to quote on failure
+ *
+ * Returns: Nonzero if @t0@ and @t1@ are identical, otherwise zero.
+ *
+ * Use: Check that values of @t0@ and @t1@ are identical. The
+ * function is exactly equivalent to @tvec_claimeqish_duration@
+ * with @f == TVFF_EXACT@.
+ */
+
+int tvec_claimeq_duration(struct tvec_state *tv,
+ double t0, double t1,
+ const char *file, unsigned lno,
+ const char *expr)
+{
+ return (tvec_claimeqish_duration(tv, t0, t1, TVFF_EXACT, 0.0,
+ file, lno, expr));
+}
+
/*----- Enumerations ------------------------------------------------------*/
/* --- @init_tenum@ --- *
*
* Use: Parse a register value from an input file.
*
- * The input format for a buffer value consists of an unsigned
- * integer followed by an optional unit specifier consisting of
- * an SI unit prefix and (optionally) the letter `B'. Unit
- * prefixes denote %%\emph{binary}%% multipliers, not decimal.
+ * The input format for a buffer value is a size, followed by an
+ * optional `%|@$%' and an alignment quantum and a further
+ * optional `%|+|%' and an alignment offset. The size, quantum,
+ * and offset are syntactically sizes.
*
- * The buffer is allocated and filled with a distinctive
- * pattern.
+ * The buffer is not allocated.
*/
static int parse_buffer(union tvec_regval *rv,
const struct tvec_regdef *rd,
struct tvec_state *tv)
{
- size_t sz, a = 0, m = 0;
+ unsigned long sz, a = 0, m = 0;
int ch, rc;
- if (parse_size(tv, &sz, "@;", "buffer length")) { rc = -1; goto end; }
+ if (parse_szint(tv, &sz, "@;", "buffer length")) { rc = -1; goto end; }
+ if (check_unsigned_range(sz, &tvrange_size, tv, "buffer length"))
+ { rc = -1; goto end; }
if (check_string_length(sz, rd->arg.p, tv)) { rc = -1; goto end; }
tvec_skipspc(tv);
if (ch == ';' || ch == '\n') { ungetc(ch, tv->fp); goto done; }
else if (ch != '@') { rc = tvec_syntax(tv, ch, "`@'"); goto end; }
- if (parse_size(tv, &m, "+;", "alignment quantum")) { rc = -1; goto end; }
+ if (parse_szint(tv, &m, "+;", "alignment quantum")) { rc = -1; goto end; }
+ if (check_unsigned_range(a, &tvrange_size, tv, "alignment quantum"))
+ { rc = -1; goto end; }
if (m == 1) m = 0;
tvec_skipspc(tv);
if (ch == ';' || ch == '\n') { ungetc(ch, tv->fp); goto done; }
else if (ch != '+') { rc = tvec_syntax(tv, ch, "`+'"); goto end; }
- if (parse_size(tv, &a, ";", "alignment offset")) { rc = -1; goto end; }
+ if (parse_szint(tv, &a, ";", "alignment offset")) { rc = -1; goto end; }
+ if (check_unsigned_range(m, &tvrange_size, tv, "alignment offset"))
+ { rc = -1; goto end; }
if (a >= m) {
rc = tvec_error(tv, "alignment offset %lu >= quantum %lu",
(unsigned long)a, (unsigned long)m);
*
* Use: Dump a register value to the format output.
*
- * Buffer values are dumped as their size with an appropriate
- * unit specifier. A unit prefix is only used if the size is an
- * exact multiple of the relevant power of two.
+ * Buffer values are dumped as their size, with the alignment
+ * quantum and alignment offset if these are non-default.
*/
static void dump_buffer(const union tvec_regval *rv,
+++ /dev/null
-.\" -*-nroff-*-
-.de VS
-.sp 1
-.RS
-.nf
-.ft B
-..
-.de VE
-.ft R
-.fi
-.RE
-.sp 1
-..
-.de hP
-.IP
-.ft B
-\h'-\w'\\$1\ 'u'\\$1\ \c
-.ft P
-..
-.ie t \{\
-. ds o \(bu
-. de VP
-. sp .4v
-..
-\}
-.el \{\
-. ds o o
-. de VP
-. sp
-..
-\}
-..
-.TH tvec 3 "11 March 2024" "Straylight/Edgeware" "mLib utilities library"
-.SH NAME
-tvec \- test vector framework
-.\" @tvec_begin
-.\" @tvec_end
-.\" @tvec_read
-.\" @tvec_humanoutput
-.\" @tvec_tapoutput
-.\" @tvec_dfltoutput
-.
-.SH SYNOPSIS
-.nf
-.B "#include <mLib/tvec.h>"
-.PP
-.ta 2n
-.B "union tvec_misc {"
-.B " const void *p;"
-.B " long i;"
-.B " unsigned long u;"
-.B " double f;"
-.B "};"
-.B "enum {"
-.B " TVMISC_PTR,"
-.B " TVMISC_INT,"
-.B " TVMISC_UINT,"
-.B " TVMISC_FLT,"
-.B " ...,"
-.B " TVMISC_LIMIT,"
-.B "};"
-.PP
-.ta 2n +2n
-.B "union tvec_regval {"
-.B " long i;"
-.B " unsigned long u;"
-.B " void *p;"
-.B " double f;"
-.B " struct { char *p; size_t sz; } text;"
-.B " struct { unsigned char *p; size_t sz; } bytes;"
-.B " struct {"
-.B " unsigned char *p; size_t sz;"
-.B " size_t a, m;"
-.B " size_t off;"
-.B " } buf;"
-.B " TVEC_REGSLOTS"
-.B "};"
-.B "struct tvec_reg {"
-.B " unsigned f;"
-.B " union tvec_regval v;"
-.B "};"
-.B "#define TVRF_LIVE ..."
-.PP
-.ta 2n
-.B "struct tvec_regdef {"
-.B " const char *name;"
-.B " const struct tvec_regty *ty;"
-.B " unsigned i;"
-.B " unsigned f;"
-.B " union tvec_misc arg;"
-.B "};"
-.B "#define TVRF_OPT ..."
-.B "#define TVRF_ID ..."
-.B "#define TVEC_ENDREGS ..."
-.PP
-.B "struct tvec_state;"
-.PP
-.B "struct tvec_env;"
-.ta \w'\fBtypedef void tvec_testfn('u
-.BI "typedef void tvec_testfn(const struct tvec_reg *" in ,
-.BI " struct tvec_reg *" out ,
-.BI " void *" ctx );
-.B "struct tvec_test {"
-.B " const char *name;"
-.B " const struct tvec_regdef *regs;"
-.B " const struct tvec_env *env;"
-.B " tvec_testfn *fn;"
-.B "};"
-.B "#define TVEC_ENDTESTS ..."
-.PP
-.ta 2n
-.B "struct tvec_config {"
-.B " const struct tvec_test *tests;"
-.B " unsigned nrout, nreg;"
-.B " size_t regsz;"
-.B "};"
-.B "struct tvec_output;"
-.PP
-.ta \w'\fBvoid tvec_begin('u
-.BI "void tvec_begin(struct tvec_state *" tv_out ,
-.BI " const struct tvec_config *" config ,
-.BI " struct tvec_output *" o );
-.BI "int tvec_end(struct tvec_state *" tv );
-.BI "int tvec_read(struct tvec_state *" tv ", const char *" infile ", FILE *" fp );
-.PP
-.BI "extern struct tvec_output *tvec_humanoutput(FILE *" fp );
-.BI "extern struct tvec_output *tvec_tapoutput(FILE *" fp );
-.BI "extern struct tvec_output *tvec_dfltoutput(FILE *" fp );
-.fi
--- /dev/null
+.\" -*-nroff-*-
+.\"
+.\" Manual for the test vector framework
+.\"
+.\" (c) 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 tvec 3mLib "11 March 2024" "Straylight/Edgeware" "mLib utilities library"
+.
+.\"--------------------------------------------------------------------------
+.SH NAME
+tvec \- test vector framework
+.\" @tvec_begin
+.\" @tvec_end
+.\" @tvec_read
+.\" @tvec_humanoutput
+.\" @tvec_tapoutput
+.\" @tvec_dfltoutput
+.
+.\"--------------------------------------------------------------------------
+.SH SYNOPSIS
+.nf
+.B "#include <mLib/tvec.h>"
+.PP
+.ta 2n
+.B "union tvec_misc {"
+.B " const void *p;"
+.B " long i;"
+.B " unsigned long u;"
+.B " double f;"
+.B "};"
+.B "enum {"
+.B " TVMISC_PTR,"
+.B " TVMISC_INT,"
+.B " TVMISC_UINT,"
+.B " TVMISC_FLT,"
+.B " ...,"
+.B " TVMISC_LIMIT,"
+.B "};"
+.PP
+.ta 2n +2n
+.B "union tvec_regval {"
+.B " long i;"
+.B " unsigned long u;"
+.B " void *p;"
+.B " double f;"
+.B " struct { char *p; size_t sz; } text;"
+.B " struct { unsigned char *p; size_t sz; } bytes;"
+.B " struct {"
+.B " unsigned char *p; size_t sz;"
+.B " size_t a, m;"
+.B " size_t off;"
+.B " } buf;"
+.B " TVEC_REGSLOTS"
+.B "};"
+.B "struct tvec_reg {"
+.B " unsigned f;"
+.B " union tvec_regval v;"
+.B "};"
+.B "#define TVRF_LIVE ..."
+.PP
+.ta 2n
+.B "struct tvec_regdef {"
+.B " const char *name;"
+.B " const struct tvec_regty *ty;"
+.B " unsigned i;"
+.B " unsigned f;"
+.B " union tvec_misc arg;"
+.B "};"
+.B "#define TVRF_UNSET ..."
+.B "#define TVRF_OPT ..."
+.B "#define TVRF_ID ..."
+.B "#define TVEC_ENDREGS ..."
+.PP
+.B "struct tvec_state;"
+.PP
+.B "struct tvec_env;"
+.ta \w'\fBtypedef void tvec_testfn('u
+.BI "typedef void tvec_testfn(const struct tvec_reg *" in ,
+.BI " struct tvec_reg *" out ,
+.BI " void *" ctx );
+.ta 2n
+.B "struct tvec_test {"
+.B " const char *name;"
+.B " const struct tvec_regdef *regs;"
+.B " const struct tvec_env *env;"
+.B " tvec_testfn *fn;"
+.B "};"
+.B "#define TVEC_ENDTESTS ..."
+.PP
+.ta 2n
+.B "struct tvec_config {"
+.B " const struct tvec_test *tests;"
+.B " unsigned nrout, nreg;"
+.B " size_t regsz;"
+.B "};"
+.B "struct tvec_output;"
+.PP
+.ta \w'\fBvoid tvec_begin('u
+.BI "void tvec_begin(struct tvec_state *" tv_out ,
+.BI " const struct tvec_config *" config ,
+.BI " struct tvec_output *" o );
+.BI "int tvec_end(struct tvec_state *" tv );
+.BI "int tvec_read(struct tvec_state *" tv ", const char *" infile ", FILE *" fp );
+.PP
+.BI "extern struct tvec_output *tvec_humanoutput(FILE *" fp );
+.BI "extern struct tvec_output *tvec_tapoutput(FILE *" fp );
+.BI "extern struct tvec_output *tvec_dfltoutput(FILE *" fp );
+.fi
+.
+.\"--------------------------------------------------------------------------
+.SH DESCRIPTION
+.
+The
+.B <mLib/tvec.h>
+header file provides definitions and declarations
+for the core of mLib's
+.IR "test vector framework" .
+.PP
+The test vector framework is rather large and complicated,
+so the documentation for it is split into multiple manual pages.
+This one provides a conceptual overview
+and describes the essentials for using it to build simple tests.
+.
+.SS Conceptual overview
+A
+.I "test session"
+runs a collection of tests
+and reports on the outcome.
+.PP
+A
+.I test
+involves exercising some functionality
+and checking that it behaves properly.
+A test can have four
+.IR outcomes .
+It can
+.IR pass :
+the functionality behaved properly.
+It can
+.IR fail :
+the functionality did not behave properly.
+It can experience an
+.IR "expected failure" :
+the functionality behaved as expected,
+but the expected behaviour is known to be incorrect.
+Or it can be
+.IR skipped :
+for some reason, the test couldn't be performed.
+.PP
+Tests are gathered together into
+.IR "test groups" .
+Each test group has a name.
+Like a individual tests, test groups also have outcomes:
+they can pass, fail, or be skipped.
+A test group cannot experience expected failure.
+.PP
+A session may also encounter
+.IR errors ,
+e.g., as a result of malformed input
+or failures reported by system facilities.
+.PP
+A test session can either
+be driven from data provided by an input file,
+or it can be driven by the program alone.
+The latter case is called
+.I "ad-hoc testing",
+and is described in
+.BR tvec-adhoc (3).
+This manual page describes file-driven testing.
+.PP
+When it begins a session for file-directed testing,
+the program provides a table of
+.IR "test definitions" .
+A test definition has a
+.IR name ,
+and also specifies a
+.IR "test function" ,
+a
+.IR "test environment" ,
+and a table of
+.IR "register definitions" .
+Test environments are explained further below.
+.PP
+A
+.I register
+is a place which can store a single item of test data;
+registers are the means
+by which input test data is provided to a test function,
+and by which a test function returns its results.
+A test definition's register definitions
+establish a collection of
+.I active
+registers.
+Each active register has a
+.IR name ,
+an
+.IR index ,
+and a
+.IR type ,
+which are established by its register definition.
+The register's name is used to refer to the register in the test data file,
+and its index is used to refer to it
+in the test function and test environments.
+The register's type describes the acceptable values for the register,
+and how they are to be compared,
+read from the input file,
+and dumped in diagnostic output.
+New register types can be defined fairly easily: see
+.BR tvec_tyimpl (3)
+for the details.
+A register definition may describe an
+.I input
+register or an
+.I output
+register:
+input registers provide input data to the test function, while
+output registers collect output data from the test function.
+The data file provides values for both input and output registers:
+the values for the input registers are passed to the test function;
+the values for the output registers are
+.I "reference outputs"
+against which the test function's outputs are to be checked.
+.PP
+The test function is called with two vectors of registers,
+one containing input values for the test function to read,
+and another for output values that the test function should write;
+and a
+.I context
+provided by the test environment.
+The test function's task is to exercise the functionality to be tested,
+providing it the input data from its input registers,
+and collecting the output in its output registers.
+It is the responsibility of the test environment or the framework
+to compare the output register values against reference values
+provided in the input data.
+.PP
+The input file syntax is described in full below.
+In overview, it is a
+.BR .ini -style
+file.
+Comments begin with a semicolon character
+.RB ` ; ',
+and extend to the end of the line.
+It is divided into
+.I sections
+by headings in square brackets:
+.IP
+.BR [ test ]
+.PP
+Each section contains a number of
+.I paragraphs
+separated by blank lines.
+Each paragraph consists of one or more
+.I assignments
+of the form
+.IP
+.IB reg " = " value
+.PP
+or
+.IP
+.IB reg ": " value
+.PP
+When the framework encounters a section heading,
+it finishes any test group currently in progress,
+and searches for a test definition whose name matches the
+.I test
+name in the section heading.
+If it finds a match,
+it begins a new test group with the same name.
+Each paragraph of assignments is used to provide
+input and reference output values
+for a single test.
+The
+.I reg
+name in an assignment must match the name of an active register;
+the corresponding
+.I value
+is stored in the named register.
+.PP
*/
unsigned f; /* flags */
-#define TVRF_LIVE 1u /* used in current test */
+#define TVRF_SEEN 1u /* assignment seen in file */
+#define TVRF_LIVE 2u /* used in current test */
union tvec_regval v; /* register value */
};
const struct tvec_regty *ty; /* register type descriptor */
unsigned i; /* register index */
unsigned f; /* flags */
-#define TVRF_OPT 1u /* optional register */
-#define TVRF_ID 2u /* part of test identity */
+#define TVRF_UNSET 1u /* register may be marked unset */
+#define TVRF_OPT 2u /* register need not be assigned */
+#define TVRF_ID 4u /* part of test identity */
union tvec_misc arg; /* extra detail for the type */
};
#define TVEC_ENDREGS { 0, 0, 0, 0, { 0 } }
void (*init)(union tvec_regval */*rv*/, const struct tvec_regdef */*rd*/);
/* Initialize the value in @*rv@. This will be called before any other
- * function acting on the value, including @release@.
+ * function acting on the value, including @release@. Following @init@,
+ * the register value must be valid to use for all other type entry
+ * points.
*/
void (*release)(union tvec_regval */*rv*/,
const struct tvec_regdef */*rd*/);
- /* Release any resources associated with the value in @*rv@. */
+ /* Release any resources associated with the value in @*rv@. The
+ * register value may be left in an invalid state.
+ */
int (*eq)(const union tvec_regval */*rv0*/,
const union tvec_regval */*rv1*/,
#define TVEC_CLAIMEQ_UINT(tv, u0, u1) \
(tvec_claimeq_uint(tv, u0, u1, __FILE__, __LINE__, #u0 " /= " #u1))
+/*----- Size type ---------------------------------------------------------*/
+
+/* A size is an unsigned integer followed by an optional unit specifier
+ * consisting of an SI unit prefix and (optionally) the letter `B'.
+ */
+
+extern const struct tvec_regty tvty_size;
+
+/* --- @tvec_claimeq_size@ --- *
+ *
+ * Arguments: @struct tvec_state *tv@ = test-vector state
+ * @unsigned long sz0, sz1@ = two sizes
+ * @const char *file@, @unsigned @lno@ = calling file and line
+ * @const char *expr@ = the expression to quote on failure
+ *
+ * Returns: Nonzero if @sz0@ and @sz1@ are equal, otherwise zero.
+ *
+ * Use: Check that values of @u0@ and @u1@ are equal. As for
+ * @tvec_claim@ above, a test case is automatically begun and
+ * ended if none is already underway. If the values are
+ * unequal, then @tvec_fail@ is called, quoting @expr@, and the
+ * mismatched values are dumped: @u0@ is printed as the output
+ * value and @u1@ is printed as the input reference.
+ *
+ * The @TVEC_CLAIM_SIZE@ macro is similar, only it (a)
+ * identifies the file and line number of the call site
+ * automatically, and (b) implicitly quotes the source text of
+ * the @u0@ and @u1@ arguments in the failure message.
+ */
+
+int tvec_claimeq_size(struct tvec_state *tv,
+ unsigned long sz0, unsigned long sz1,
+ const char *file, unsigned lno, const char *expr);
+#define TVEC_CLAIMEQ_UINT(tv, u0, u1) \
+ (tvec_claimeq_uint(tv, u0, u1, __FILE__, __LINE__, #u0 " /= " #u1))
+
/*----- Floating-point type -----------------------------------------------*/
/* Floating-point values are either NaN (%|#nan|%, if supported by the
* @const char *file@, @unsigned @lno@ = calling file and line
* @const char *expr@ = the expression to quote on failure
*
- * Returns: Nonzero if @f0@ and @u1@ are sufficiently close, otherwise
+ * Returns: Nonzero if @f0@ and @f1@ are sufficiently close, otherwise
* zero.
*
* Use: Check that values of @f0@ and @f1@ are sufficiently close.
* %$y$% when %$|x - y| < \delta$%.
*
* * If @f&TVFF_EQMASK@ is @TVFF_RELDELTA@, then %$x$% matches
- * %$y$% when %$|1 - y/x| < \delta$%. (Note that this
- * criterion is asymmetric FIXME
+ * %$y$% when %$|1 - x/y| < \delta$%. (Note that this
+ * criterion is asymmetric. Write %$x \approx_\delta y$%
+ * if and only if %$|1 - x/y < \delta$%. Then, for example,
+ * if %$y/(1 + \delta) < x < y (1 - \delta)$%, then
+ * %$x \approx_\delta y$%, but %$y \not\approx_\delta x$%.)
*
* The @TVEC_CLAIM_FLOAT@ macro is similar, only it (a)
* identifies the file and line number of the call site
const char */*file*/, unsigned /*lno*/,
const char */*expr*/);
#define TVEC_CLAIMEQISH_FLOAT(tv, f0, f1, f, delta) \
- (tvec_claimeqish_float(tv, f0, f1, f, delta, , __FILE__, __LINE__, \
+ (tvec_claimeqish_float(tv, f0, f1, f, delta, __FILE__, __LINE__, \
#f0 " /= " #f1 " (+/- " #delta ")"))
/* --- @tvec_claimeq_float@, @TVEC_CLAIMEQ_FLOAT@ --- *
/* A duration measures a time interval in seconds. The input format consists
* of a nonnegative decimal floating-point number in @strtod@ format followed
* by an optional unit specification.
- *
- * No @tvec_claimeq_...@ function is provided for durations: use
- * @tvec_claimeq_float@.
*/
extern const struct tvec_regty tvty_duration;
extern int tvec_parsedurunit(double */*scale_out*/,
const char **/*p_inout*/);
+/* --- @tvec_claimeqish_duration@, @TVEC_CLAIMEQISH_DURATION@ --- *
+ *
+ * Arguments: @struct tvec_state *tv@ = test-vector state
+ * @double to, t1@ = two durations
+ * @unsigned f@ = flags (@TVFF_...@)
+ * @double delta@ = maximum tolerable difference
+ * @const char *file@, @unsigned @lno@ = calling file and line
+ * @const char *expr@ = the expression to quote on failure
+ *
+ * Returns: Nonzero if @t0@ and @t1@ are sufficiently close, otherwise
+ * zero.
+ *
+ * Use: Check that values of @t0@ and @t1@ are sufficiently close.
+ * This is essentially the same as @tvec_claimeqish_float@, only
+ * it dumps the values as durations on a mismatch.
+ *
+ * The @TVEC_CLAIM_FLOAT@ macro is similar, only it (a)
+ * identifies the file and line number of the call site
+ * automatically, and (b) implicitly quotes the source text of
+ * the @t0@ and @t1@ arguments (and @delta@) in the failure
+ * message.
+ */
+
+extern int tvec_claimeqish_duration(struct tvec_state */*tv*/,
+ double /*t0*/, double /*t1*/,
+ unsigned /*f*/, double /*delta*/,
+ const char */*file*/, unsigned /*lno*/,
+ const char */*expr*/);
+#define TVEC_CLAIMEQISH_DURATION(tv, t0, t1, f, delta) \
+ (tvec_claimeqish_duration(tv, t0, t1, f, delta, __FILE__, __LINE__, \
+ #t0 " /= " #t1 " (+/- " #delta ")"))
+
+/* --- @tvec_claimeq_duration@, @TVEC_CLAIMEQ_DURATION@ --- *
+ *
+ * Arguments: @struct tvec_state *tv@ = test-vector state
+ * @double t0, t1@ = two durations
+ * @const char *file@, @unsigned @lno@ = calling file and line
+ * @const char *expr@ = the expression to quote on failure
+ *
+ * Returns: Nonzero if @t0@ and @t1@ are identical, otherwise zero.
+ *
+ * Use: Check that values of @t0@ and @t1@ are identical. The
+ * function is exactly equivalent to @tvec_claimeqish_duration@
+ * with @f == TVFF_EXACT@; the macro is similarly like
+ * @TVEC_CLAIMEQISH_DURATION@ with @f == TVFF_EXACT@, except
+ * that it doesn't bother to quote a delta.
+ */
+
+int tvec_claimeq_duration(struct tvec_state */*tv*/,
+ double /*t0*/, double /*t1*/,
+ const char */*file*/, unsigned /*lno*/,
+ const char */*expr*/);
+#define TVEC_CLAIMEQ_DURATION(tv, t0, t1) \
+ (tvec_claimeq_float(tv, t0, t1, __FILE__, __LINE__, #t0 " /= " #t1))
+
/*----- Enumerated types --------------------------------------------------*/
/* An enumeration describes a set of values of some underlying type, each of
## Tracing.
pkginclude_HEADERS += trace.h
libtrace_la_SOURCES += trace.c traceopt.c
+EXTRA_DIST += trace.3.in
LIBMANS += trace.3
###----- That's all, folks --------------------------------------------------
.\" -*-nroff-*-
-.TH trace 3 "21 October 1999" "Straylight/Edgeware" "mLib utilities library"
-.SH "NAME"
-trace \- configurable tracing output
+.\"
+.\" Manual for tracing
+.\"
+.\" (c) 1999, 2001, 2005, 2009, 2017, 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 trace 3mLib "21 October 1999" "Straylight/Edgeware" "mLib utilities library"
.\" @trace
.\" @trace_block
.\" @trace_on
.\" @NTRACE
.\" @T
.\" IF_TRACING
+.
+.\"--------------------------------------------------------------------------
+.SH "NAME"
+trace \- configurable tracing output
+.
+.\"--------------------------------------------------------------------------
.SH "SYNOPSIS"
+.
.nf
.B "#include <mLib/trace.h>"
.PP
.BI T( statements\fR... )
.BI "IF_TRACING(unsigned " l ", " statements\fR... )
.fi
+.
+.\"--------------------------------------------------------------------------
.SH "DESCRIPTION"
+.
The
.B <mLib/trace.h>
header declares some functions and macros for handling trace output.
message level and the overall tracing level is nonzero. The idea is
that the programmer assigns a different bit to each group of trace
messages, and allows a user to select which ones are wanted.
+.
.SS "Producing trace output"
The basic function is
.BR trace .
in order, the message level, a pointer to the header string for the hex
dump, the base address of the block to dump, and the size of the block
in bytes.
+.
.SS "Configuring trace output"
The tracing destination is set with the function
.BR trace_on :
.B trace_custom
and passing a function which will write a buffer of data somewhere
sensible.
+.
.SS "Parsing user trace options"
The function
.B traceopt
.I bad
mask to prevent access to secret information when running setuid, or to
zero when not.
+.
.SS "Macro support for tracing"
The tracing macros are intended to make insertion of tracing information
unobtrusive and painless. If the
level is set such that the message will be printed, the code in the
second argument is executed. If code is being compiled without tracing,
of course, the entire contents of the macro is ignored.
+.
+.\"--------------------------------------------------------------------------
.SH "SEE ALSO"
+.
.BR mLib (3).
+.
+.\"--------------------------------------------------------------------------
.SH "AUTHOR"
+.
Mark Wooding, <mdw@distorted.org.uk>
+.
+.\"----- That's all, folks --------------------------------------------------
libmdwopt_la_SOURCES = mdwopt.c
libmdwopt_la_CPPFLAGS = $(AM_CPPFLAGS) -DBUILDING_MLIB
libui_la_LIBADD += libmdwopt.la
+EXTRA_DIST += mdwopt.3.in
LIBMANS += mdwopt.3
## Program naming.
pkginclude_HEADERS += quis.h
libui_la_SOURCES += quis.c pquis.c
+EXTRA_DIST += quis.3.in
LIBMANS += quis.3
## Error reporting.
pkginclude_HEADERS += report.h
libui_la_SOURCES += report.c
+EXTRA_DIST += report.3.in
LIBMANS += report.3
###----- That's all, folks --------------------------------------------------
.\" -*-nroff-*-
-.TH mdwopt 3 "6 July 1999" "Straylight/Edgeware" "mLib utilities library"
+.\"
+.\" Manual for option parsing
+.\"
+.\" (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 mdwopt 3mLib "6 July 1999" "Straylight/Edgeware" "mLib utilities library"
+.\" @mdwopt
+.
+.\"--------------------------------------------------------------------------
.SH "NAME"
mdwopt \- command-line option parser
-.\" @mdwopt
+.
+.\"--------------------------------------------------------------------------
.SH "SYNOPSIS"
+.
.nf
.B "#include <mLib/mdwopt.h>"
.PP
.BI " const char * "shortopt ,
.BI " const struct option *" longopt ", int *" longind );
.fi
+.
+.\"--------------------------------------------------------------------------
.SH "OVERVIEW"
+.
The
.B mdwopt
function is a command line options parser which is (mostly) compatible
functions, although provides more features than either. It's not the
most featureful options parser around, but it's good enough for my
purposes at the moment.
+.
+.\"--------------------------------------------------------------------------
.SH "OPTION SYNTAX"
+.
A command line consists of a number of
.I words
(which may contain spaces, according to various shell quoting
.IR long .
Traditional Unix (and POSIX) only uses short options. The long options
are a GNU convention.
+.
.SS "Short option syntax"
Short options are the sort which Unix has known for ages: an option is a
single letter, preceded by a
.RB ` \- '
to introduce the option. (Some programs use upper-case option letters
to indicate this instead.)
+.
.SS "Long option syntax"
Long options, as popularized by the GNU utilities, are given long-ish
memorable names, preceded by a double-dash
character, and negated by a
.RB ` + '
character.
+.
.SS "Numerical options"
Finally, some (older) programs accept arguments of the form
.RB ` \- \c
.IR number ',
to set some numerical parameter, typically a line count of some kind.
+.
+.\"--------------------------------------------------------------------------
.SH "PARSING OPTIONS WITH \fBmdwopt\fP"
+.
An application parses its options by calling
.B mdwopt
repeatedly. Each time it is called,
will usually be exactly the arguments passed to the program's
.B main
function.
+.
.SS "Short option parsing"
Short options are described by a string,
.IR shortopt ,
returned ORed with
.B OPTF_NEGATED
(bit 8 set).
+.
.SS "Long option parsing"
Long options are described in a table. Each entry in the
table is of type
Arguments from long options are stored in the
.B arg
member of the data block.
+.
.SS "Other optional features"
The
.I flags
.RB ` \- '.
The return value is
.RB ` # ' " | OPTF_NEGATED" .
+.
.SS "Compatibility features"
The macros
.BR getopt ,
to read by people used to the traditional
.B getopt
function.
+.
+.\"--------------------------------------------------------------------------
.SH "SEE ALSO"
+.
.BR getopt (3),
.BR mLib (3).
+.
+.\"--------------------------------------------------------------------------
.SH "AUTHOR"
+.
Mark Wooding, <mdw@distorted.org.uk>
+.
+.\"----- That's all, folks --------------------------------------------------
+++ /dev/null
-.\" -*-nroff-*-
-.TH quis 3 "22 May 1999" "Straylight/Edgeware" "mLib utilities library"
-.SH NAME
-quis \- remember the program's name for use in messages
-.\" @quis
-.\" @ego
-.\" @QUIS
-.\" @pquis
-.SH SYNOPSIS
-.nf
-.B "#include <mLib/quis.h>"
-.PP
-.BI "void ego(const char *" p );
-.B "const char *quis(void);"
-.B "const char *QUIS;"
-.BI "int pquis(FILE *" fp ", const char *" p );
-.fi
-.SH DESCRIPTION
-The
-.B ego
-function should be called early in your program's initialization
-sequence, with the value of
-.B argv[0]
-as its argument. It will strip away leading path components, and a
-leading `\-' character (in case the program was called as a login
-shell), and keep the resulting short name for later.
-.PP
-The
-.B quis
-function returns the stored program name. There is also a macro
-.B QUIS
-which expands to the name of a global variable whose value is the string
-returned by
-.BR quis() .
-.PP
-Don't ask why it's done this way. There are raisins, but they're mostly
-hysterical.
-.PP
-The function
-.B pquis
-is passed a file pointer
-.I fp
-and a string
-.IR p :
-it writes the string to the file, replacing every lone occurrence of the
-character
-.RB ` $ '
-by the program name. Pairs
-.RB (` $$ ')
-are written as single dollar signs. The return value is zero if
-everything went OK, or the constant
-.B EOF
-if there was an error.
-.PP
-The program name is used in the messages produced by the
-.BR die (3)
-and
-.BR moan (3)
-functions.
-.SH "SEE ALSO"
-.BR report (3),
-.BR mLib (3).
-.SH AUTHOR
-Mark Wooding, <mdw@distorted.org.uk>
--- /dev/null
+.\" -*-nroff-*-
+.\"
+.\" Manual for program name
+.\"
+.\" (c) 1999, 2001, 2005, 2009, 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 quis 3mLib "22 May 1999" "Straylight/Edgeware" "mLib utilities library"
+.\" @quis
+.\" @ego
+.\" @QUIS
+.\" @pquis
+.
+.\"--------------------------------------------------------------------------
+.SH NAME
+quis \- remember the program's name for use in messages
+.
+.\"--------------------------------------------------------------------------
+.SH SYNOPSIS
+.
+.nf
+.B "#include <mLib/quis.h>"
+.PP
+.BI "void ego(const char *" p );
+.B "const char *quis(void);"
+.B "const char *QUIS;"
+.BI "int pquis(FILE *" fp ", const char *" p );
+.fi
+.
+.\"--------------------------------------------------------------------------
+.SH DESCRIPTION
+.
+The
+.B ego
+function should be called early in your program's initialization
+sequence, with the value of
+.B argv[0]
+as its argument. It will strip away leading path components, and a
+leading `\-' character (in case the program was called as a login
+shell), and keep the resulting short name for later.
+.PP
+The
+.B quis
+function returns the stored program name. There is also a macro
+.B QUIS
+which expands to the name of a global variable whose value is the string
+returned by
+.BR quis() .
+.PP
+Don't ask why it's done this way. There are raisins, but they're mostly
+hysterical.
+.PP
+The function
+.B pquis
+is passed a file pointer
+.I fp
+and a string
+.IR p :
+it writes the string to the file, replacing every lone occurrence of the
+character
+.RB ` $ '
+by the program name. Pairs
+.RB (` $$ ')
+are written as single dollar signs. The return value is zero if
+everything went OK, or the constant
+.B EOF
+if there was an error.
+.PP
+The program name is used in the messages produced by the
+.BR die (3)
+and
+.BR moan (3)
+functions.
+.
+.\"--------------------------------------------------------------------------
+.SH "SEE ALSO"
+.
+.BR report (3),
+.BR mLib (3).
+.
+.\"--------------------------------------------------------------------------
+.SH AUTHOR
+.
+Mark Wooding, <mdw@distorted.org.uk>
+.
+.\"----- That's all, folks --------------------------------------------------
+++ /dev/null
-.\" -*-nroff-*-
-.TH report 3 "20 June 1999" "Straylight/Edgeware" "mLib utilities library"
-.SH NAME
-report \- report errors
-.\" @moan
-.\" @die
-.SH SYNOPSIS
-.nf
-.B "#include <mLib/report.h>"
-.PP
-.BI "void moan(const char *" f ", ...);"
-.BI "void die(int " status ", const char *" f ", ...);"
-.fi
-.SH DESCRIPTION
-The
-.B moan
-function emits a message to the standard error stream consisting of the
-program's name (as read by the
-.B quis
-function; see
-.BR quis (3) for details),
-a colon, a space, and the
-.BR printf -style
-formatted string
-.I f
-followed by a newline. This is a handy way to report nonfatal errors in
-a program.
-.PP
-The
-.B die
-function emits a message to the standard error stream, just as for
-.B moan
-above, and then calls the
-.B exit
-function with argument
-.I status
-to halt the program. This is a handy way to report fatal errors in a
-program.
-.SH SEE ALSO
-.BR exit (3),
-.BR quis (3),
-.BR mLib (3).
-.SH AUTHOR
-Mark Wooding, <mdw@distorted.org.uk>
--- /dev/null
+.\" -*-nroff-*-
+.\"
+.\" Manual for reporting errors
+.\"
+.\" (c) 1999, 2001, 2005, 2009, 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 report 3mLib "20 June 1999" "Straylight/Edgeware" "mLib utilities library"
+.\" @moan
+.\" @die
+.
+.\"--------------------------------------------------------------------------
+.SH NAME
+report \- report errors
+.
+.\"--------------------------------------------------------------------------
+.SH SYNOPSIS
+.
+.nf
+.B "#include <mLib/report.h>"
+.PP
+.BI "void moan(const char *" f ", ...);"
+.BI "void die(int " status ", const char *" f ", ...);"
+.fi
+.
+.\"--------------------------------------------------------------------------
+.SH DESCRIPTION
+The
+.B moan
+function emits a message to the standard error stream consisting of the
+program's name (as read by the
+.B quis
+function; see
+.BR quis (3) for details),
+a colon, a space, and the
+.BR printf -style
+formatted string
+.I f
+followed by a newline. This is a handy way to report nonfatal errors in
+a program.
+.PP
+The
+.B die
+function emits a message to the standard error stream, just as for
+.B moan
+above, and then calls the
+.B exit
+function with argument
+.I status
+to halt the program. This is a handy way to report fatal errors in a
+program.
+.
+.\"--------------------------------------------------------------------------
+.SH SEE ALSO
+.
+.BR exit (3),
+.BR quis (3),
+.BR mLib (3).
+.
+.\"--------------------------------------------------------------------------
+.SH AUTHOR
+.
+Mark Wooding, <mdw@distorted.org.uk>
+.
+.\"----- That's all, folks --------------------------------------------------
## Compiler checking.
pkginclude_HEADERS += compiler.h
+EXTRA_DIST += compiler.3.in
LIBMANS += compiler.3
## Utility macros.
pkginclude_HEADERS += macros.h
+EXTRA_DIST += macros.3.in
LIBMANS += macros.3
## Alignment.
pkginclude_HEADERS += align.h
+EXTRA_DIST += align.3.in
LIBMANS += align.3
## Bit manipulation.
pkginclude_HEADERS += bits.h
+EXTRA_DIST += bits.3.in
LIBMANS += bits.3
check_PROGRAMS += t/bits.t
## Control flow.
pkginclude_HEADERS += control.h
+EXTRA_DIST += control.3.in
LIBMANS += control.3
check_PROGRAMS += t/control.t
## Exceptions.
pkginclude_HEADERS += exc.h
libutils_la_SOURCES += exc.c
+EXTRA_DIST += exc.3.in
LIBMANS += exc.3
check_PROGRAMS += t/exc.t
## Generalized formatting.
pkginclude_HEADERS += gprintf.h
libutils_la_SOURCES += gprintf.c
+EXTRA_DIST += gprintf.3.in
LIBMANS += gprintf.3
## Linear regression.
pkginclude_HEADERS += linreg.h
libutils_la_SOURCES += linreg.c
+EXTRA_DIST += linreg.3.in
LIBMANS += linreg.3
## Mathematics.
pkginclude_HEADERS += maths.h
+EXTRA_DIST += maths.3.in
LIBMANS += maths.3
## String handling.
pkginclude_HEADERS += str.h
libutils_la_SOURCES += str.c
+EXTRA_DIST += str.3.in
LIBMANS += str.3
## Version comparison.
pkginclude_HEADERS += versioncmp.h
libutils_la_SOURCES += versioncmp.c
+EXTRA_DIST += versioncmp.3.in
LIBMANS += versioncmp.3
check_PROGRAMS += t/versioncmp.t
+++ /dev/null
-.\" -*-nroff-*-
-.TH align 3 "4 January 2009" "Straylight/Edgeware" "mLib utilities library"
-.SH NAME
-align \- alignment utilities
-.\" @ALIGN
-.SH SYNOPSIS
-.nf
-.B "#include <mLib/align.h>"
-.PP
-.BI "size_t ALIGN(size_t " sz ");"
-.fi
-.SH DESCRIPTION
-The
-.B ALIGN
-macro returns the value of its argument
-.I sz
-rounded up to the next multiple of the size of
-.BR "union align" ,
-which is defined as a union containing a selection of built-in types.
-The intent is to write fairly portable memory allocators, which must
-return correctly-aligned memory.
-.IR array .
-.SH "SEE ALSO"
-.BR mLib (3).
-.SH "AUTHOR"
-Mark Wooding, <mdw@distorted.org.uk>
--- /dev/null
+.\" -*-nroff-*-
+.\"
+.\" Manual for memory alignment
+.\"
+.\" (c) 2009, 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 align 3mLib "4 January 2009" "Straylight/Edgeware" "mLib utilities library"
+.\" @ALIGN
+.
+.\"--------------------------------------------------------------------------
+.SH NAME
+align \- alignment utilities
+.
+.\"--------------------------------------------------------------------------
+.SH SYNOPSIS
+.
+.nf
+.B "#include <mLib/align.h>"
+.PP
+.BI "size_t ALIGN(size_t " sz ");"
+.fi
+.
+.\"--------------------------------------------------------------------------
+.SH DESCRIPTION
+The
+.B ALIGN
+macro returns the value of its argument
+.I sz
+rounded up to the next multiple of the size of
+.BR "union align" ,
+which is defined as a union containing a selection of built-in types.
+The intent is to write fairly portable memory allocators, which must
+return correctly-aligned memory.
+.IR array .
+.
+.\"--------------------------------------------------------------------------
+.SH "SEE ALSO"
+.
+.BR mLib (3).
+.
+.\"--------------------------------------------------------------------------
+.SH "AUTHOR"
+.
+Mark Wooding, <mdw@distorted.org.uk>
+.
+.\"----- That's all, folks --------------------------------------------------
.\" -*-nroff-*-
-.TH bits 3 "20 June 1999" "Straylight/Edgeware" "mLib utilities library"
-.ie t \{\
-. ds ss \s8\u
-. ds se \d\s0
-.\}
-.el \{\
-. ds ss ^
-. ds se
-.\}
-.SH NAME
-bits \- portable bit manipulation macros
+.\"
+.\" Manual for bit manipulation
+.\"
+.\" (c) 1999, 2001, 2005, 2009, 2018, 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 bits 3mLib "20 June 1999" "Straylight/Edgeware" "mLib utilities library"
.\" octet
.\" uint16
.\" uint24
.\" @SUB64
.\" @CMP64
.\" @ZERO64
+.
+.\"--------------------------------------------------------------------------
+.SH NAME
+bits \- portable bit manipulation macros
+.
+.\"--------------------------------------------------------------------------
.SH SYNOPSIS
+.
.nf
.B "#include <mLib/bits.h>"
.PP
.BR "typedef " ... " uint64;"
.BR "typedef " ... " kludge64;"
.PP
+.fi
+In the following,
+.I w
+is one of
+.BR 8 ,
+.BR 16 ,
+.BR 24 ,
+and
+.BR 32 ,
+and, on platforms with a 64-bit type,
+.BR 64 ;
+and
+.I we
+is one of
+.BR 8 ,
+.BR 16 ,
+.BR 16_L ,
+.BR 16_B ,
+.BR 24 ,
+.BR 24_L ,
+.BR 24_B ,
+.BR 32 ,
+.BR 32_L ,
+and
+.BR 32_B ,
+and, on platforms with a 64-bit type,
+.BR 64 ,
+.BR 64_L ,
+and
+.BR 64_B .
+.nf
+.PP
.BI "#define TY_" we " " type
.BI "#define SZ_" we " \fR..."
.BI "#define MASK_" we " \fR..."
.BI "int CMP64(kludge64 " x ", " op ", kludge64 " y );
.BI "int ZERO64(kludge64 " x );
.fi
+.
+.\"--------------------------------------------------------------------------
.SH DESCRIPTION
+.
The header file
.B <mLib/bits.h>
contains a number of useful definitions for portably dealing with bit-
argument
.I x
is exactly zero.
+.
+.\"--------------------------------------------------------------------------
.SH "SEE ALSO"
+.
.BR mLib (3).
+.
+.\"--------------------------------------------------------------------------
.SH AUTHOR
+.
Mark Wooding, <mdw@distorted.org.uk>
+.
+.\"----- That's all, folks --------------------------------------------------
+++ /dev/null
-.\" -*-nroff-*-
-.TH compiler 3 "26 May 2018" "Straylight/Edgeware" "mLib utilities library"
-.SH NAME
-compiler \- detect compiler version
-.\" @GCC_VERSION_P
-.\" @CLANG_VERSION_P
-.SH SYNOPSIS
-.nf
-.B "#include <mLib/compiler.h>"
-.PP
-.BI "int GCC_VERSION_P(" maj ", " min ");"
-.BI "int CLANG_VERSION_P(" maj ", " min ");"
-.fi
-.SH DESCRIPTION
-The macro invocation
-.BI GCC_VERSION_P( maj ", " min )
-expands to a compile-time constant nonzero value if the present compiler
-is GCC version
-.IR maj . min
-or better, or claims compatibility with it.
-This is frequently imperfect, as many compilers claim compatibility
-without implementing all of the necessary features, but it works
-adequately if one takes care.
-.PP
-The macro invocation
-.BI CLANG_VERSION_P( maj ", " min )
-expands to a compile-time constant nonzero value if the present compiler
-is Clang version
-.IR maj . min
-or better (or claims compatibility with it, but this is less likely
-than for GCC.
-.SH "SEE ALSO"
-.BR mLib (3).
-.SH "AUTHOR"
-Mark Wooding, <mdw@distorted.org.uk>
--- /dev/null
+.\" -*-nroff-*-
+.\"
+.\" Manual for compiler version checking
+.\"
+.\" (c) 2018, 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 compiler 3mLib "26 May 2018" "Straylight/Edgeware" "mLib utilities library"
+.\" @GCC_VERSION_P
+.\" @CLANG_VERSION_P
+.
+.\"--------------------------------------------------------------------------
+.SH NAME
+compiler \- detect compiler version
+.
+.\"--------------------------------------------------------------------------
+.SH SYNOPSIS
+.
+.nf
+.B "#include <mLib/compiler.h>"
+.PP
+.BI "int GCC_VERSION_P(" maj ", " min ");"
+.BI "int CLANG_VERSION_P(" maj ", " min ");"
+.fi
+.
+.\"--------------------------------------------------------------------------
+.SH DESCRIPTION
+The macro invocation
+.BI GCC_VERSION_P( maj ", " min )
+expands to a compile-time constant nonzero value if the present compiler
+is GCC version
+.IR maj . min
+or better, or claims compatibility with it.
+This is frequently imperfect, as many compilers claim compatibility
+without implementing all of the necessary features, but it works
+adequately if one takes care.
+.PP
+The macro invocation
+.BI CLANG_VERSION_P( maj ", " min )
+expands to a compile-time constant nonzero value if the present compiler
+is Clang version
+.IR maj . min
+or better (or claims compatibility with it, but this is less likely
+than for GCC.
+.
+.\"--------------------------------------------------------------------------
+.SH "SEE ALSO"
+.
+.BR mLib (3).
+.
+.\"--------------------------------------------------------------------------
+.SH "AUTHOR"
+.
+Mark Wooding, <mdw@distorted.org.uk>
+.
+.\"----- That's all, folks --------------------------------------------------
.\" -*-nroff-*-
-.de VS
-.sp 1
-.RS
-.nf
-.ft B
-..
-.de VE
-.ft R
-.fi
-.RE
-.sp 1
-..
-.TH control 3 "23 April 2023" "Straylight/Edgeware" "mLib utilities library"
+.\"
+.\" Manual for control flow metaprogramming
+.\"
+.\" (c) 2023, 2024 Straylight/Edgeware
+.\"
.
-.SH NAME
-control \- control structure metaprogramming
+.\"----- 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 control 3mLib "23 April 2023" "Straylight/Edgeware" "mLib utilities library"
.\" @MC_BEFORE
.\" @MC_AFTER
.\" @MC_WRAP
.\" @MC_LABEL
.\" @MC_GOTO
.
+.\"--------------------------------------------------------------------------
+.SH NAME
+control \- control structure metaprogramming
+.
+.\"--------------------------------------------------------------------------
.SH SYNOPSIS
+.
.nf
.B "#include <mLib/control.h>"
.PP
.BI MC_GOTO( tag )
.fi
.
+.\"--------------------------------------------------------------------------
.SH DESCRIPTION
+.
The header file
.B <mLib/control.h>
defines a number of macros which are useful
completes,
control transfers to the following statement.
.
+.\"--------------------------------------------------------------------------
.SH "BUGS"
+.
Some macros cause free
.B break
and/or
by introducing a hazard for those
trying to port code to other compilers which lack any such feature.
.
+.\"--------------------------------------------------------------------------
.SH "SEE ALSO"
-.BR mLib (3),
+.
.BR macros (3).
+.BR mLib (3),
.PP
Simon Tatham,
.IR "Metaprogramming custom control structures in C",
.BR "https://www.chiark.greenend.org.uk/~sgtatham/mp/" .
.
+.\"--------------------------------------------------------------------------
.SH "AUTHOR"
+.
Mark Wooding, <mdw@distorted.org.uk>
+.
+.\"----- That's all, folks --------------------------------------------------
.\" -*-nroff-*-
-.de VS
-.sp 1
-.in +5n
-.ft B
-.nf
-..
-.de VE
-.ft R
-.in -5n
-.sp 1
-.fi
-..
-.TH exc 3 "20 June 1999" "Straylight/Edgeware" "mLib utilities library"
-.SH NAME
-exc \- exception handling for C programs
+.\"
+.\" Manual for exception handling
+.\"
+.\" (c) 1999, 2001, 2005, 2009, 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 exc 3mLib "20 June 1999" "Straylight/Edgeware" "mLib utilities library"
.\" @TRY
.\" @CATCH
.\" @END_TRY
.\" @THROW
.\" @RETHROW
-.\"
+.
.\" @exc_uncaught
-.\"
+.
.\" @EXC_PAIR
.\" @EXC_ALLOC
.\" @EXC_ALLOCN
.\" @EXC_ALLOCI
.\" @EXC_ALLOCP
.\" @EXC_ALLOCS
-.\"
+.
+.\"--------------------------------------------------------------------------
+.SH NAME
+exc \- exception handling for C programs
+.
+.\"--------------------------------------------------------------------------
.SH SYNOPSIS
+.
+.nf
.B "#include <mLib/exc.h>"
-.sp 1
+.PP
+.ta 2n
.B TRY
-.I statement
+.I " statement"
.B CATCH
-.I statement
+.I " statement"
.B END_TRY;
-.br
.B EXIT_TRY;
-.sp 1
-.BI "THROW(exc_extype " type
-.RB [ ,
-.IR data ]\fB);
-.br
+.PP
+.BI "THROW(exc_extype " type " " "" \fR[ "" ", "data \fR] "" );
.B RETHROW;
-.sp 1
+.PP
.nf
.B "typedef void (*exc__uncaught)(exc_extype, exc_exval);"
.BI "exc__uncaught exc_uncaught(exc__uncaught " proc );
.BI "exc_extype EXC_ALLOCP(exc_extype " owner ", exc_extype " type );
.BI "exc_extype EXC_ALLOCS(exc_extype " owner ", exc_extype " type );
.fi
+.
+.\"--------------------------------------------------------------------------
.SH DESCRIPTION
+.
The header file
.B <mLib/exc.h>
introduces some new syntax and definitions to support exception handling
It's unfortunately important to remember that the syntax is provided
using macro expansion and standard C facilities; some of the
restrictions of these features show through.
+.
.SS "The TRY statement"
The
.B TRY
which refer to members of
.B exc_val
directly.
+.
.SS "The EXIT_TRY statement"
It is not safe to leave the dynamic scope of an exception handler early
(e.g., by a
scope of the
.B TRY
statement.
+.
.SS "The THROW and RETHROW statements"
The
.B THROW
nor
.B RETHROW
yields any value.
+.
.SS "Exception type allocation"
Exception types are 32-bit values. The top 16 bits are an
.IR "owner identifier" .
.B EXC_PAIR
as described above), and the type code. The data type is encoded into
the exception type by the allocation macro.
+.
.SS "Predefined exceptions"
The following exceptions are predefined:
.TP
and automatic data apply. Also, note that status such as the signal
mask is not reset, so you might have to do that manually in order to
recover from a signal.
+.
+.\"--------------------------------------------------------------------------
.SH "SEE ALSO"
+.
.BR mLib (3).
+.
+.\"--------------------------------------------------------------------------
.SH AUTHOR
+.
Mark Wooding, <mdw@distorted.org.uk>
+.
+.\"----- That's all, folks --------------------------------------------------
.\" -*-nroff-*-
-.de VS
-.sp 1
-.RS
-.nf
-.ft B
-..
-.de VE
-.ft R
-.fi
-.RE
-.sp 1
-..
-.de hP
-.IP
-.ft B
-\h'-\w'\\$1\ 'u'\\$1\ \c
-.ft P
-..
-.ie t \{\
-. ds o \(bu
-. de VP
-. sp .4v
-..
-\}
-.el \{\
-. ds o o
-. de VP
-. sp
-..
-\}
+.\"
+.\" Manual for generalized output formatting
+.\"
+.\" (c) 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 gprintf 3 "9 March 2024" "Straylight/Edgeware" "mLib utilities library"
+.\"--------------------------------------------------------------------------
+.TH gprintf 3mLib "9 March 2024" "Straylight/Edgeware" "mLib utilities library"
+.\" @gprintf
+.\" @vgprintf
+.\" @gprintf_memputf
.
+.\" @file_printops
+.
+.\"--------------------------------------------------------------------------
.SH NAME
gprintf \- generalized output formatting
.
+.\"--------------------------------------------------------------------------
.SH SYNOPSIS
+.
.nf
.B "#include <mLib/gprintf.h>"
.PP
.B "const struct gprintf_ops file_printops;"
.fi
.
+.\"--------------------------------------------------------------------------
.SH DESCRIPTION
+.
The
.B "<mLib/gprintf.h>"
header file declares facilities for generalized output formatting
.BR buf_putstrf...(3)
functions.
.PP
+The formatting is intended to be convenient and safe
+rather than efficient,
+so don't expect blistering performance.
+Similarly, there may be differences
+between the formatting done by
+.B gprintf
+and the C ilbrary's
+.BR sprintf (3)
+because the former has to do most of its work itself.
+In particular,
+.B gprintf
+understands the POSIX
+.RB ` n$ '
+positional parameter notation accepted by many Unix C libraries,
+even if the underlying C library does not.
+.PP
To use it, you must define a
.B "struct gprintf_ops"
structure,
/* ...\& other cleanup ...\& */
.VE
.
+.\"--------------------------------------------------------------------------
.SH "SEE ALSO"
+.
.BR buf (3),
.BR dstr (3),
.BR mLib (3).
.
+.\"--------------------------------------------------------------------------
.SH AUTHOR
+.
+.\"--------------------------------------------------------------------------
Mark Wooding, <mdw@distorted.org.uk>
+.
+.\"----- That's all, folks --------------------------------------------------
.\" -*-nroff-*-
-.TH linreg 3 "9 March 2024" "Straylight/Edgeware" "mLib utilities library"
+.\"
+.\" Manual for linear regression
+.\"
+.\" (c) 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 linreg 3mLib "9 March 2024" "Straylight/Edgeware" "mLib utilities library"
.\" @linreg_init
.\" @linreg_update
.\" @linreg_fit
.\" @LINREG_INIT
.
+.\"--------------------------------------------------------------------------
+.SH NAME
+lineag \- linear regression
+.
+.\"--------------------------------------------------------------------------
.SH SYNOPSIS
.nf
.B "#include <mLib/linreg.h>"
.BI " double *" m_out ", double *" c_out ", double *" r_out );
.fi
.
+.\"--------------------------------------------------------------------------
.SH DESCRIPTION
+.
The functions declared in the
.B <mLib/linreg.h>
header perform simple linear regression.
.PP
Any half-decent introduction to statistics will explain these concepts.
.
+.\"--------------------------------------------------------------------------
+.SH SEE ALSO
+.
+.BR mLib (3).
+.
+.\"--------------------------------------------------------------------------
.SH AUTHOR
+.
Mark Wooding, <mdw@distorted.org.uk>
+.
+.\"----- That's all, folks --------------------------------------------------
.\" -*-nroff-*-
-.TH macros 3 "13 December 2003" "Straylight/Edgeware" "mLib utilities library"
-.SH NAME
-macros \- useful macros
+.\"
+.\" Manual for miscellaneous macros
+.\"
+.\" (c) 2003, 2005, 2009, 2013, 2018, 2019, 2022, 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 macros 3mLib "13 December 2003" "Straylight/Edgeware" "mLib utilities library"
.\" @N
.\" @STR
.\" @GLUE
.\" @MUFFLE_WARNINGS_STMT
.\" @GCC_WARNING
.\" @CLANG_WARNING
+.
+.\"--------------------------------------------------------------------------
+.SH NAME
+macros \- useful macros
+.
+.\"--------------------------------------------------------------------------
.SH SYNOPSIS
+.
.nf
.B "#include <mLib/macros.h>"
.PP
.BI "GCC_WARNING(" option ")"
.BI "CLANG_WARNING(" option ")"
.fi
+.
+.\"--------------------------------------------------------------------------
.SH DESCRIPTION
+.
.SS Utilities
The
.B N
.B IGNORE
macro ignores its argument, which may be an expression of any type.
This can be useful in muffling warnings about unused variables.
+.
.SS Annotations
The following annotations can be attached to function declarations and
definitions, as part of the declaration specifiers. (Other positions
(starting from position
.IR arg-index ).
Compilers may warn about misuse of such functions.
+.
.SS Muffling warnings
Some compilers allow you to muffle warnings in particular pieces of
code. These macros provide a compiler-neutral interface to such
.BR MUFFLE_WARNINGS_EXPR ),
or a statement (for
.BR MUFFLE_WARNINGS_STMT ).
+.
.SS GCC-specific features
The
-.B GCC_VERSION_P
-macro returns a nonzero value if the compiler is at least version
-.IB maj . min
-of GCC, and zero otherwise. It's useful in preprocessor conditions.
-.PP
-The
.B GCC_WARNING
macro is intended to be used in
.I warns
.BR <mLib/compiler.h>;
see
.BR compiler (3).
+.
+.\"--------------------------------------------------------------------------
.SH "SEE ALSO"
-.BR mLib (3),
+.
.BR compiler (3).
+.BR mLib (3),
+.
+.\"--------------------------------------------------------------------------
.SH "AUTHOR"
+.
Mark Wooding, <mdw@distorted.org.uk>
+.
+.\"----- That's all, folks --------------------------------------------------
+++ /dev/null
-.\" -*-nroff-*-
-.TH linreg 3 "9 March 2024" "Straylight/Edgeware" "mLib utilities library"
-.\" @NANPN
-.\" @INFP
-.\" @NEGP
-.
-.SH SYNOPSIS
-.nf
-.B "#include <mLib/maths.h>"
-.PP
-.BI "int NANP(" floatish " " x );
-.BI "int INFP(" floatish " " x );
-.BI "int NEGP(" floatish " " x );
-.fi
-.
-.SH DESCRIPTION
-The
-.B <mLib/maths.h>
-header declares some minor low-level floating-point utilities.
-These are mostly redundant with C99,
-but provided for portability to older platforms.
-.PP
-The
-.B NANP
-macro returns nonzero if its argument is not-a-number.
-The
-.B INFP
-macro returns nonzero if its argument is infinite.
-The
-.B NEGP
-macro returns nonzero if its argument is negative;
-on IEEE\ 754 platforms with sufficient support,
-it will correctly detect negative zero.
-.
-.SH AUTHOR
-Mark Wooding, <mdw@distorted.org.uk>
--- /dev/null
+.\" -*-nroff-*-
+.\"
+.\" Manual for mathematical definitions
+.\"
+.\" (c) 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 math 3mLib "9 March 2024" "Straylight/Edgeware" "mLib utilities library"
+.\" @NANPN
+.\" @INFP
+.\" @NEGP
+.
+.\"--------------------------------------------------------------------------
+.NAME
+maths \- mathematical utilities
+.
+.\"--------------------------------------------------------------------------
+.SH SYNOPSIS
+.
+.nf
+.B "#include <mLib/maths.h>"
+.PP
+.BI "int NANP(" floatish " " x );
+.BI "int INFP(" floatish " " x );
+.BI "int NEGP(" floatish " " x );
+.fi
+.
+.\"--------------------------------------------------------------------------
+.SH DESCRIPTION
+.
+The
+.B <mLib/maths.h>
+header declares some minor low-level floating-point utilities.
+These are mostly redundant with C99,
+but provided for portability to older platforms.
+.PP
+The
+.B NANP
+macro returns nonzero if its argument is not-a-number.
+The
+.B INFP
+macro returns nonzero if its argument is infinite.
+The
+.B NEGP
+macro returns nonzero if its argument is negative;
+on IEEE\ 754 platforms with sufficient support,
+it will correctly detect negative zero.
+.
+.\"--------------------------------------------------------------------------
+.SH "SEE ALSO"
+.
+.BR mLib (3).
+.
+.\"--------------------------------------------------------------------------
+.SH AUTHOR
+.
+Mark Wooding, <mdw@distorted.org.uk>
+.
+.\"----- That's all, folks --------------------------------------------------
.\" -*-nroff-*-
-.de VS
-.sp 1
-.in +5n
-.ft B
-.nf
-..
-.de VE
-.ft R
-.in -5n
-.sp 1
-.fi
-..
-.ie t \{\
-. de VP
-. sp .4v
-..
-\}
-.el \{\
-. de VP
-. sp
-..
-\}
-.TH str 3 "20 June 1999" "Straylight/Edgeware" "mLib utilities library"
-.SH NAME
-str \- small string utilities
+.\"
+.\" Manual for string utilities
+.\"
+.\" (c) 1999--2001, 2005--2007, 2009, 2019, 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 str 3mLib "20 June 1999" "Straylight/Edgeware" "mLib utilities library"
.\" @str_qword
.\" @str_qsplit
.\" @str_getword
.\" @str_matchx
.\" @str_match
.\" @str_sanitize
+.
+.\"--------------------------------------------------------------------------
+.SH NAME
+str \- small string utilities
+.
+.\"--------------------------------------------------------------------------
.SH SYNOPSIS
+.
.nf
.B "#include <mLib/str.h>"
.PP
.BI "int str_match(const char *" p ", const char *" s );
.BI "void str_sanitize(char *" d ", const char *" p ", size_t " sz );
.fi
+.
+.\"--------------------------------------------------------------------------
.SH DESCRIPTION
+.
The header file
.B <mLib/str.h>
contains a few small utility functions for manipulating null-terminated
.RB ` _ '
when written to
.IR d .
+.
+.\"--------------------------------------------------------------------------
.SH EXAMPLES
+.
Given the code
.VS
char p[] = " alpha beta gamma delta ";
and
.B rest
will be null.
+.
+.\"--------------------------------------------------------------------------
.SH "SEE ALSO"
+.
.BR mLib (3).
+.
+.\"--------------------------------------------------------------------------
.SH AUTHOR
+.
Mark Wooding, <mdw@distorted.org.uk>
+.
+.\"----- That's all, folks --------------------------------------------------
+++ /dev/null
-.\" -*-nroff-*-
-.TH versioncmp 3 "6 January 2007" "Straylight/Edgeware" "mLib utilities library"
-.SH NAME
-versioncmp \- compare Debian-format version numbers
-.\" @versioncmp
-.\" @VERSIONCMP
-.SH SYNOPSIS
-.nf
-.B "#include <mLib/versioncmp.h>"
-.PP
-.BI "int versioncmp(const char *" va ", const char *" vb ");"
-.BI "int VERSIONCMP(const char *" va ", " op ", const char *" vb ");"
-.fi
-.SH DESCRIPTION
-The
-.B versioncmp
-function compares version strings.
-.PP
-The format of version numbers considered is
-.IP
-.RI [ epoch
-.BR : ]
-.I main
-.RB [ \-
-.IR sub ]
-.PP
-The
-.I main
-part may contain colons or hyphens if there is an
-.I epoch
-or
-.IR sub ,
-respectively. Version strings are compared componentwise: first epochs,
-then main parts, and finally subparts.
-.PP
-The component comparison is done as follows. First, the initial
-subsequence of nondigit characters is extracted from each string, and
-these are compared lexicographically, using ASCII ordering, except that
-letters precede non-letters. If both are the same, an initial sequence
-of digits is extracted from the remaining parts of the version strings,
-and these are compared numerically (an empty sequence being considered
-to have the value zero). This process is repeated until we have a
-winner or until both strings are exhausted.
-.PP
-The return value is 0 if the two strings are equal, \-1 if
-.I va
-is older than
-.IR vb ,
-or +1 if
-.I va
-is newer than
-.IR vb .
-.PP
-The
-.B VERSIONCMP
-macro provides a more convenient syntax for the
-.B versioncmp
-function, by allowing a relational operator to be written between the
-operands.
-.SH SEE ALSO
-.BR mLib (3).
-.PP
-.IR "Debian Policy Manual" .
-.SH AUTHOR
-Mark Wooding, <mdw@distorted.org.uk>
--- /dev/null
+.\" -*-nroff-*-
+.\"
+.\" Manual for version number comparison
+.\"
+.\" (c) 2007, 2009, 2020, 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 versioncmp 3mLib "6 January 2007" "Straylight/Edgeware" "mLib utilities library"
+.\" @versioncmp
+.\" @VERSIONCMP
+.
+.\"--------------------------------------------------------------------------
+.SH NAME
+versioncmp \- compare Debian-format version numbers
+.
+.\"--------------------------------------------------------------------------
+.SH SYNOPSIS
+.
+.nf
+.B "#include <mLib/versioncmp.h>"
+.PP
+.BI "int versioncmp(const char *" va ", const char *" vb ");"
+.BI "int VERSIONCMP(const char *" va ", " op ", const char *" vb ");"
+.fi
+.
+.\"--------------------------------------------------------------------------
+.SH DESCRIPTION
+.
+The
+.B versioncmp
+function compares version strings.
+.PP
+The format of version numbers considered is
+.IP
+.RI [ epoch
+.BR : ]
+.I main
+.RB [ \-
+.IR sub ]
+.PP
+The
+.I main
+part may contain colons or hyphens if there is an
+.I epoch
+or
+.IR sub ,
+respectively. Version strings are compared componentwise: first epochs,
+then main parts, and finally subparts.
+.PP
+The component comparison is done as follows. First, the initial
+subsequence of nondigit characters is extracted from each string, and
+these are compared lexicographically, using ASCII ordering, except that
+letters precede non-letters. If both are the same, an initial sequence
+of digits is extracted from the remaining parts of the version strings,
+and these are compared numerically (an empty sequence being considered
+to have the value zero). This process is repeated until we have a
+winner or until both strings are exhausted.
+.PP
+The return value is 0 if the two strings are equal, \-1 if
+.I va
+is older than
+.IR vb ,
+or +1 if
+.I va
+is newer than
+.IR vb .
+.PP
+The
+.B VERSIONCMP
+macro provides a more convenient syntax for the
+.B versioncmp
+function, by allowing a relational operator to be written between the
+operands.
+.
+.\"--------------------------------------------------------------------------
+.SH SEE ALSO
+.
+.BR mLib (3).
+.PP
+.IR "Debian Policy Manual" .
+.
+.\"--------------------------------------------------------------------------
+.SH AUTHOR
+.
+Mark Wooding, <mdw@distorted.org.uk>
+.
+.\"----- That's all, folks --------------------------------------------------
bin_PROGRAMS =
check_PROGRAMS =
pkginclude_HEADERS =
+noinst_DATA =
PROGMANS =
LIBMANS =
-EXTRA_DIST += $(PROGMANS) $(LIBMANS)
+
+SUFFIXES =
###--------------------------------------------------------------------------
### Machinery for precomputations.
###--------------------------------------------------------------------------
### Manual.
-EXTRA_DIST += $(LIBMANS) $(PROGMANS)
+noinst_DATA += $(PROGMANS) $(LIBMANS)
+CLEANFILES += $(PROGMANS) $(LIBMANS)
+
+SUFFIXES += .1 .1.in
+SUFFIXES += .3 .3.in
+
+mandefs = $(top_srcdir)/defs.man
+
+V_MAN = $(V_MAN_@AM_V@)
+V_MAN_ = $(V_MAN_@AM_DEFAULT_V@)
+V_MAN_0 = @echo " MAN $@";
+
+.1.in.1 .3.in.3:
+ $(V_MAN)
+ $(AM_V_at)sed '/^\.$$/ d; /^\.\\"/ d' $(mandefs) >$@.defs
+ $(AM_V_at)sed -e '/@@@PRE@@@/ {' -e 'r$@.defs' -e 'd' -e '}' \
+ $< >$@.new
+ $(AM_V_at)rm -f $@.defs && mv $@.new $@
install-data-local: install-man
install-man: $(LIBMANS) $(PROGMANS)
@$(NORMAL_INSTALL)
$(mkdir_p) $(DESTDIR)$(mandir)
$(top_srcdir)/config/maninst \
- -d $(DESTDIR)$(mandir) -s $(srcdir) \
+ -d $(DESTDIR)$(mandir) -s . \
-i "$(INSTALL)" \
install $(PROGMANS)
$(top_srcdir)/config/maninst \
- -d $(DESTDIR)$(mandir) -s $(srcdir) \
+ -d $(DESTDIR)$(mandir) -s . \
-i "$(INSTALL)" -e "$(manext)" \
install $(LIBMANS)
.PHONY: install-man
uninstall-man:
@$(NORMAL_UNINSTALL)
$(top_srcdir)/config/maninst \
- -d $(DESTDIR)$(mandir) -s $(srcdir) \
+ -d $(DESTDIR)$(mandir) -s . \
uninstall $(PROGMANS)
$(top_srcdir)/config/maninst \
- -d $(DESTDIR)$(mandir) -s $(srcdir) -e "$(manext)" \
+ -d $(DESTDIR)$(mandir) -s . -e "$(manext)" \
uninstall $(LIBMANS)
.PHONY: uninstall-man
~mdw / mLib / commitdiff