add errmsg documentation

buffer/carp.3

@@ -0,0 +1,20 @@
+.TH carp 3
+.SH NAME
+carp \- print warning diagnostic
+.SH SYNTAX
+.B #include <libowfat/errmsg.h>
+
+void \fBcarp\fP(const char *\fImessage\fR, ...);
+.SH DESCRIPTION
+
+If \fIerrmsg_iam\fP was called to set the program name, \fIcarp\fP will
+first print that program name and a colon.
+
+\fIcarp\fP will print all its arguments to stderr (fd #2).
+
+It does not synchronize with any other output method.
+
+If you have unflushed data in \fIbuffer_2\fP, it will stay there.
+
+.SH "SEE ALSO"
+errmsg(7), buffer_flush(3)

buffer/carpsys.3

@@ -0,0 +1,14 @@
+.TH carpsys 3
+.SH NAME
+carp \- print warning diagnostic
+.SH SYNTAX
+.B #include <libowfat/errmsg.h>
+
+void \fBcarpsys\fP(const char *\fImessage\fR, ...);
+.SH DESCRIPTION
+
+\fIcarpsys\fP is like \fIcarp\fP, but it will also print a string
+representation of the system error code (from errno).
+
+.SH "SEE ALSO"
+errmsg(7), carp(3)

buffer/die.3

@@ -0,0 +1,25 @@
+.TH die 3
+.SH NAME
+die \- print warning diagnostic and abort program
+.SH SYNTAX
+.B #include <libowfat/errmsg.h>
+
+void \fBdie\fP(int \fIexitcode\fP, const char *\fImessage\fR, ...);
+.SH DESCRIPTION
+
+If \fIerrmsg_iam\fP was called to set the program name, \fIdie\fP will
+first print that program name and a colon.
+
+\fIdie\fP will print all its arguments to stderr (fd #2) and then call
+\fIexit\fP(\fIexitcode\fP).
+
+It does not synchronize with any other output method.
+
+Flush \fIbuffer_1\fP and \fIbuffer_2\fP manually first if needed.
+
+.SH NOTE
+
+This function does not return.
+
+.SH "SEE ALSO"
+errmsg(7), buffer_flush(3)

buffer/diesys.3

@@ -0,0 +1,18 @@
+.TH die 3
+.SH NAME
+die \- print warning diagnostic and abort program
+.SH SYNTAX
+.B #include <libowfat/errmsg.h>
+
+void \fBdie\fP(int \fIexitcode\fP, const char *\fImessage\fR, ...);
+.SH DESCRIPTION
+
+\fIdiesys\fP is like \fIdie\fP, but it will also print a string
+representation of the system error code (from errno).
+
+.SH NOTE
+
+This function does not return.
+
+.SH "SEE ALSO"
+errmsg(7), die(3)

buffer/errmsg.7

@@ -0,0 +1,40 @@
+.TH errmsg 7
+.SH NAME
+errmsg \- print diagnostics and/or abort program
+.SH SYNTAX
+.B #include <libowfat/errmsg.h>
+
+  \fBerrmsg_iam\fP("my_program");    // or use argv[0]
+  \fBmsg\fP("entering phase 1");
+  \fBcarp\fP("there is a problem, but we'll soldier on");
+  \fBdie\fP(111,"fatal problem, program will abort");
+  \fBmsg\fP("failed to open ",filename," as expected");
+  \fBcarpsys\fP("failed to open ",filename);
+  \fBdiesys\fP(111,"error opening ",filename,", bailing out");
+
+.SH DESCRIPTION
+
+At the start of the program, call \fIerrmsg_iam\fP so the diagnostic messages
+will include the program name.
+
+\fImsg\fP will print to stdout (fd #1), \fIcarp\fP will print to stderr (fd #2), \fIdie\fP
+will print to stderr (fd #2) and then exit with the return code you
+specified.
+
+\fImsgsys\fP, \fIcarpsys\fP and \fIdiesys\fP will also include a string representation of
+the system error code in errno.
+
+By convention, fd #1 is for regular output and fd #2 is for error
+messages.
+
+These message are written directly to the corresponding file descriptor,
+without buffering. There is no need for flushing.
+
+.SH NOTE
+
+These functions do not synchronize with \fIbuffer_1\fP or \fIbuffer_2\fP.
+If you have pending output in a buffer, you need to flush manually first
+(see buffer_flush).
+
+.SH "SEE ALSO"
+buffer_flush(3)

buffer/errmsg_iam.3

@@ -0,0 +1,19 @@
+.TH errmsg_iam 3
+.SH NAME
+errmsg_iam \- tell errmsg library the name of the program
+.SH SYNTAX
+.B #include <libowfat/errmsg.h>
+
+void \fBerrmsg_iam\fP(const char *\fIprogname\fR);
+.SH DESCRIPTION
+
+Use this function to set the program name.
+
+This function is usually called directly at the start of main() and
+given argv[0] as argument.
+
+This is important for batch processing, so the observer can tell which
+program the error message came from.
+
+.SH "SEE ALSO"
+errmsg(7)

buffer/msg.3

@@ -0,0 +1,20 @@
+.TH msg 3
+.SH NAME
+msg \- print diagnostic
+.SH SYNTAX
+.B #include <libowfat/errmsg.h>
+
+void \fBmsg\fP(const char *\fImessage\fR, ...);
+.SH DESCRIPTION
+
+If \fIerrmsg_iam\fP was called to set the program name, \fImsg\fP will
+first print that program name and a colon.
+
+\fImsg\fP will print all its arguments to stdout (fd #1).
+
+It does not synchronize with any other output method.
+
+If you have unflushed data in \fIbuffer_1\fP, it will stay there.
+
+.SH "SEE ALSO"
+errmsg(7), buffer_flush(3)

buffer/msgsys.3

@@ -0,0 +1,14 @@
+.TH msg 3
+.SH NAME
+msg \- print diagnostic
+.SH SYNTAX
+.B #include <libowfat/errmsg.h>
+
+void \fBmsg\fP(const char *\fImessage\fR, ...);
+.SH DESCRIPTION
+
+\fImsgsys\fP is like \fImsg\fP, but it will also print a string
+representation of the system error code (from errno).
+
+.SH "SEE ALSO"
+errmsg(7), msg(3)