HP 3000 Manuals HP 3000 Manuals
msgrcv
Reads a message from a message queue.
Syntax
#include <sys/types.h>
#include <sys/ipc.h>
#include <sys/msg.h>
int msgrcv (int msqid, void *msgp, int msgsz,
long msgtyp, int msgflg);
Parameters
msqid Passes message queue identifier returned by a call to
msgget().
msgp Passes a pointer to a buffer whose structure is similar to the
msgbuf example template located in <msg.h>, for example:
struct example_msgbuf {
long mtype; /* message type */
char mtext[your_buffer_size]; /* message text */
};
where your_buffer_size is an integer specifying the size of
the buffer. The mtype field stores the received message's
type as specified by the process that sent the message. The
mtext field stores the text of the message. The size of mtext
is specified by the msgsz argument.
msgsz Passes the size, in bytes, of mtext. Valid values are from 0
to a system-defined limit.
msgtyp Passes a value specifying the type of message requested.
Following are valid values and their meanings:
0 Read the first message on the queue.
>0 Read the first message on the queue whose type equals
msgtyp.
<0 Read a message from the queue whose type is the lowest
type of all messages in that queue that is less than
or equal to the absolute value of msgtyp.
msgflg Passes a value defining what action to take if either a
message specified by msgtyp is not found on the message queue
or the message is too large to fit in the buffer. Flags are:
IPC_NOWAIT The calling process is not suspended. Control
returns immediately with errno set to ENOMSG.
MSG_NOERROR If the message to receive is larger than msgsz,
the message is truncated to msgsz bytes. No
error indication is given.
If msgflg does not specify IPC_NOWAIT, the calling process
suspends execution until a message satisfying the msgtyp
specifications is placed on the queue. When this occurs,
control returns to msgrcv(). If MSG_NOERROR is not set, and
the selected message is larger than the buffer pointed to by
msgp, msgrcv() returns an error and sets errno to E2BIG.
Return Values
>=0 Success. The number of bytes actually placed into the mtext
field of the data structure pointed to by msgp is returned.
-1 An error occurred, and errno is set to indicate the error
condition.
Description
The msgrcv() function reads a message from the message queue specified by
msqid and places it in the buffer pointed to by msgp.
If the MSG_NOERROR option is set in msgflg, the received message is
truncated to msgsz bytes if it is larger than msgsz. The truncated part
of the message is lost and no indication of the truncation is given.
If the calling process is suspended waiting for a message, the following
conditions will cause msgrcv() to return an error and set errno to
indicate the error condition.
* The message queue specified by msqid is removed from the system
* The calling process receives a signal that is to be caught.
If msgrcv() is successful, the following fields of the data structure
associated with msqid are updated to the indicated values:
msg_qnum Decremented by 1
msg_lrpid PID of the calling process
msg_rtime Current time
Implementation Considerations
If a process suspended during execution of msgrcv() receives a signal,
control returns to the user with errno set to EINTR. Disabled signals are
ignored.
Errors
If an error occurs, errno is set to one of the following values.
E2BIG CAUSE msgsz is less than the size of the message and msgflg
does not specify MSG_NOERROR.
ACTION Increase the msgsz parameter and associated buffer
space, or specify the MSG_NOERROR option to allow
truncation of the received message.
EACCES CAUSE The calling process does not have permission.
ACTION Ensure that the calling process has read access for
the message queue.
EFAULT CAUSE The system detected a NULL or bad address in
attempting to use the msgp argument.
ACTION Check to see if the pointer is correctly initialized.
EIDRM CAUSE The message queue specified by msqid was removed
while the process was suspended in msgrcv().
ACTION None.
EINTR CAUSE A process waited in msgrcv() was interrupted by a
signal.
ACTION Application dependent.
EINVAL CAUSE msqid is not a valid message queue identifier, or
msgsz is less than 0 or greater than the
system-defined limit.
ACTION Check the msqid to make sure it is valid and the
message queue has not been removed from the system.
Verify that a positive msgsz was specified that does
not exceed the currently configured limit.
ENOMSG CAUSE The specified message queue does not contain a
message of the type specified in mtype and msgflg
specifies IPC_NOWAIT.
ACTION None. Application dependent. The receive operation
can be retried.
ESYSERR CAUSE An operating system error occurred that does not map
directly to any of the above errors.
ACTION Examine the MPE/iX process error stack for the type
of system error.
See Also
msgctl(), msgget(), msgsnd(), SVID2 (Section 12)