sigevent

Description:

The sigevent structure describes an event. POSIX specifies the basic structure and allows a lot of leeway in extending it. It effectively includes these members (although they aren't all usable at the same time):

The value of sigev_notify indicates how the notification is to occur and which of the other members are used:

• SIGEV_INTR
• SIGEV_MEMORY
• SIGEV_NONE
• SIGEV_PULSE
• SIGEV_SEM
• SIGEV_SIGNAL
• SIGEV_SIGNAL_CODE
• SIGEV_SIGNAL_THREAD
• SIGEV_THREAD
• SIGEV_UNBLOCK

SIGEV_SET_TYPE( &my_event, SIGEV_PULSE )

if( my_event.sigev_notify == SIGEV_PULSE )

if( SIGEV_GET_TYPE(&my_event) == SIGEV_PULSE )

The kernel uses the sigev_handle field for registered events, which are more secure than regular sigevents. For more information, see the entry for MsgRegisterEvent(), as well as Events in the Interprocess Communication (IPC) chapter of the System Architecture guide. By default, you can use only registered events, but you can use the -U option to procnto to allow unregistered events to be used temporarily while you're converting your programs to use registered events.

The <sys/siginfo.h> file also defines some macros to make initializing the sigevent structure easier. All the macros take a pointer to a sigevent structure as their event argument and set the sigev_notify member to the appropriate value. These macros are QNX OS extensions and are described below.

SIGEV_INTR (QNX OS extension)

Send an interrupt notification to a specific thread, depending on the situation:

• If used with MsgSend*(), MsgReceive*(), and MsgDeliverEvent(), the thread is the one identified by the rcvid that MsgReceive*() returns.
• For timers, it's the thread that called timer_settime().
• For InterruptAttachEvent(), it's the thread attaching to the interrupt.

No other fields in the structure are used.

The initialization macro is:
SIGEV_INTR_INIT( &event )

SIGEV_MEMORY (QNX OS extension)

Directly manipulate a location in memory. The following fields are used:

volatile unsigned *sigev_addr

The address of the data that you want to manipulate.

int sigev_value.sival_int

The value to use in the operation.

int sigev_memop

The operation to perform; one of the following:

• SIGEV_MEM_ASSIGN — set the location in memory to the given value.
• SIGEV_MEM_ADD — use atomic_add() to add the value to the location in memory.
• SIGEV_MEM_SUB — use atomic_sub() to subtract the value from the location in memory.
• SIGEV_MEM_BITSET — use atomic_set() to set the bits in the location in memory.
• SIGEV_MEM_BITCLR — use atomic_clr() to clear the bits in the location in memory.
• SIGEV_MEM_BITTOGGLE — use atomic_toggle() to toggle the bits in the location in memory.

For the SIGEV_MEM_BIT* operations, the bits that are set in the value indicate which bits to set, clear, or toggle in the location in memory.

The initialization macro is:
SIGEV_MEMORY_INIT( &event, addr, value, operation )

procmgr_event_notify_add( PROCMGR_EVENT_CONFSTR, my_sigevent );

SIGEV_NONE (POSIX)

Don't send any notification. No other fields in the structure are used.

The initialization macro is:
SIGEV_NONE_INIT( &event )

SIGEV_PULSE (QNX OS extension)

Send a pulse. The following fields are used:

int sigev_coid

The connection ID. This should be attached to the channel with which the pulse will be received.

short sigev_priority

The priority of the pulse, or SIGEV_PULSE_PRIO_INHERIT if you want the thread that receives the pulse to run at the initial priority of the process.

The priority of the pulse must be in the range for the target process, or that process must have the PROCMGR_AID_PRIORITY ability enabled (see procmgr_ability()). If procnto was started with an s appended to the -P option, then out-of-range priority requests use the maximum allowed value instead of resulting in an error.

short sigev_code

A code to be interpreted by the pulse handler. Although sigev_code can be any 8-bit signed value, you should avoid sigev_code values less than zero in order to avoid conflict with kernel or pulse codes generated by a QNX OS manager. These codes all start with _PULSE_CODE_ and are defined in <sys/neutrino.h>; for more information, see the documentation for the _pulse structure. A safe range of pulse values is _PULSE_CODE_MINAVAIL to _PULSE_CODE_MAXAVAIL.

int sigev_value.sival_int or void *sigev_value.sival_ptr

A 32-bit value or a pointer to be interpreted by the pulse handler.

The initialization macros are:

• SIGEV_PULSE_INIT( &event, coid, priority, code, value )

  Store the value in sigev_value.sival_ptr.

• SIGEV_PULSE_INT_INIT( &event, coid, priority, code, value )

  Store the value in sigev_value.sival_int and set the hidden SIGEV_FLAG_SIVAL_INT bit in sigev_notify.

• SIGEV_PULSE_PTR_INIT( &event, coid, priority, code, value )

  Store the value in sigev_value.sival_ptr.

SIGEV_SEM (QNX OS extension)

Increment a named semaphore; this is equivalent to calling sem_post(). The following field is used:

int sigev_coid

The connection ID.

The initialization macro is:
SIGEV_SEM_INIT( &event, &sem )

SIGEV_SIGNAL (POSIX)

Send a signal to a process. The following fields are used:

int sigev_signo

The signal to raise. This must be in the range from 1 through NSIG − 1.

The initialization macro is:
SIGEV_SIGNAL_INIT( &event, signal )

If you need to set the sigev_value for a SIGEV_SIGNAL event (for example if SA_SIGINFO is set), you can use one of these macros instead of SIGEV_SIGNAL_INIT():

• SIGEV_SIGNAL_VALUE_INIT( &event, signal, value )

  Store the value in sigev_value.sival_ptr.

• SIGEV_SIGNAL_VALUE_INT_INIT( &event, signal, value )

  Store the value in sigev_value.sival_int and set the hidden SIGEV_FLAG_SIVAL_INT bit in sigev_notify.

• SIGEV_SIGNAL_VALUE_PTR_INIT( &event, signal, value )

  Store the value in sigev_value.sival_ptr.

SIGEV_SIGNAL_CODE (QNX OS extension)

This is similar to SIGEV_SIGNAL, except that SIGEV_SIGNAL_CODE also includes a value and a code. The following fields are used:

int sigev_signo

The signal to raise. This must be in the range from 1 through NSIG − 1.

short sigev_code

A code to be interpreted by the signal handler. This must be in the range from SI_MINAVAIL through SI_MAXAVAIL.

int sigev_value.sival_int or void *sigev_value.sival_ptr

A 32-bit value or a pointer to be interpreted by the signal handler.

The initialization macros are:

• SIGEV_SIGNAL_CODE_INIT( &event, signal, value, code )

  Store value in sigev_value.sival_ptr.

• SIGEV_SIGNAL_CODE_INT_INIT( &event, signal, value )

  Store the value in sigev_value.sival_int and set the hidden SIGEV_FLAG_SIVAL_INT bit in sigev_notify.

• SIGEV_SIGNAL_CODE_PTR_INIT( &event, signal, value )

  Store the value in sigev_value.sival_ptr.

These macros store the code in sigev_code.

SIGEV_SIGNAL_THREAD (QNX OS extension)

Send a signal to a specific thread, depending on the situation:

• If used with MsgDeliverEvent(), the thread is the one identified by the rcvid that MsgReceive*() returned when you received a message (not a pulse).
• For timers, it's the thread that called timer_settime().
• For InterruptAttachEvent(), it's the thread attaching to the interrupt.

In the case of timers and interrupts, if the thread dies before the event gets delivered, the kernel drops the event.

The following fields are used:

int sigev_signo

The signal to raise. This must be in the range from 1 through NSIG − 1.

short sigev_code

A code to be interpreted by the signal handler. This must be in the range from SI_MINAVAIL through SI_MAXAVAIL.

int sigev_value.sival_int

A 32-bit value to be interpreted by the signal handler.

The initialization macro is:
SIGEV_SIGNAL_THREAD_INIT( &event, signal, value, code )

SIGEV_THREAD (POSIX)

Create a new thread.

The following fields are used:

void (*sigev_notify_function) (union sigval)

A pointer to the function to be notified.

pthread_attr *sigev_notify_attributes

A pointer to thread attributes. This must be NULL, or point to a valid thread attribute structure; that is, a structure initialized by pthread_attr_init() and updated with the appropriate pthread_attr_set*() functions.

Note:

This pointer is stored and then used at the time of event delivery, so the attribute structure must be valid at that time.

void *sigev_value.sival_ptr

A value to be passed to the notification function.

The initialization macro is:
SIGEV_THREAD_INIT( &event, fn,  value, attr )

union sigval {
    int        sival_int;
    void     * sival_ptr;
};

SIGEV_UNBLOCK (QNX OS extension)

Force a thread to become unblocked. No other fields in the structure are used.

The initialization macro is:
SIGEV_UNBLOCK_INIT( &event )

Hidden bits (QNX OS extension)

After you've set up the sigevent structure as appropriate, you can use some extra bits in sigev_notify for other purposes. The bits and their associated macros include:

SIGEV_FLAG_SIVAL_INT

The sigevent was initialized specifically to hold an integer with one of the SIGEV_*_INT_INIT() macros.

SIGEV_FLAG_CODE_UPDATEABLE

Allow the server to update the sigev_code member before the event is delivered. The actual update depends on the server.

To determine if the bit is set, the server should just test it directly:

if (event.sigev_notify & SIGEV_FLAG_CODE_UPDATEABLE)
{ // may update event before delivering }
else
{ // should not update event before delivering } 

SIGEV_FLAG_UPDATEABLE

Allow the server to update the sigev_value member before the event is delivered:

• SIGEV_MAKE_UPDATEABLE( &event )
• SIGEV_CLEAR_UPDATEABLE( &event )

The actual update depends on the server. For information about the updated information for kernel events, see procmgr_event_notify_add().

To determine if the bit is set, the server should just test it directly:

if (event.sigev_notify & SIGEV_FLAG_UPDATEABLE)
{ // may update event before delivering }
else
{ // should not update event before delivering } 

Classification:

POSIX 1003.1, QNX OS extensions