From 74d1e209a24b69480cea55d8689af37f75846555 Mon Sep 17 00:00:00 2001 From: giraffedata Date: Fri, 12 Oct 2007 02:07:12 +0000 Subject: "miscellaneous update" git-svn-id: http://svn.code.sf.net/p/netpbm/code/userguide@431 9d0c8265-081b-0410-96cb-a4ca84ce46f8 --- error.html | 250 ---------------------------------------------------- liberror.html | 250 ++++++++++++++++++++++++++++++++++++++++++++++++++++ libnetpbm_dir.html | 8 +- libnetpbm_draw.html | 18 ++-- libpbm.html | 4 +- libpm.html | 4 +- libppm.html | 8 +- pamscale.html | 13 +-- 8 files changed, 277 insertions(+), 278 deletions(-) delete mode 100644 error.html create mode 100644 liberror.html diff --git a/error.html b/error.html deleted file mode 100644 index 2bd8ad9b..00000000 --- a/error.html +++ /dev/null @@ -1,250 +0,0 @@ - - - -Netpbm User Manual - - -

Error Handling

- -

Netpbm Programming Library Errors

- -

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. - -

Netpbm's response to encountering an error is called "throwing -an error." - -

The typical way a Netpbm function throws an error (for example, -when you attempt to open a non-existent file with pm_openr()) -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. - -

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. - -

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 -setjmp() and longjmp() functions. - -

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. - -

To select this form of throwing an error, use the -pm_setjmpbuf() function. This alternative is not available -before Netpbm 10.27 (March 2005). - -

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. - -

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 -pm_setusererrormsgfn(). - - -

pm_setjmpbuf()

- -

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. - -

This is not analogous to setjmp(). You do a -setjmp() first, then tell the Netpbm programming library with -pm_setjmpbuf() to use the result. - -

Example: - -

-
-  #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!\n");
-
-  } else {
-    printf("pnm_readpam() failed.  You should have seen "
-           "messages to Standard Error telling you why.\n");
-  }
-
-
- -

This example should look really strange to you if you haven't read -the documentation of setjmp(). Remember that there is a -hyperjump such that the program is executing the pnm_readpam() -and then suddenly is returning a second time from the setjmp()! - -

Even pm_error() works this way -- if you set up a longjmp with -pm_setjmpbuf() and then call pm_error(), pm_error() -will, after issuing your error message, execute the longjmp. - - -

pm_setjmpbuf() was new in Netpbm 10.27 (March 2005). Before -that, Netpbm programming library functions always throw an error by -exiting the program. - - -

User Detected Errors

- -

The Netpbm programming library provides a function for you to throw -an error explicitly: pm_error(). pm_error() does -nothing but throw an error, and does so the same way any Netpbm -library function you call would. pm_error() is more convenient -than most standard C facilities for handling errors. - -

If you don't want to throw an error, but just want to issue an -error message, use pm_errormsg(). It issues the message in the -same way as pm_error() but returns normally instead of longjmping -or exiting the program. - -

Note that libnetpbm distinguishes between an error message -and an informational message (use pm_errormsg() for the former; -pm_message() 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. - - -

pm_error()

- -

Overview

- -

-void pm_error( -char * fmt, -... ); - -

Example

- -
-
-if (argc-1 < 3)
-    pm_error("You must specify at least 3 arguments.  "
-             "You specified" only %d", argc-1);
-
-
- -

pm_error() is a printf() style routine that -simply throws an error. It issues an error message exactly like -pm_errormsg() would in the process. - - -

pm_errormsg()

- -

Overview

- -

-void pm_errormsg( -char * fmt, -... ); - -

Example

- -
-
-if (rc = -1)
-    pm_errormsg("Could not open file.  errno=%d", errno);
-    return -1;
-
-
- -

pm_errormsg() is a printf() 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 pm_setusererrormsgfn. - -

There is very little advantage to using this over traditional C -services, but it issues a message in the same way as libnetpbm -library functions do, so the common handling might be valuable. - -

Note that the arguments specify the message text, not any formatting -of it. Formatting is handled by pm_errormsg(). So don't put any -newlines or tabs in it. - - -

pm_setusererrormsgfn()

- -

Overview

- -

-void pm_setusererrormsgfn(pm_usererrormsgfn * function); - -

Example

- -
-
-    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");
-
-
- -

pm_setusererrormsgfn() 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. - -

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

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 function. - -

The user error message routine does not handle informational messages. -It handles only error messages. See -pm_setusermessagefn(). - - -

Error Handling In Netpbm Programs

- -

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. - -

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. - - - diff --git a/liberror.html b/liberror.html new file mode 100644 index 00000000..2bd8ad9b --- /dev/null +++ b/liberror.html @@ -0,0 +1,250 @@ + + + +Netpbm User Manual + + +

Error Handling

+ +

Netpbm Programming Library Errors

+ +

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. + +

Netpbm's response to encountering an error is called "throwing +an error." + +

The typical way a Netpbm function throws an error (for example, +when you attempt to open a non-existent file with pm_openr()) +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. + +

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. + +

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 +setjmp() and longjmp() functions. + +

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. + +

To select this form of throwing an error, use the +pm_setjmpbuf() function. This alternative is not available +before Netpbm 10.27 (March 2005). + +

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. + +

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 +pm_setusererrormsgfn(). + + +

pm_setjmpbuf()

+ +

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. + +

This is not analogous to setjmp(). You do a +setjmp() first, then tell the Netpbm programming library with +pm_setjmpbuf() to use the result. + +

Example: + +

+
+  #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!\n");
+
+  } else {
+    printf("pnm_readpam() failed.  You should have seen "
+           "messages to Standard Error telling you why.\n");
+  }
+
+
+ +

This example should look really strange to you if you haven't read +the documentation of setjmp(). Remember that there is a +hyperjump such that the program is executing the pnm_readpam() +and then suddenly is returning a second time from the setjmp()! + +

Even pm_error() works this way -- if you set up a longjmp with +pm_setjmpbuf() and then call pm_error(), pm_error() +will, after issuing your error message, execute the longjmp. + + +

pm_setjmpbuf() was new in Netpbm 10.27 (March 2005). Before +that, Netpbm programming library functions always throw an error by +exiting the program. + + +

User Detected Errors

+ +

The Netpbm programming library provides a function for you to throw +an error explicitly: pm_error(). pm_error() does +nothing but throw an error, and does so the same way any Netpbm +library function you call would. pm_error() is more convenient +than most standard C facilities for handling errors. + +

If you don't want to throw an error, but just want to issue an +error message, use pm_errormsg(). It issues the message in the +same way as pm_error() but returns normally instead of longjmping +or exiting the program. + +

Note that libnetpbm distinguishes between an error message +and an informational message (use pm_errormsg() for the former; +pm_message() 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. + + +

pm_error()

+ +

Overview

+ +

+void pm_error( +char * fmt, +... ); + +

Example

+ +
+
+if (argc-1 < 3)
+    pm_error("You must specify at least 3 arguments.  "
+             "You specified" only %d", argc-1);
+
+
+ +

pm_error() is a printf() style routine that +simply throws an error. It issues an error message exactly like +pm_errormsg() would in the process. + + +

pm_errormsg()

+ +

Overview

+ +

+void pm_errormsg( +char * fmt, +... ); + +

Example

+ +
+
+if (rc = -1)
+    pm_errormsg("Could not open file.  errno=%d", errno);
+    return -1;
+
+
+ +

pm_errormsg() is a printf() 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 pm_setusererrormsgfn. + +

There is very little advantage to using this over traditional C +services, but it issues a message in the same way as libnetpbm +library functions do, so the common handling might be valuable. + +

Note that the arguments specify the message text, not any formatting +of it. Formatting is handled by pm_errormsg(). So don't put any +newlines or tabs in it. + + +

pm_setusererrormsgfn()

+ +

Overview

+ +

+void pm_setusererrormsgfn(pm_usererrormsgfn * function); + +

Example

+ +
+
+    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");
+
+
+ +

pm_setusererrormsgfn() 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. + +

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). + +

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 function. + +

The user error message routine does not handle informational messages. +It handles only error messages. See +pm_setusermessagefn(). + + +

Error Handling In Netpbm Programs

+ +

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. + +

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. + + + diff --git a/libnetpbm_dir.html b/libnetpbm_dir.html index 0221df94..282040fa 100644 --- a/libnetpbm_dir.html +++ b/libnetpbm_dir.html @@ -53,10 +53,10 @@ services.

  • pm_ungamma709()
  • pm_message()
  • pm_setusermessagefn() -
  • pm_error() -
  • pm_errormsg() -
  • pm_setusererrormsgfn() -
  • pm_setjmpbuf() +
  • pm_error() +
  • pm_errormsg() +
  • pm_setusererrormsgfn() +
  • pm_setjmpbuf()
  • pm_keymatch() diff --git a/libnetpbm_draw.html b/libnetpbm_draw.html index 168ed0e0..39543dfc 100644 --- a/libnetpbm_draw.html +++ b/libnetpbm_draw.html @@ -42,8 +42,6 @@ in this facility.

    ppmd_filledrectangle

    -

    ppmd_fill_init

    -

    ppmd_fill_drawproc

    ppmd_fill

    @@ -65,7 +63,7 @@ can create additional fonts and use them instead.

    In a program that uses Netpbm drawing facilities, there is a "current font." all drawing of text uses the current font. When the program starts, the current font is "standard"; you -can change it after that by calling the ppmd_setfont function. +can change it after that by calling the ppmd_set_font function.

    Other than a built-in font, a font lives in file in a format special to Netpbm called Ppmdfont. The file typically has a name that @@ -86,7 +84,7 @@ example. In Netpbm source code, you will find the C source file standardppmdfont.c, which was generated from the file standard.ppmdfont by ppmdcfont. You simply use a pointer to the structure that the C file defines as a font handle, -just like one you would get from ppmd_readfont. +just like one you would get from ppmd_read_font.

    Font File Format

    @@ -104,28 +102,28 @@ vector, not raster, font.

    These functions are declared in the header file ppmdfont.h. -

    ppmd_readfont

    +

    ppmd_read_font

    This function associates a Ppmdfont file, which you identify by naming the Ppmdfont file, with a handle that you can use to identify the font to other functions. Technically, this function reads the font into memory. -

    ppmd_freefont

    +

    ppmd_free_font

    This function releases the handle that you get from -ppmd_readfont. It frees resources associated with it; you +ppmd_read_font. It frees resources associated with it; you can't use the handle after this. -

    ppmd_getfont

    +

    ppmd_get_font

    This function returns the handle of the currently selected font. -

    ppmd_setfont

    +

    ppmd_set_font

    This function sets the currently selected font. You identify the font to which to set it with a handle such as you get from -ppmd_readfont or ppmd_getfont. +ppmd_read_font or ppmd_get_font.

      diff --git a/libpbm.html b/libpbm.html index 22cca2af..2243c9cf 100644 --- a/libpbm.html +++ b/libpbm.html @@ -226,7 +226,7 @@ there may be white space between images. image, it returns *eofP false (0). If there is no next image in the file, it returns *eofP true . If it can't position or determine the file status due to a file error, it -throws an error. +throws an error.

    pbm_check() checks for the common file integrity error where the file is the wrong size to contain all the image data. @@ -235,7 +235,7 @@ header (as if pbm_readpbminit() was the last operation on the file). It checks the file size to see if the number of bytes left in the file are the number required to contain the image raster. If the file is too short, pbm_check() causes the program t throws an error. Otherwise, it returns +href="liberror.html#error">throws an error. Otherwise, it returns one of the following values (enumerations of the enum pm_check_code type) as *retval: diff --git a/libpm.html b/libpm.html index 1cd3ae88..a4a4f987 100644 --- a/libpm.html +++ b/libpm.html @@ -474,7 +474,7 @@ specifying the -quiet option.

    Netpbm distinguishes between error messages and information messages; pm_message() is just for informational messages. To issue an error message, see -pm_errormsg(). +pm_errormsg().

    pm_setusermessagefn registers a handler for informational messages, called a user message routine. Any library function @@ -489,7 +489,7 @@ characters).

    To capture error messages in addition to informational messages, see -pm_setusererrormsgfn(). +pm_setusererrormsgfn().

    You can remove the user message routine, so that the library issues future informational messages in its default way (write to Standard diff --git a/libppm.html b/libppm.html index 44883834..015d76fc 100644 --- a/libppm.html +++ b/libppm.html @@ -520,7 +520,7 @@ it was in use before MIT came up with the similar and preferred rgbi style).

    If the color specification does not conform to any of these formats, including the case that it is a name, but is not in the system color dictionary, ppm_parsecolor() throws an error. +href="liberror.html">throws an error.

    ppm_colorname

    @@ -535,7 +535,7 @@ color does not appear in it and hexok is false, ppm_colorname() returns the name of the closest matching color in the color file. Finally, if there is no system color dictionary available and hexok is false, ppm_colorname() fails and -throws an error. +throws an error.

    The string returned is in static libppm library storage which is overwritten by every call to ppm_colorname(). @@ -614,7 +614,7 @@ one of many things that could be represented by it).

    This creates a colorhash_table using dynamically allocated storage. There are no colors in it. If there is not enough storage, -throws an error. +throws an error.

    void ppm_freecolorhash() @@ -677,7 +677,7 @@ the index in the input colorhist_vector for that color. the input.

    If the same color appears twice in the input, -ppm_colorhisttocolorhash() throws an +ppm_colorhisttocolorhash() throws an error.

    ncolors is the number of colors in chv. diff --git a/pamscale.html b/pamscale.html index 7a23842d..855649ec 100644 --- a/pamscale.html +++ b/pamscale.html @@ -383,7 +383,7 @@ function. pamscale offers many other filter functions, though. Some of these approximate sinc and are faster to compute. For most of them, I have no idea of the mathematical explanation for them, but people do find they give pleasing results. They may not be based on -resampling at all, but just exploit the fact the convolution that is +resampling at all, but just exploit the convolution that is coincidentally part of a resampling calculation.

    For some filter functions, you can tell just by looking at the @@ -395,11 +395,12 @@ fact a step function -- the very one we computed as the first step in the resampling. This is mathematically equivalent to the discrete sampling method. -

    The box (rectangle) filter assumes the original image is a piecewise -linear function. Its graph just looks like straight lines connecting -the pixel values. This is mathematically equivalent to the pixel mixing -method when scaling down, and interpolation (ala pamstretch) -when scaling up. +

    The box (rectangle) filter assumes the original image is a +piecewise linear function. Its graph just looks like straight lines +connecting the pixel values. This is mathematically equivalent to the +pixel mixing method (but mixing brightness, not light intensity, so +like pamscale -linear) when scaling down, and interpolation +(ala pamstretch) when scaling up.

    Gamma

    -- cgit 1.4.1