| 1 |
\ |
| 2 |
.\" This man page was generated by the Netpbm tool 'makeman' from HTML source. |
| 3 |
.\" Do not hand-hack it! If you have bug fixes or improvements, please find |
| 4 |
.\" the corresponding HTML page on the Netpbm website, generate a patch |
| 5 |
.\" against that, and send it to the Netpbm maintainer. |
| 6 |
.TH "Netpbm User Manual" 0 "" "netpbm documentation" |
| 7 |
|
| 8 |
|
| 9 |
|
| 10 |
.UN error |
| 11 |
.SH Netpbm Programming Library Errors |
| 12 |
.PP |
| 13 |
As part of Netpbm's mission to make writing graphics programs quick |
| 14 |
and easy, Netpbm recognizes that no programmer likes to deal with |
| 15 |
error conditions. Therefore, very few Netpbm programming library |
| 16 |
functions return error information. There are no return codes to |
| 17 |
check. If for some reason a function can't do what was asked of it, |
| 18 |
it doesn't return at all. |
| 19 |
.PP |
| 20 |
Netpbm's response to encountering an error is called "throwing |
| 21 |
an error." |
| 22 |
.PP |
| 23 |
The typical way a Netpbm function throws an error (for example, |
| 24 |
when you attempt to open a non-existent file with \fBpm_openr()\fP) |
| 25 |
is that the function writes an error message to the Standard Error |
| 26 |
file and then causes the program to terminate with an exit() system |
| 27 |
call. The function doesn't do any explicit cleanup, because everything |
| 28 |
a library function sets up gets cleaned up by normal process |
| 29 |
termination. |
| 30 |
.PP |
| 31 |
In many cases, that simply isn't acceptable. If you're calling |
| 32 |
Netpbm functions from inside a server program, you'd want the program |
| 33 |
to recognize that the immediate task failed, but keep running to do |
| 34 |
other work. |
| 35 |
.PP |
| 36 |
So as an alternative, you can replace that program exit with a |
| 37 |
longjmp instead. A longjmp is a classic Unix exception handling |
| 38 |
concept. See the documentation of the standard C library |
| 39 |
\fBsetjmp()\fP and \fBlongjmp()\fP functions. |
| 40 |
.PP |
| 41 |
In short, you identify a point in your programs for execution to |
| 42 |
hyperjump to from whatever depths of whatever functions it may be in |
| 43 |
at the time it detects an exception. That hyperjump is called a |
| 44 |
longjmp. The longjmp unwinds the stack and puts the program in the |
| 45 |
same state as if the subroutines had returned all the way up to the |
| 46 |
function that contains the jump point. A longjmp does not in itself |
| 47 |
undo things like memory allocations. But when you have a Netpbm |
| 48 |
function do a longjmp, it also cleans up everything it started. |
| 49 |
.PP |
| 50 |
To select this form of throwing an error, use the |
| 51 |
\fBpm_setjmpbuf()\fP function. This alternative is not available |
| 52 |
before Netpbm 10.27 (March 2005). |
| 53 |
.PP |
| 54 |
Issuing of the error message is a separate thing. Regardless |
| 55 |
of whether a library routine exits the program or executes a longjmp, |
| 56 |
it issues an error message first. |
| 57 |
.PP |
| 58 |
You can customize the error message behavior too. By default, a |
| 59 |
Netpbm function issues an error message by writing it to the Standard |
| 60 |
Error file, formatted into a single line with the program name prefixed. |
| 61 |
But you can register your own error message function to run instead with |
| 62 |
\fBpm_setusererrormsgfn()\fP. |
| 63 |
|
| 64 |
|
| 65 |
.UN pm_setjmpbuf |
| 66 |
.SS pm_setjmpbuf() |
| 67 |
.PP |
| 68 |
pm_setjmpbuf() sets up the process so that when future calls to the |
| 69 |
Netpbm programming library throw an error, they execute a longjmp |
| 70 |
instead of causing the process to exit as they would by default. |
| 71 |
.PP |
| 72 |
This is \fInot\fP analogous to \fBsetjmp()\fP. You do a |
| 73 |
setjmp() first, then tell the Netpbm programming library with |
| 74 |
\fBpm_setjmpbuf()\fP to use the result. |
| 75 |
.PP |
| 76 |
Example: |
| 77 |
|
| 78 |
.nf |
| 79 |
\f(CW |
| 80 |
#include <setjmp.h> |
| 81 |
#include <netpbm/pam.h> |
| 82 |
|
| 83 |
jmp_buf jmpbuf; |
| 84 |
int rc; |
| 85 |
|
| 86 |
rc = setjmp(jmpbuf); |
| 87 |
if (rc == 0) { |
| 88 |
struct pam pam; |
| 89 |
pm_setjmpbuf(&jmpbuf); |
| 90 |
|
| 91 |
pnm_readpam(stdin, &pam, PAM_STRUCT_SIZE(tuple_type)); |
| 92 |
|
| 93 |
printf("pnm_readpam() succeeded!\en"); |
| 94 |
|
| 95 |
} else { |
| 96 |
printf("pnm_readpam() failed. You should have seen " |
| 97 |
"messages to Standard Error telling you why.\en"); |
| 98 |
} |
| 99 |
\fP |
| 100 |
|
| 101 |
.fi |
| 102 |
.PP |
| 103 |
This example should look really strange to you if you haven't read |
| 104 |
the documentation of \fBsetjmp()\fP. Remember that there is a |
| 105 |
hyperjump such that the program is executing the \fBpnm_readpam()\fP |
| 106 |
and then suddenly is returning a second time from the setjmp()! |
| 107 |
.PP |
| 108 |
Even \fBpm_error()\fP works this way -- if you set up a longjmp with |
| 109 |
\fBpm_setjmpbuf()\fP and then call \fBpm_error()\fP, \fBpm_error()\fP |
| 110 |
will, after issuing your error message, execute the longjmp. |
| 111 |
.PP |
| 112 |
\fBpm_setjmpbuf()\fP was new in Netpbm 10.27 (March 2005). Before |
| 113 |
that, Netpbm programming library functions always throw an error by |
| 114 |
exiting the program. |
| 115 |
|
| 116 |
|
| 117 |
.SH User Detected Errors |
| 118 |
.PP |
| 119 |
The Netpbm programming library provides a function for you to throw |
| 120 |
an error explicitly: \fBpm_error()\fP. \fBpm_error()\fP does |
| 121 |
nothing but throw an error, and does so the same way any Netpbm |
| 122 |
library function you call would. \fBpm_error()\fP is more convenient |
| 123 |
than most standard C facilities for handling errors. |
| 124 |
.PP |
| 125 |
If you don't want to throw an error, but just want to issue an |
| 126 |
error message, use \fBpm_errormsg()\fP. It issues the message in the |
| 127 |
same way as \fBpm_error()\fP but returns normally instead of longjmping |
| 128 |
or exiting the program. |
| 129 |
.PP |
| 130 |
Note that \fBlibnetpbm\fP distinguishes between an error message |
| 131 |
and an informational message (use \fBpm_errormsg()\fP for the former; |
| 132 |
\fBpm_message()\fP for the latter). The only practical difference is |
| 133 |
which user message function it calls. So if you don't register any |
| 134 |
user message function, you won't see any difference, but a program is |
| 135 |
still more maintainable and easier to read when you use the |
| 136 |
appropriate one of these. |
| 137 |
|
| 138 |
|
| 139 |
.UN pm_error |
| 140 |
.SS pm_error() |
| 141 |
|
| 142 |
.B Overview |
| 143 |
.PP |
| 144 |
\fBvoid pm_error(\fP |
| 145 |
\fBchar *\fP \fIfmt\fP\fB,\fP |
| 146 |
\fB... );\fP |
| 147 |
|
| 148 |
.B Example |
| 149 |
|
| 150 |
.nf |
| 151 |
\f(CW |
| 152 |
if (argc-1 < 3) |
| 153 |
pm_error("You must specify at least 3 arguments. " |
| 154 |
"You specified" only %d", argc-1); |
| 155 |
\fP |
| 156 |
|
| 157 |
.fi |
| 158 |
.PP |
| 159 |
\fBpm_error()\fP is a \fBprintf()\fP style routine that |
| 160 |
simply throws an error. It issues an error message exactly like |
| 161 |
\fBpm_errormsg()\fP would in the process. |
| 162 |
|
| 163 |
|
| 164 |
.UN pm_errormsg |
| 165 |
.SS pm_errormsg() |
| 166 |
|
| 167 |
.B Overview |
| 168 |
.PP |
| 169 |
\fBvoid pm_errormsg(\fP |
| 170 |
\fBchar *\fP \fIfmt\fP\fB,\fP |
| 171 |
\fB... );\fP |
| 172 |
|
| 173 |
.B Example |
| 174 |
|
| 175 |
.nf |
| 176 |
\f(CW |
| 177 |
if (rc = -1) |
| 178 |
pm_errormsg("Could not open file. errno=%d", errno); |
| 179 |
return -1; |
| 180 |
\fP |
| 181 |
|
| 182 |
.fi |
| 183 |
.PP |
| 184 |
\fBpm_errormsg()\fP is a \fBprintf()\fP style routine that |
| 185 |
issues an error message. By default, it writes the message to Standard |
| 186 |
Error, but you can register a user error message routine to be called |
| 187 |
instead, and that might do something such as write the message into a |
| 188 |
log file. See |
| 189 |
.UR #pm_setusererrormsgfn |
| 190 |
\fBpm_setusererrormsgfn\fP |
| 191 |
.UE |
| 192 |
\&. |
| 193 |
.PP |
| 194 |
There is very little advantage to using this over traditional C |
| 195 |
services, but it issues a message in the same way as \fBlibnetpbm\fP |
| 196 |
library functions do, so the common handling might be valuable. |
| 197 |
.PP |
| 198 |
Note that the arguments specify the message text, not any formatting |
| 199 |
of it. Formatting is handled by \fBpm_errormsg()\fP. So don't put any |
| 200 |
newlines or tabs in it. |
| 201 |
|
| 202 |
|
| 203 |
.UN pm_setusererrormsgfn |
| 204 |
.SS pm_setusererrormsgfn() |
| 205 |
|
| 206 |
.B Overview |
| 207 |
.PP |
| 208 |
\fBvoid pm_setusererrormsgfn(pm_usererrormsgfn *\fP \fIfunction\fP\fB);\fP |
| 209 |
|
| 210 |
.B Example |
| 211 |
|
| 212 |
.nf |
| 213 |
\f(CW |
| 214 |
static pm_usererrormsgfn logfilewrite; |
| 215 |
|
| 216 |
static void |
| 217 |
logfilewrite(const char * const msg) { |
| 218 |
fprintf(myerrorlog, "Netpbm error: %s", msg); |
| 219 |
} |
| 220 |
|
| 221 |
pm_setusererrormsgfn(&logfilewrite); |
| 222 |
|
| 223 |
pm_errormsg("Message for the error log"); |
| 224 |
\fP |
| 225 |
|
| 226 |
.fi |
| 227 |
.PP |
| 228 |
\fBpm_setusererrormsgfn()\fP registers a handler for error messages, |
| 229 |
called a user error message routine. Any library function that wants |
| 230 |
to issue an error message in the future will call that function with |
| 231 |
the message as an argument. |
| 232 |
.PP |
| 233 |
The argument the user error message routine gets is English text |
| 234 |
designed for human reading. It is just the text of the message; there |
| 235 |
is no attempt at formatting in it (so you won't see any newline or tab |
| 236 |
characters). |
| 237 |
.PP |
| 238 |
You can remove the user error message routine, so that the library |
| 239 |
issues future error messages in its default way (write to Standard Error) |
| 240 |
by specifying a null pointer for \fIfunction\fP. |
| 241 |
.PP |
| 242 |
The user error message routine does not handle informational messages. |
| 243 |
It handles only error messages. See |
| 244 |
.UR libpm.html#message |
| 245 |
\fBpm_setusermessagefn()\fP |
| 246 |
.UE |
| 247 |
\&. |
| 248 |
|
| 249 |
|
| 250 |
.SH Error Handling In Netpbm Programs |
| 251 |
.PP |
| 252 |
Most Netpbm programs respond to encountering an error by issuing a |
| 253 |
message describing the error to the Standard Error file and then |
| 254 |
exiting with exit status 1. |
| 255 |
.PP |
| 256 |
Netpbm programs generally do not follow the Unix convention of very |
| 257 |
terse error messages. Conventional Unix programs produce error |
| 258 |
messages as if they had to pay by the word. Netpbm programs tend to |
| 259 |
give a complete description of the problem in human-parseable English. |
| 260 |
These messages are often many terminal lines long. |
| 261 |
.SH DOCUMENT SOURCE |
| 262 |
This manual page was generated by the Netpbm tool 'makeman' from HTML |
| 263 |
source. The master documentation is at |
| 264 |
.IP |
| 265 |
.B http://netpbm.sourceforge.net/doc/liberror.html |
| 266 |
.PP |