Diagnostic output

All WCSLIB functions return a status value, each of which is associated with a fixed error message which may be used for diagnostic output. For example

  int status;
  struct wcsprm wcs;

  ...

  if ((status = wcsset(&wcs)) {
    fprintf(stderr, "ERROR %d from wcsset(): %s.\n", status, wcs_errmsg[status]);
    return status;
  }

This might produce output like

ERROR 5 from wcsset(): Invalid parameter value.

The error messages are provided as global variables with names of the form cel_errmsg, prj_errmsg, etc. by including the relevant header file.

As of version 4.8, courtesy of Michael Droettboom (pywcs), WCSLIB has a second error messaging system which provides more detailed information about errors, including the function, source file, and line number where the error occurred. For example,

  struct wcsprm wcs;

  /* Enable wcserr and send messages to stderr. */
  wcserr_enable(1);
  wcsprintf_set(stderr);

  ...

  if (wcsset(&wcs) {
    wcsperr(&wcs);
    return wcs.err->status;
  }

In this example, if an error was generated in one of the prjset() functions, wcsperr() would print an error traceback starting with wcsset(), then celset(), and finally the particular projection-setting function that generated the error. For each of them it would print the status return value, function name, source file, line number, and an error message which may be more specific and informative than the general error messages reported in the first example. For example, in response to a deliberately generated error, the twcs test program, which tests wcserr among other things, produces a traceback similar to this:

ERROR 5 in wcsset() at line 1564 of file wcs.c:
  Invalid parameter value.
ERROR 2 in celset() at line 196 of file cel.c:
  Invalid projection parameters.
ERROR 2 in bonset() at line 5727 of file prj.c:
  Invalid parameters for Bonne's projection.

Each of the structs in WCSLIB includes a pointer, called err, to a wcserr struct. When an error occurs, a struct is allocated and error information stored in it. The wcserr pointers and the memory allocated for them are managed by the routines that manage the various structs such as wcsinit() and wcsfree().

wcserr messaging is an opt-in system enabled via wcserr_enable(), as in the example above. If enabled, when an error occurs it is the user's responsibility to free the memory allocated for the error message using wcsfree(), celfree(), prjfree(), etc. Failure to do so before the struct goes out of scope will result in memory leaks (if execution continues beyond the error).