Augmenting the Displayed Information

You may provide a special function for each of your data types that makes additional information available to Prism. This enables Prism to more accurately display the contents of structures with that data type.

For C or C++ union types, you may identify which member of the union is valid. For a pointer within a structure, you may specify that the pointer's target is an array of elements, rather than a single element, and you may further specify the length of the array.

You must embed these specifications within a special function that is compiled and linked with your program being debugged. The function has the following form:

void prism_define_typename (typename *ptr);

where typename is the tag name of one of your structure data types. Thus, you can define one such function for each of your data types. When Prism displays a variable of this type, it checks whether an augmentation function is defined in the program. If so, Prism calls the function, passing a pointer to the instance of the structure being displayed. Your function may then look at the instance to choose valid union members and to size dynamic arrays.

You communicate this information back to Prism by calling the following, defined in prism.h:

void prism_add_array(char *member_name, int len);

This call specifies that the pointer named member_name points to an array of length len. The pointer's name, member_name, is the name of one of the members of the structure, as found in the structure's C (or C++) declaration. The results are undefined if member_name is not a pointer.

void prism_add_union(char *name, char
*valid_member);

This call specifies that the member named name is of type union, and of all the members of this union, only valid_member is to be displayed. Both name and valid_member are names as found in the C or C++ declarations of structs or unions.

Assume that data in the declaration below is a dynamic array:

 struct Vector {
      int len;
      int *data;
   };

The function you write looks like this:

#include "prism.h"
     void prism_define_Vector(struct
Vector *v)
   {
     prism_add_array("data",
v->len);
   }

Assume that the member type discriminates the union value in this example:

 enum Type {INT, DOUBLE};
     struct Value {
      enum Type type;
       union
{
        int
i;
        double
d;
      } value;
    };

The function you write would look like this:

#include "prism.h"
    void prism_define_Value(struct Value
*val)
     {
        if
(val->type == INT)
            prism_add_union("value",
"i");
        else
        prism_add_union("value",
"d");
     }

There are no restrictions on the number or order of calls to prism_add_union and prism_add_array.