Debian Codegraph @

upstream/opensuse-tumbleweed/man1/liberror.1

raw
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