HP-UX Reference (11i v2 03/08) - 2 System Calls (vol 5)

ManualsBrandsHP ManualsSoftwareHP-UX Reference Manuals

201

202

203

204

205

206

207

208

209

210

mq_receive(2) mq_receive(2)

NAME

mq_receive - receive a message from a message queue

SYNOPSIS

#include <sys/mqueue.h>

ssize_t mq_receive(mqd_t mqdes,

char *msg_ptr,

size_t msg_len,

unsigned int *msg_prio

);

DESCRIPTION

The mq_receive() system call receives the oldest of the highest priority message from the message

queue speciﬁed by mqdes . The selected message is removed from the queue and copied to the buffer

pointed to by the msg_ptr argument. The argument, msg_len, speciﬁes the size of the buffer in bytes. The

value of msg_len should be greater than or equal to the mq_msgsize attribute of the message queue, or

mq_receive() will fail.

If the argument msg_prio is not NULL, the priority of the message removed from the queue is stored in

the location pointed to by msg_prio .

If the speciﬁed message queue is empty and the

O_NONBLOCK ﬂag is not set in the message queue block-

ing status associated with mqdes, mq_receive() will block in priority order, until it can receive a mes-

sage from the queue, or until mq_receive() is interrupted by a signal. If the speciﬁed message queue

is empty and the O_NONBLOCK ﬂag is set in the message queue blocking status associated with mqdes,

mq_receive() will not wait for a message to arrive on the queue and will return with an error.

RETURN VALUE

mq_receive() returns the following values:

n Successful completion. n is the size of the selected message in bytes and the message is

removed from the queue.

-1 Failure. errno is set to indicate the error and no message is removed from the queue.

ERRORS

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

[EAGAIN] The

O_NONBLOCK ﬂag is set in the message queue blocking status associated with

mqdes, and the message queue is empty.

[EBADF] mqdes is not a valid message queue descriptor open for reading.

[EINTR] A signal interrupted the call to

mq_receive().

[EINVAL] msg_ptr points to an invalid address.

[EMSGSIZE] The speciﬁed message buffer size, msg_len , is less than the message size attribute of

the message queue.

[ENOSYS]

mq_receive() is not supported by the implementation.