Browse Source

add errmsg documentation

master
Felix von Leitner 1 month ago
parent
commit
519c59690d
8 changed files with 170 additions and 0 deletions
  1. +20
    -0
      buffer/carp.3
  2. +14
    -0
      buffer/carpsys.3
  3. +25
    -0
      buffer/die.3
  4. +18
    -0
      buffer/diesys.3
  5. +40
    -0
      buffer/errmsg.7
  6. +19
    -0
      buffer/errmsg_iam.3
  7. +20
    -0
      buffer/msg.3
  8. +14
    -0
      buffer/msgsys.3

+ 20
- 0
buffer/carp.3 View File

@@ -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)

+ 14
- 0
buffer/carpsys.3 View File

@@ -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)

+ 25
- 0
buffer/die.3 View File

@@ -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)

+ 18
- 0
buffer/diesys.3 View File

@@ -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)

+ 40
- 0
buffer/errmsg.7 View File

@@ -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)

+ 19
- 0
buffer/errmsg_iam.3 View File

@@ -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)

+ 20
- 0
buffer/msg.3 View File

@@ -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)

+ 14
- 0
buffer/msgsys.3 View File

@@ -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)

Loading…
Cancel
Save