Attach a handler function to a pulse code


#include <sys/iofunc.h>
#include <sys/dispatch.h>

int pulse_attach( dispatch_t * dpp,
                  int flags,
                  int code,
                  int (* func)
                      ( message_context_t * ctp,
                        int code,
                        unsigned flags,
                        void * handle ),
                  void * handle );


The dispatch handle, as returned by a successful call to dispatch_create().
Currently, the following flag is defined in <sys/dispatch.h>:
  • MSG_FLAG_ALLOC_PULSE — allocate and attach a pulse code that's different than any other code that was either given to pulse_attach() through the code argument, or allocated by pulse_attach(). The allocated code is in the range _PULSE_CODE_MINAVAIL through _PULSE_CODE_MAXAVAIL.
The pulse code that you want to attach the function to. You can use one of the predefined _PULSE_CODE_* codes in <sys/neutrino.h>, or you can use your own value in the range from _PULSE_CODE_MINAVAIL to _PULSE_CODE_MAXAVAIL. This argument is ignored if you specify MSG_FLAG_ALLOC_PULSE in the flags.
The function that you want to call when a message in the given range is received; see below, as well as Handler function in the documentation for message_attach().
An arbitrary handle that you want to associate with data for the defined message range. This handle is passed to func.



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


The pulse_attach() function attaches a pulse code to a user-supplied function, func. You can use the same function func with message_attach(). By examining ctp->rcvid, the func function can determine whether a pulse or message was received.

When the resource manager receives a pulse that matches code, it calls func. This user-supplied function is responsible for doing any specific work needed to handle the pulse identified by ctp->msg->pulse. The handle passed to the function is the handle initially passed to pulse_attach(). The handle may be a device entry you want associated with the pulse code. Your function should return 0; other return values are reserved.

You typically use pulse_attach() to associate pulses generated by interrupt handlers or timers with a routine in the main program of your resource manager.

Note: Your process needs the PROCMGR_AID_PUBLIC_CHANNEL ability enabled in order to create a public channel (i.e., without _NTO_CHF_PRIVATE set). For more information, see procmgr_ability().


If MSG_FLAG_ALLOC_PULSE is specified, the function returns the allocated pulse code; otherwise, it returns the code that's passed in. On failure, -1 is returned (errno is set).


Couldn't allocate a pulse code.
You're attaching a handler for _PULSE_CODE_COIDDEATH, and the dispatch handle can't accept such a handler. A dispatch handle can accept such a handler if any of the following is true:
  • The dpp was the first dispatch handle created in the process with dispatch_create().
  • The dpp was the first dispatch handle created in the process with dispatch_create() after the destruction of a dispatch handle that could accept such a handler.
  • The dpp was a dispatch handle created with dispatch_create_channel() with the DISPATCH_CHANNEL_COIDDEATH flag set.
The pulse code is out of range, or it's already registered.
Insufficient memory to allocate internal data structures.
The calling process doesn't have the required permission; see procmgr_ability().


#include <sys/dispatch.h>
#include <time.h>
#include <stdio.h>    
#include <stdlib.h>
int my_func( … ) {


int main( int argc, char **argv ) {
   dispatch_t    *dpp;
   int           flag = 0, code, mycode;
   if ( ( dpp = dispatch_create() ) == NULL ) {
      fprintf( stderr, "%s: Unable to allocate \
               dispatch handle.\n",argv[0] );
      return EXIT_FAILURE;


   mycode = …;

   if ( (code = pulse_attach( dpp, flag, mycode,
                &my_func, NULL)) == -1 ) {
      fprintf ( stderr, "Failed to attach code %d.\n", mycode );
      return 1;
   /* else successfully attached a pulse code */

For examples using the dispatch interface, see dispatch_create(), message_attach(), resmgr_attach(), and thread_pool_create().


QNX Neutrino

Cancellation point Yes
Interrupt handler No
Signal handler No
Thread No