Event Specification Modifiers

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.

-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.

-resumeone

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 Using a Filter With a Conditional Event.

-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.

-disable

The-disable modifier creates the handler in the disabled state.

-count n-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).

-temp

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.

-instr

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.

-thread thread_id

The action is executed only if the thread that caused the event matches 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.

-lwp lwp_id

The action is executed only if the thread that caused the event matches lwp_id. The action is executed only if the thread that caused the event matches lwp_id. The specific thread you have in mind might be assigned a different lwp_id from one execution of the program to the next.

-hidden

Hides the handler in a regular status command. Use status -h to see hidden handlers.

-perm

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.