HP-UX Reference (11i v3 07/02) - 2 System Calls (vol 5)

ManualsBrandsHP ManualsSoftwareHP-UX Reference Manuals

221

222

223

224

225

226

227

228

229

230

mq_notify(2) mq_notify(2)

NAME

mq_notify() - register or cancel a notiﬁcation request with a message queue

SYNOPSIS

#include <sys/mqueue.h>

int mq_notify(mqd_t mqdes, const struct sigevent *notification);

DESCRIPTION

If the argument notiﬁcation is not NULL, the

mq_notify() system call registers the calling process to

be notiﬁed of message arrival at an empty message queue associated with the message queue descriptor

mqdes. The notiﬁcation speciﬁed by the notiﬁcation argument will be sent to the process when the message

queue transitions from the empty state to the non-empty state.

If the type of notiﬁcation speciﬁed in notiﬁcation

->sigev_notify

is SIGEV_SIGNAL , then the signal

speciﬁed in notiﬁcation

->sigev_signo will be sent to the process. If the SA_SIGINFO ﬂag is set for

that signal number, then the value speciﬁed in notiﬁcation

->sigev_value will be the si_value com-

ponent of the

siginfo_t structure passed to the signal catching function at the time of signal delivery.

At any time, only one process can be registered for notiﬁcation with a message queue. If the calling pro-

cess, or any other process has already registered for notiﬁcation with the speciﬁed message queue, subse-

quent attempts to register with that queue will fail.

If notiﬁcation is NULL and the process is currently registered for notiﬁcation with the speciﬁed message

queue, the existing registration is canceled.

When the notiﬁcation is sent to the registered process, its registration is removed. The message queue is

then available for registration.

If there is some process blocked in mq_receive() waiting to receive a message from a message queue,

the arrival of a message on the queue will satisfy the mq_receive() , even if the queue has a registered

notiﬁcation request. The resulting behavior is as if the message queue remains empty, and no notiﬁcation

is sent.

To use this function, link in the realtime library by specifying -lrt on the compiler or linker command

line.

RETURN VALUE

mq_notify() returns the following values:

0 Successful completion.

-1 Failure. errno is set to indicate the error.

ERRORS

If mq_notify() fails, errno is set to one of the following values:

[EAGAIN] The system lacks sufﬁcient signal queuing resources to honor the request.

[EBADF] The mqdes argument is not a valid message queue descriptor.

[EBUSY] A process is already registered for notiﬁcation with the message queue.

[EINVAL] An attempt was made to cancel a non-existent notiﬁcation request, or notiﬁcation

points to an invalid address.

[ENOSYS] mq_notify() is not supported by the implementation.