AddSoftBreakpoint

Syntax

  #include <netware.h> 
   
  int  AddSoftBreakpoint (
     void             *addr,
     SoftBPHandler_t   handler );
  

Parameters

addr

(IN) Points to the address of the soft breakpoint.

handler

(IN) Specifies the function to call for the soft breakpoint. See Remarks for the prototype.

Return Values

If successful, returns a handle to the breakpoint.

Remarks

The handler function must conform to the following prototype:

  typedef int (*SoftBPHandler_t)(
     int         number,
     void       *address,
     xframe_t   *frame);
  

The parameters have the following definitions

number

Specifies the number of the breakpoint (0 through 3).

address

Points to the address of the data or the function.

frame

Points to a structure containing exception information. See xframe_t.

If the callback returns EXCEPTION_HANDLED, execution continues. If it returns a nonzero value, execution stops and the internal debugger is activated so you can examine the state of the machine.

See Also

• AddressOfSoftBreakpoint
• RemoveSoftBreakpoint

Example

The following sample codes illustrates how to use soft breakpoints.

The compiled code was linked as a TSR NLM (Flag_On 0x01000000). The soft breakpoint is an execution-only breakpoint and a “break on write” cannot be created using a soft breakpoint.

  #include <screen.h>
  #include <stdlib.h>
  #include <signal.h>
  
  #include <library.h>
  #include <netware.h>
  
  void   term_cleanup( int signal );
  int    bp_handler( int num, void *addr, xframe_t *sf );
  
  int   gStatus = 0;
  int   gHits = 0;
  int   gBreakpoint = -1;
  char  *gEntryPoint;
  void  *gNLMHandle = (void *) NULL;
  
  
  void main
  (
     int   argc,
     char  **argv
  )
  {
     void   *addr;
  
     if (argc < 2)
     {
        consoleprintf("Usage: sbreak <entry-point>\n");
        exit(0);
     }
  
     gNLMHandle  = getnlmhandle();
     gEntryPoint = argv[1];
     addr    = ImportPublicObject(gNLMHandle, gEntryPoint);
  
     if (addr)
     {
        signal(SIGTERM, term_cleanup);
        consoleprintf("Profiling calls to \"%s\"\n", gEntryPoint);
  
        gBreakpoint = AddSoftBreakpoint(addr, bp_handler);
     }
     else
     {
        consoleprintf("Symbol \"%s\" not found.\n", gEntryPoint);
        exit(-1);
     }
  }
  
  void term_cleanup
  (
     int   sig
  )
  {
  #pragma unused(sig)
  
     if (gBreakpoint != -1)
        RemoveSoftBreakpoint(gBreakpoint);
  
     UnImportPublicObject(gNLMHandle, gEntryPoint);
  }
  
  int bp_handler
  (
     int         num,
     void       *addr,
     xframe_t   *sf
  )
  {
  #pragma unused(sf)
  
     consoleprintf("\n%5d \"%s\" (0x%08X)", ++gHits, gEntryPoint);
     return EXCEPTION_HANDLED;
  }