Adding upstream version 4.22.0.upstream/4.22.0

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 262 insertions, 0 deletions

diff --git a/upstream/opensuse-leap-15-6/man1/liberror.1 b/upstream/opensuse-leap-15-6/man1/liberror.1
new file mode 100644
index 00000000..d92e9eb0
--- /dev/null
+++ b/upstream/opensuse-leap-15-6/man1/liberror.1
@@ -0,0 +1,262 @@
+\
+.\" This man page was generated by the Netpbm tool 'makeman' from HTML source.
+.\" Do not hand-hack it!  If you have bug fixes or improvements, please find
+.\" the corresponding HTML page on the Netpbm website, generate a patch
+.\" against that, and send it to the Netpbm maintainer.
+.TH "Netpbm User Manual" 0 "" "netpbm documentation"
+
+
+
+.UN error
+.SH Netpbm Programming Library Errors
+.PP
+As part of Netpbm's mission to make writing graphics programs quick
+and easy, Netpbm recognizes that no programmer likes to deal with
+error conditions.  Therefore, very few Netpbm programming library
+functions return error information.  There are no return codes to
+check.  If for some reason a function can't do what was asked of it,
+it doesn't return at all.
+.PP
+Netpbm's response to encountering an error is called "throwing
+an error."
+.PP
+The typical way a Netpbm function throws an error (for example,
+when you attempt to open a non-existent file with \fBpm_openr()\fP)
+is that the function writes an error message to the Standard Error
+file and then causes the program to terminate with an exit() system
+call.  The function doesn't do any explicit cleanup, because everything
+a library function sets up gets cleaned up by normal process
+termination.
+.PP
+In many cases, that simply isn't acceptable.  If you're calling
+Netpbm functions from inside a server program, you'd want the program
+to recognize that the immediate task failed, but keep running to do
+other work.
+.PP
+So as an alternative, you can replace that program exit with a
+longjmp instead.  A longjmp is a classic Unix exception handling
+concept.  See the documentation of the standard C library
+\fBsetjmp()\fP and \fBlongjmp()\fP functions.
+.PP
+In short, you identify a point in your programs for execution to
+hyperjump to from whatever depths of whatever functions it may be in
+at the time it detects an exception.  That hyperjump is called a
+longjmp.  The longjmp unwinds the stack and puts the program in the
+same state as if the subroutines had returned all the way up to the
+function that contains the jump point.  A longjmp does not in itself
+undo things like memory allocations.  But when you have a Netpbm
+function do a longjmp, it also cleans up everything it started.
+.PP
+To select this form of throwing an error, use the
+\fBpm_setjmpbuf()\fP function.  This alternative is not available
+before Netpbm 10.27 (March 2005).
+.PP
+Issuing of the error message is a separate thing.  Regardless
+of whether a library routine exits the program or executes a longjmp,
+it issues an error message first.
+.PP
+You can customize the error message behavior too.  By default, a
+Netpbm function issues an error message by writing it to the Standard
+Error file, formatted into a single line with the program name prefixed.
+But you can register your own error message function to run instead with
+\fBpm_setusererrormsgfn()\fP.
+
+
+.UN pm_setjmpbuf
+.SS pm_setjmpbuf()
+.PP
+pm_setjmpbuf() sets up the process so that when future calls to the
+Netpbm programming library throw an error, they execute a longjmp
+instead of causing the process to exit as they would by default.
+.PP
+This is \fInot\fP analogous to \fBsetjmp()\fP.  You do a
+setjmp() first, then tell the Netpbm programming library with
+\fBpm_setjmpbuf()\fP to use the result.
+.PP
+Example:
+
+.nf
+\f(CW
+  #include <setjmp.h>
+  #include <netpbm/pam.h>
+
+  jmp_buf jmpbuf;
+  int rc;
+
+  rc = setjmp(jmpbuf);
+  if (rc == 0) {
+    struct pam pam;
+    pm_setjmpbuf(&jmpbuf);
+    
+    pnm_readpam(stdin, &pam, PAM_STRUCT_SIZE(tuple_type));
+
+    printf("pnm_readpam() succeeded!\en");
+
+  } else {
+    printf("pnm_readpam() failed.  You should have seen "
+           "messages to Standard Error telling you why.\en");
+  }
+\fP
+.fi
+.PP
+This example should look really strange to you if you haven't read
+the documentation of \fBsetjmp()\fP.  Remember that there is a
+hyperjump such that the program is executing the \fBpnm_readpam()\fP
+and then suddenly is returning a second time from the setjmp()!
+.PP
+Even \fBpm_error()\fP works this way -- if you set up a longjmp with
+\fBpm_setjmpbuf()\fP and then call \fBpm_error()\fP, \fBpm_error()\fP
+will, after issuing your error message, execute the longjmp.
+.PP
+\fBpm_setjmpbuf()\fP was new in Netpbm 10.27 (March 2005).  Before
+that, Netpbm programming library functions always throw an error by
+exiting the program.
+
+
+.SH User Detected Errors
+.PP
+The Netpbm programming library provides a function for you to throw
+an error explicitly: \fBpm_error()\fP.  \fBpm_error()\fP does
+nothing but throw an error, and does so the same way any Netpbm
+library function you call would.  \fBpm_error()\fP is more convenient
+than most standard C facilities for handling errors.
+.PP
+If you don't want to throw an error, but just want to issue an
+error message, use \fBpm_errormsg()\fP.  It issues the message in the
+same way as \fBpm_error()\fP but returns normally instead of longjmping
+or exiting the program.  
+.PP
+Note that \fBlibnetpbm\fP distinguishes between an error message
+and an informational message (use \fBpm_errormsg()\fP for the former;
+\fBpm_message()\fP for the latter).  The only practical difference is
+which user message function it calls.  So if you don't register any
+user message function, you won't see any difference, but a program is
+still more maintainable and easier to read when you use the
+appropriate one of these.
+
+
+.UN pm_error
+.SS pm_error()
+
+.B Overview
+.PP
+\fBvoid pm_error(\fP
+\fBchar *\fP \fIfmt\fP\fB,\fP
+\fB... );\fP
+
+.B Example
+
+.nf
+\f(CW
+if (argc-1 < 3)
+    pm_error("You must specify at least 3 arguments.  "
+             "You specified" only %d", argc-1);
+\fP
+.fi
+.PP
+\fBpm_error()\fP is a \fBprintf()\fP style routine that 
+simply throws an error.  It issues an error message exactly like
+\fBpm_errormsg()\fP would in the process.
+
+
+.UN pm_errormsg
+.SS pm_errormsg()
+
+.B Overview
+.PP
+\fBvoid pm_errormsg(\fP
+\fBchar *\fP \fIfmt\fP\fB,\fP
+\fB... );\fP
+
+.B Example
+
+.nf
+\f(CW
+if (rc = -1)
+    pm_errormsg("Could not open file.  errno=%d", errno);
+    return -1;
+\fP
+.fi
+.PP
+\fBpm_errormsg()\fP is a \fBprintf()\fP style routine that 
+issues an error message.  By default, it writes the message to Standard
+Error, but you can register a user error message routine to be called
+instead, and that might do something such as write the message into a 
+log file.  See 
+.UR #pm_setusererrormsgfn
+\fBpm_setusererrormsgfn\fP
+.UE
+\&.
+.PP
+There is very little advantage to using this over traditional C
+services, but it issues a message in the same way as \fBlibnetpbm\fP
+library functions do, so the common handling might be valuable.
+.PP
+Note that the arguments specify the message text, not any formatting
+of it.  Formatting is handled by \fBpm_errormsg()\fP.  So don't put any
+newlines or tabs in it.
+
+
+.UN pm_setusererrormsgfn
+.SS pm_setusererrormsgfn()
+
+.B Overview
+.PP
+\fBvoid pm_setusererrormsgfn(pm_usererrormsgfn *\fP \fIfunction\fP\fB);\fP
+
+.B Example
+
+.nf
+\f(CW
+    static pm_usererrormsgfn logfilewrite;
+
+    static void
+    logfilewrite(const char * const msg) {
+        fprintf(myerrorlog, "Netpbm error: %s", msg);
+    }
+
+    pm_setusererrormsgfn(&logfilewrite);
+    
+    pm_errormsg("Message for the error log");
+\fP
+.fi
+.PP
+\fBpm_setusererrormsgfn()\fP registers a handler for error messages,
+called a user error message routine.  Any library function that wants
+to issue an error message in the future will call that function with
+the message as an argument.
+.PP
+The argument the user error message routine gets is English text
+designed for human reading.  It is just the text of the message; there
+is no attempt at formatting in it (so you won't see any newline or tab
+characters).
+.PP
+You can remove the user error message routine, so that the library
+issues future error messages in its default way (write to Standard Error)
+by specifying a null pointer for \fIfunction\fP.
+.PP
+The user error message routine does not handle informational messages.
+It handles only error messages.  See 
+.UR libpm.html#message
+ \fBpm_setusermessagefn()\fP
+.UE
+\&.
+
+
+.SH Error Handling In Netpbm Programs
+.PP
+Most Netpbm programs respond to encountering an error by issuing a
+message describing the error to the Standard Error file and then
+exiting with exit status 1.
+.PP
+Netpbm programs generally do not follow the Unix convention of very
+terse error messages.  Conventional Unix programs produce error
+messages as if they had to pay by the word.  Netpbm programs tend to
+give a complete description of the problem in human-parseable English.
+These messages are often many terminal lines long.
+.SH DOCUMENT SOURCE
+This manual page was generated by the Netpbm tool 'makeman' from HTML
+source.  The master documentation is at
+.IP
+.B http://netpbm.sourceforge.net/doc/liberror.html
+.PP
\ No newline at end of file