sys_mq_notify  [ipc/mqueue.c]


Registers or unregisters for delivery of an asynchronous notification when a new message arrives on the empty POSIX message queue.

Arguments

eax 281
ebx Message queue descriptor.
ecx Pointer to a properly initialized sigevent structure:
struc sigevent
{
.sigev_value    sigval
.sigev_signo    rd 1
.sigev_notify   rd 1
._tid:          ;rd 1
._sigev_thread: ;sigev_thread
._pad           rd 13
}

struc sigev_thread
{
._function  rd 1
._attribute rd 1
}

struc sigval
{
.sival_int: ;rd 1
.sival_ptr  rd 1
}

sigevent members:

sigev_value
Data passed with notification.
sigev_signo
Notification signal.
sigev_notify
Notification method. If sigev_notify is a non-NULL pointer, then sys_mq_notify registers the calling process to receive message notification. If sigev_notify is NULL, and the calling process is currently registered to receive notifications for this message queue, then the registration is removed; another process can then register to receive a message notification for this queue.
Following notification are supported:
SIGEV_NONE A "null" notification: the calling process is registered as the target for notification, but when a message arrives, no notification is sent.
SIGEV_SIGNAL Notify the process by sending the signal specified in sigev_signo. If the signal is caught with a signal handler that was registered using the sys_sigaction SA_SIGINFO flag, then the following fields are set in the siginfo_t structure that is passed as the second argument of the handler: si_code is set to SI_MESGQ; si_signo is set to the signal number; si_value is set to the value specified in sigev_value; si_pid is set to the PID of the process that sent the message; and si_uid is set to the real user ID of the sending process.
SIGEV_THREAD Deliver notification by invoking _function as the start function of a new thread. The function is invoked with sigev_value as its sole argument. If _attribute is not NULL, then it should point to a pthread_attr_t structure that defines attributes for the thread.
pthread_attr_t defined as follows:
_tid
*to be documented*
_function
Pointer to the function for thread notification.
_attribute
Pointer to the thread function attributes.

Return values

If the system call succeeds the return value is 0.
If the system call fails the return value is one of the following errno values:

-EFAULT ecx points to an invalid location.
-EINVAL sigev_notify is not one of the permitted values; or sigev_notify is SIGEV_SIGNAL and sigev_signo is not a a valid signal number.
-ENOMEM Insufficient memory.
-EBADF ebx refers to an invalid message queue descriptor.
-EBUSY Another process has already registered to receive notification for this message queue.
-EACCESS *to be documented*
-ENOTSOCK *to be documented*

Remarks

Message notification only occurs when a new message arrives and the queue was previously empty. If the queue was not empty at the time sys_mq_notify was called, then a notification will only occur after the queue is emptied and a new message arrives.

If another process or thread is waiting to read a message from an empty queue using sys_mq_receive, then any message notification registration is ignored: the message is delivered to the process or thread calling sys_mq_receive, and the message notification registration remains in effect.

Notification occurs once: after a notification is delivered, the notification registration is removed, and another process can register for message notification. If the notified process wishes to receive the next notification, it can use sys_mq_notify to request a further notification. This should be done before emptying all unread messages from the queue. (Placing the queue in non-blocking mode is useful for emptying the queue of messages without blocking once it is empty.)

Compatibility

n/a