An event specification modifier sets additional attributes of a handler, the most common kind being event filters. Modifiers must appear after the keyword portion of an event specification. A modifier begins with a dash (-). The following are the valid event specification modifiers.
The syntax for the -if modifier is:
-if condition
The condition is evaluated when the event specified by the event specification occurs. The side effect of the handler is allowed only if the condition evaluates to nonzero.
If the –if modifier is used with an event that has an associated singular source location, such as in or at, condition is evaluated in the scope corresponding to that location. Otherwise, qualify it with the desired scope.
Macro expansion is performed on the condition according to same conventions as with the print command.
The –resumeone modifier can be used with the -if modifier in an event specification for a multithreaded program, and causes only one thread to be resumed if the condition contains function calls. For more information, see Qualifying Breakpoints With Conditional Filters.
The syntax for the -in modifier is:
-in function
The event triggers only if it occurs between the time the first instruction of the given function is reached and the time the function returns. Recursion on the function are ignored.
The–disable modifier creates the handler in the disabled state.
The syntax for the -count modifier is:
-count n
or
-count infinity
The –count n and - count infinity modifiers have the handler count from 0 (see Using Event Counters). Each time the event occurs, the count is incremented until it reaches n. Once that happens, the handler fires and the counter is reset to zero.
Counts of all enabled handlers are reset when a program is run or rerun. More specifically, they are reset when the sync event occurs.
The count is reset when you begin debugging a new program with the debug –r command (see debug Command) or the attach –r command (see attach Command).
The -temp modifier creates a temporary handler. Once the event has occurred it is automatically deleted. By default, handlers are not temporary. If the handler is a counting handler, it is automatically deleted only when the count reaches 0 (zero).
Use the delete -temp command to delete all temporary handlers.
The -instr modifier makes the handler act at an instruction level. This event replaces the traditional ’i’ suffix of most commands. It usually modifies two aspects of the event handler:
Any message prints assembly-level rather than source-level information.
The granularity of the event becomes instruction level. For instance, step –instr implies instruction-level stepping.
The syntax for the -thread modifier is:
-thread thread-ID
The -thread modifier means the action is executed only if the thread that caused the event matches a different thread ID. The specific thread you have in mind might be assigned a different thread ID from one execution of the program to the next.
The syntax for the -lwp modifier is:
-lwp lwp-ID
The -lwp modifier means the action is executed only if the -lwp that caused the event matches lwp-ID. The specific -lwp you have in mind might be assigned a different lwp-ID from one execution of the program to the next.
The -hidden modifier hides the handler in a regular status command. Use status –h to see hidden handlers.
Normally all handlers are thrown away when a new program is loaded. Using the –perm modifier retains the handler across debugging sessions. A plain delete command does not delete a permanent handler. Use delete –p to delete a permanent handler.