int status; struct wcsprm wcs; ... if ((status = wcsset(&wcs)) { fprintf(stderr, "ERROR %d from wcsset(): %s.\n", status, wcs_errmsg[status]); return status; }
ERROR 5 from wcsset(): Invalid parameter value.
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; }
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 wcsini() 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).