Interface Functions

Memory Block Declaration Routines
Memory Checking Routines
Function Pointer Checks
Opaque Types
Printf/scanf Checking
Utility Functions
Callbacks
Variable Arguments
Initialization
Termination

Interface Functions

This section lists the Insure++ specific functions that can be called from Insure++ interface files. The use of these functions is described in the section " Interfaces". This description gives only a brief summary of the purpose and arguments of the various functions. Probably the best way to see their purpose is to look at the source code for the interfaces shipped with Insure++, which can be found in subdirectories of the main Insure++ installation directory with names such as src.sun4/cc, src.hp9/cc, etc.

Memory Block Declaration Routines

These functions are used to indicate the usage of memory blocks. They do not actually allocate or free memory.

• void iic_alloc(void *ptr, unsigned long size);

  Declares a block of uninitialized heap memory of the given size. (See Writing simple interfaces.)

• void iic_alloca(void *ptr, unsigned long size);

  Declares a block of data on the stack.

• void iic_alloci(void *ptr, unsigned long size);

  Declares a block of initialized heap memory of the given size. (Without the second argument, declares a block the length of the first argument treated as a character string, including the terminating NULL.) (See Common interface functions.)

• void iic_allocs(void *ptr, unsigned long size);

  Declares a pointer to a block of static memory. (Without the second argument, declares a block the length of the first argument treated as a character string, including the terminating NULL.) (See Common interface functions.)

• void iic_realloc(void *old, void *new, unsigned long new_size);

  Indicates that the indicated block has been re-allocated and that the contents of the old block should be copied to the new one.

• void iic_save(void *ptr);

  Specifies that the indicated block should never be reported to have "leaked". Normally, this is used when the system will keep track of a memory block, even after all user pointers have gone.

• void iic_unalloc(void *ptr);

  Deallocates a block of memory. (See Common interface functions.)

• void iic_unallocs(void *ptr);

  Undoes the effect of an iic_allocs. No error checking is performed on the pointer - the block is simply forgotten.

Memory Checking Routines

These functions report the appropriate Insure++ error message if the check fails.

• void iic_copy(void *to, void *from, unsigned long size;)

  Checks for write and read access to the given number of bytes and indicates that the from block will be copied onto the to block. (See Writing simple interfaces.)

• void iic_copyattr(void *to, void *from);

  Copies the attribute properties (e.g., opaque, uninitialized, etc.) from one pointer to another.

• void iic_dest(void *ptr, unsigned long size);

  Checks for write access to the ptr for size number of bytes. (See Common interface functions.)

• void iic_freeable(void *ptr);

  Checks that the indicated pointer indicates a dynamically allocated block of memory that could be freed.

• void iic_justcopy(void *to, void *from, unsigned long size);

  Indicates that the from block will be copied onto the to block without performing the other iic_copy checks.

• void iic_pointer(void *ptr);

  Checks that the indicated pointer is valid, without checking anything about the size of the block it points to.

• void iic_resize(void *ptr, unsigned long newsize);

  Indicates that the block of memory has changed size.

• void iic_source(void *ptr, unsigned long size);

  Checks for read access to ptr for size bytes. (See Common interface functions.) Does no checks for initialization of the block.

• void iic_sourcei(void *ptr, unsigned long size);

  Checks for read access to ptr for size bytes, and also that the memory is initialized. (See Common interface functions.)

• int iic_string(char *ptr, unsigned long size);

  Checks that the pointer indicates a NULL terminated string. (See Common interface functions.) If the optional second argument is supplied, the check terminates after at most that number of characters. In either case, the string length is returned, or -1 if some error prevented the string length from being computed.

Function Pointer Checks

• void iic_declfunc(void (*f)());

  Declares that the indicated pointer is a function regardless of appearance or other information.

• void iic_func(void (*f)());

  Checks that the indicated pointer is actually a function.

Opaque Types

• void iic_opaque(void *ptr);

  Declares that the pointer should never be checked.

• void iic_opaque_type (<typename>);

  Declares that the indicated structure or union type is opaque and should not be checked. (See Opaque pointers.)

• void iic_opaque_subtype (<typename>, <typetag>);

  Declares that the indicated element of a structure or union type is opaque and should not be checked. (See Opaque pointers.)

Printf/scanf Checking

• void iic_input_format(char *format_string);

  Indicates that the indicated string and the arguments following it should be checked as though they were a scanf style format string. This function should be called from the interface before activating the function being checked.

• void iic_output_format (char *format_string);

  Indicates that the indicated string and the arguments following it should be checked as though they were a printf style format string.

• void iic_post_input_format (int ntokens);

  This function can be called after an iic_input_format check and a call to an input function to check that the indicated number of tokens did not corrupt memory when read. If the argument is omitted, all the tokens from the iic_input_format string are checked.

• int iic_strlenf(char *format_string, ...);

  Returns the length of the string after substitution of the subsequent arguments, which are interpreted as a printf style format string.

• int iic_vstrlenf(char *format_string, va_list ap);

  Returns the length of the string after substitution of the argument, which must be the standard type for a variable argument list. The format_string argument is interpreted in the normal printf style.

Utility Functions

• char *iic_c_string(char *string);

  Converts a string to a format consistent with the C language conventions. Useful for printing error messages.

• void iic_error(int code, char *format, ...);

  Generates a message with the indicated error code (either USER_ERROR or RETURN_FAILURE ). (See Checking for errors in system calls.)

• void iic_expand_subtype (<typename>, <typetag>);

  Indicates that the structure or union named typename contains an element name typetag whose size varies at runtime. Normally used for "stretchy" arrays. (See Stretch arrays.) For example, if you have the following code, and a is a stretchy array,

  	    
  		struct test {
              		char a[1];
              	};
  
              

  then the appropriate function call would be:

  
               	iic_expand_subtype(struct test, a);
  
              

• int iic_numargs(void);

  Returns the number of arguments actually passed to the function.

• void iic_warning(char *string);

  Prints the indicated string at compile-time.

Callbacks

• iic_body

  Keyword used in function declarations to indicate that the function for which the interface is being specified will be used as a callback. (See " Using iic_body".)

• void iic_callback(void (*f)(), void (*template)());,

  Specifies that the function f will be used as a callback, and that whenever it is called its invocation is to be processed as indicated by the previously declared (static) function template. (See " Using iic_callback".)

• void iic_opaque_callback (void (*f)());

  Specifies that the function f will be used as a callback, and that all of its arguments should be treated as opaque whenever it is invoked. (See "Which to use: iic_callback or iic_body?".)

Variable Arguments

• __dots__

  Placeholder for variable arguments ("...") in an argument list. (See Interface esoterica.)

Initialization

• void iic_startup(void)

  Function that can be declared in any interface file and which contains calls to be made before any function in the interface is executed. (See Interface esoterica.)

Termination

• void iic_exit(void)

  Indicates that the function specified by the interface is going to exit. This allows Insure++ to close its files and perform any necessary cleanup activity before the program terminates.

Insure++ API

Manpages