PGSBOX, which is provided as a separate part of WCSLIB, is a PGPLOT routine (PGPLOT being a Fortran graphics library) that draws and labels curvilinear coordinate grids. Example PGSBOX grids can be seen at http://www.atnf.csiro.au/people/Mark.Calabretta/WCS/PGSBOX/index.html.

The prologue to pgsbox.f contains usage instructions. pgtest.f and cpgtest.c serve as test and demonstration programs in Fortran and C and also as well- documented examples of usage.

PGSBOX requires a separate routine, EXTERNAL NLFUNC, to define the coordinate transformation. Fortran subroutine PGCRFN (pgcrfn.f) is provided to define separable pairs of non-linear coordinate systems. Linear, logarithmic and power-law axis types are currently defined; further types may be added as required. A C function, pgwcsl_(), with Fortran-like interface defines an NLFUNC that interfaces to WCSLIB 4.x for PGSBOX to draw celestial coordinate grids.

PGPLOT is implemented as a Fortran library with a set of C wrapper routines that are generated by a software tool. However, PGSBOX has a more complicated interface than any of the standard PGPLOT routines, especially in having an EXTERNAL function in its argument list. Consequently, PGSBOX is implemented in Fortran but with a hand-coded C wrapper, cpgsbox().

As an example, in this suite the C test/demo program, cpgtest, calls the C wrapper, cpgsbox(), passing it a pointer to pgwcsl_(). In turn, cpgsbox() calls PGSBOX, which invokes pgwcsl_() as an EXTERNAL subroutine. In this sequence, a complicated C struct defined by cpgtest is passed through PGSBOX to pgwcsl_() as an INTEGER array.

While there are no formal standards for calling Fortran from C, there are some fairly well established conventions. Nevertheless, it's possible that you may need to modify the code if you use a combination of Fortran and C compilers with linkage conventions that differ from that of the GNU compilers, gcc and g77.