COHERENT manpages
This page displays the COHERENT manpage for msgrcv() [Receive a message].
List of available manpages
Index
msgrcv() -- General Function (libc) Receive a message #include <sys/types.h> #include <sys/ipc.h> #include <sys/msg.h> msgrcv(id, buffer, size, type, flag) int id, size, flag; long *buffer; long type; The function msgrcv() reads a message from the queue associated with identifier id, and writes it into the user-defined chunk of memory to which buffer points. The memory to which buffer points has a layout similar to a structure with the following members (if we pretend mtext[] is legal C): struct msgbuf { long mtype; /* message type */ char mtext[]; /* message text */ }; mtype gives the message's type, as specified by the sending process. mtext gives the text of the message. size gives the size of the message's text, in bytes. msgrcv() silently truncates the received message to size if it more than size bytes long and (flag & MSG_NOERROR) is true. type gives the type of message being requested. msgrcv obeys the following rules when it reads the message queue: -> If type equals 0L, it reads the first message in the queue. -> If type is greater than 0L, it reads the first message of type. -> If type is less than 0L, it reads the first message whose type is less than or equal to the absolute value of type. If the message queue contains no message of the desired type, the behavior of msgrcv() is determined by the value of flag. If flag contains the value IPC_NOWAIT (i.e., flag & IPC_NOWAIT is true) then msgrcv() sets errno to ENOMSG and returns -1. If, however, flag does not contain IPC_NOWAIT, then msgrcv() suspends execution until one of the following occurs: 1. A message of the desired type appears on the queue. 2. id is removed from the system. msgrcv() sets errno to EIDRM and returns -1. 3. The calling process receives a signal. msgrcv() sets errno to EINTR and returns -1. The calling process then resumes execution in the manner by signal received. For information on what given signals mean, see the Lexicon entry for signal(). msgrcv() also fails and returns no message if any of the following is true: -> id is not a valid message-queue identifier. msgrcv sets errno to EINVAL. -> The calling process lacks operation permission (EACCES). -> size is less than zero (EINVAL). -> The message's size is greater than size bytes long and (flag & MSG_NOERROR) is false (E2BIG). -> buffer points to an illegal address (EFAULT). When msgrcv() has successfully received its message, it modifies the data structure associated with id in the following ways: -> It decrements field msg_qnum by one. -> It sets msg_lrpid to the identifier of the process that called msgrcv(). -> It sets msg_rtime to the current time. When it completes successfully, msgrcv() returns the number of bytes written into the field mtext of the structure pointed to by buffer. Example For an example of this function, see the Lexicon entry for msgget(). Files /usr/include/sys/ipc.h /usr/include/sys/msg.h See Also libc, msgctl(), msgget(), msgsnd()