Caution: This version of this document is no longer maintained. For the latest documentation, see


Attach an “idle” interrupt handler


#include <sys/neutrino.h>

int InterruptHookIdle(
    void (*handler)(uint64_t *, struct qtime_entry *),
    unsigned flags );


A pointer to the handler function; see below.
Flags that specify how you want to attach the interrupt handler. For more information, see Flags,” below.



Use the -l c option to qcc to link against this library. This library is usually included automatically.


The InterruptHookIdle() kernel call attaches the specified interrupt handler to the “idle” interrupt, which is called when the system is idle. This is typically used to implement power management features.

The arguments to the handler functions are:

A pointer to the time, in nanoseconds, when the next timer will expire.
struct qtime_entry *
A pointer to the section of the system page with the time information, including the current time of day.

The simplest idle handler consists of a halt instruction.


The flags argument is a bitwise OR of the following values, or 0:

Flag Description
_NTO_INTR_FLAGS_END Put the new handler at the end of the list of existing handlers (for shared interrupts) instead of the start.
_NTO_INTR_FLAGS_PROCESS Associate the handler with the process instead of the attaching thread.
_NTO_INTR_FLAGS_TRK_MSK Track calls to InterruptMask() and InterruptUnmask() to make detaching the interrupt handler safer.


The interrupt structure allows hardware interrupts to be shared. For example, if two processes take over the same physical interrupt, both handlers are invoked consecutively. When a handler attaches, it's placed in front of any existing handlers for that interrupt and is called first. You can change this behavior by setting the _NTO_INTR_FLAGS_END flag in the flags argument. This adds the handler at the end of any existing handlers.

Processor interrupts are enabled during the execution of the handler. Don't attempt to talk to the interrupt controller chip. The end of interrupt command is issued to the chip by the operating system after processing all handlers at a given level.

The first process to attach to an interrupt unmasks the interrupt. When the last process detaches from an interrupt, the system masks it.

If the thread that attached the interrupt handler terminates without detaching the handler, the kernel does it automatically.


Adding _NTO_INTR_FLAGS_PROCESS to flags associates the interrupt handler with the process instead of the attaching thread. The interrupt handler is removed when the process exits, instead of when the attaching thread exits.


The _NTO_INTR_FLAGS_TRK_MSK flag and the id argument to InterruptMask() and InterruptUnmask() let the kernel track the number of times a particular interrupt handler or event has been masked. Then, when an application detaches from the interrupt, the kernel can perform the proper number of unmasks to ensure that the interrupt functions normally. This is important for shared interrupt values.

Blocking states

This call doesn't block.


An interrupt function ID, or -1 if an error occurs (errno is set).

Use the returned value with the InterruptDetach() function to detach this interrupt handler.


All kernel interrupt entries are in use.
The process doesn't have superuser capabilities.


QNX Neutrino

Cancellation point No
Interrupt handler No
Signal handler Yes
Thread Yes

See also:

InterruptAttach(), InterruptAttachEvent(), InterruptDetach(), InterruptHookTrace()

Writing an Interrupt Handler chapter of the Neutrino Programmer's Guide