next up previous
Next: Using the C Interface - a Few Peculiarities
Up: THE NDF_ LIBRARY C INTERFACE
Previous: THE NDF_ LIBRARY C INTERFACE

Conventions Used in the C Interface  

Although the NDF_ library is implemented mainly in Fortran, an interface is provided which allows it to be called from programs written in C (see Appendix [*] for a list of the C functions available). Of course, most of the rest of this document describes the Fortran interface, but it is quite easy to translate the descriptions and examples into C once you are aware of the conventions used. The following notes are intended to assist with this:

1.
C function names are derived from the corresponding Fortran routine names by removing the underscore, converting to lower case and then capitalising the fourth character. Thus, the Fortran routine NDF_ABCDEF becomes the C function ndfAbcdef.
2.
A single header file ``ndf.h'' is provided to define the C interface. This contains function prototypes together with C equivalent definitions for all the symbolic constants and error codes used by the Fortran version. All the constants use exactly the same names (in upper case) as in Fortran. It is recommended that you always include this file, since some functions may be implemented via C macros and will therefore only be available in this way.

3.
The data types used in Fortran and C for routine arguments and returned values are related as follows:

Fortran Type C Type
DOUBLE PRECISION double
REAL float
INTEGER int
LOGICAL int
CHARACTER char *

Note that the C interface uses ``int'' for both the Fortran INTEGER and LOGICAL data types, but interprets the latter according to whether the C integer is non-zero or zero (corresponding with Fortran's .TRUE. and .FALSE. respectively).

4.
Input scalar arguments are always passed in C by value.

5.
Non-scalar input arguments (typically strings) are passed in C by pointer, qualified by ``const'' as appropriate.

6.
All output arguments are passed in C by pointer. In the case of output array arguments, the caller must ensure that adequate space has been allocated to receive the returned values (also see the notes on passing character strings below). The C array notation ``[ ]'' is used in the function prototypes to indicate where a returned value is an array rather than a scalar value.

7.
All C strings should be null-terminated.

8.
Whenever a C string value is to be returned (via a argument ``arg'', say, with type char *), the argument is followed in C by an associated integer length argument (``arg_length'') which does not appear in the Fortran version of the routine. This additional argument specifies the length of the character array allocated to receive the string, including the final null. Truncation of the returned string will occur if this length would be exceeded.

9.
An array of character strings is passed in C as an array of pointers to null-terminated strings (like the standard argument vector passed to the C ``main'' function).

10.
A few functions pass HDS locators. These are stored in character arrays, but they are not strings and hence are not null-terminated. The number of array elements required is given by the HDS constant DAT__SZLOC.

11.
Strings which are used to describe the data type of NDF components must contain the same text in C as in Fortran. Hence, you should continue to use ``_REAL'', for example, (and not ``_FLOAT'') when specifying the data type of a new NDF.

12.
When mapping NDF array components, the C interface will usually return a pointer to void, reflecting the fact that the data type is determined at run time and is therefore not known to the mapping function. To access the mapped data, you should cast this pointer to the appropriate pointer type before use, as follows:

Mapped Data Type C Pointer Cast
_DOUBLE (double *)
_REAL (float *)
_INTEGER (int *)
_WORD (short *)
_UWORD (unsigned short *)
_BYTE (signed char *)
_UBYTE (unsigned char *)

13.
Remember that the data storage order used when mapping multi-dimensional array data follows the Fortran convention (where the first array index varies most rapidly) and not the C convention (where the final array index varies most rapidly).

14.
Several functions pass pointers to Objects defined by the AST library (SUN/211) for handling world coordinate system information. These use the same C argument passing conventions for these pointers as used in the AST library itself.


next up previous
Next: Using the C Interface - a Few Peculiarities
Up: THE NDF_ LIBRARY C INTERFACE
Previous: THE NDF_ LIBRARY C INTERFACE


Starlink User Note 33
R.F. Warren-Smith
11th January 2000
E-mail:rfws@star.rl.ac.uk

Copyright © 2000 Council for the Central Laboratory of the Research Councils