From 2389a150acfc3915ec6684231fefca4e2323e93d Mon Sep 17 00:00:00 2001 From: leitner Date: Tue, 14 Jul 2020 16:07:30 +0000 Subject: [PATCH] add errmsg documentation --- buffer/carp.3 | 20 ++++++++++++++++++++ buffer/carpsys.3 | 14 ++++++++++++++ buffer/die.3 | 25 +++++++++++++++++++++++++ buffer/diesys.3 | 18 ++++++++++++++++++ buffer/errmsg.7 | 40 ++++++++++++++++++++++++++++++++++++++++ buffer/errmsg_iam.3 | 19 +++++++++++++++++++ buffer/msg.3 | 20 ++++++++++++++++++++ buffer/msgsys.3 | 14 ++++++++++++++ 8 files changed, 170 insertions(+) create mode 100644 buffer/carp.3 create mode 100644 buffer/carpsys.3 create mode 100644 buffer/die.3 create mode 100644 buffer/diesys.3 create mode 100644 buffer/errmsg.7 create mode 100644 buffer/errmsg_iam.3 create mode 100644 buffer/msg.3 create mode 100644 buffer/msgsys.3 diff --git a/buffer/carp.3 b/buffer/carp.3 new file mode 100644 index 0000000..93bec2b --- /dev/null +++ b/buffer/carp.3 @@ -0,0 +1,20 @@ +.TH carp 3 +.SH NAME +carp \- print warning diagnostic +.SH SYNTAX +.B #include + +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) diff --git a/buffer/carpsys.3 b/buffer/carpsys.3 new file mode 100644 index 0000000..02d18da --- /dev/null +++ b/buffer/carpsys.3 @@ -0,0 +1,14 @@ +.TH carpsys 3 +.SH NAME +carp \- print warning diagnostic +.SH SYNTAX +.B #include + +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) diff --git a/buffer/die.3 b/buffer/die.3 new file mode 100644 index 0000000..5c947d7 --- /dev/null +++ b/buffer/die.3 @@ -0,0 +1,25 @@ +.TH die 3 +.SH NAME +die \- print warning diagnostic and abort program +.SH SYNTAX +.B #include + +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) diff --git a/buffer/diesys.3 b/buffer/diesys.3 new file mode 100644 index 0000000..0bc8140 --- /dev/null +++ b/buffer/diesys.3 @@ -0,0 +1,18 @@ +.TH die 3 +.SH NAME +die \- print warning diagnostic and abort program +.SH SYNTAX +.B #include + +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) diff --git a/buffer/errmsg.7 b/buffer/errmsg.7 new file mode 100644 index 0000000..c7b3461 --- /dev/null +++ b/buffer/errmsg.7 @@ -0,0 +1,40 @@ +.TH errmsg 7 +.SH NAME +errmsg \- print diagnostics and/or abort program +.SH SYNTAX +.B #include + + \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) diff --git a/buffer/errmsg_iam.3 b/buffer/errmsg_iam.3 new file mode 100644 index 0000000..a02ed9e --- /dev/null +++ b/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 + +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) diff --git a/buffer/msg.3 b/buffer/msg.3 new file mode 100644 index 0000000..9f737db --- /dev/null +++ b/buffer/msg.3 @@ -0,0 +1,20 @@ +.TH msg 3 +.SH NAME +msg \- print diagnostic +.SH SYNTAX +.B #include + +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) diff --git a/buffer/msgsys.3 b/buffer/msgsys.3 new file mode 100644 index 0000000..dc5a02c --- /dev/null +++ b/buffer/msgsys.3 @@ -0,0 +1,14 @@ +.TH msg 3 +.SH NAME +msg \- print diagnostic +.SH SYNTAX +.B #include + +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)