msgrcv(2)

NAME

     msgrcv - message receive operation

SYNOPSIS

     #include <sys/msg.h>

     ssize_t msgrcv(int msqid, void *msgp, size_t msgsz, long int
     msgtyp, int msgflg);

DESCRIPTION

     The msgrcv() function reads a message from the queue associ-
     ated  with  the  message queue identifier specified by msqid
     and places it in the user-defined buffer pointed to by msgp.

     The msgp argument points to a user-defined buffer that  must
     contain first a field of type long int that will specify the
     type of the message, and then a data portion that will  hold
     the  data  bytes  of  the message. The structure below is an
     example of what this user-defined buffer might look like:

     struct mymsg {
             long int    mtype;     /* message type */
             char        mtext[1];  /* message text */
     }

     The mtype member is the received message's type as specified
     by the sending process.

     The mtext member is the text of the message.

     The  msgsz argument specifies the size in  bytes  of  mtext.
     The  received  message  is truncated to msgsz bytes if it is
     larger than msgsz and (msgflg&MSG_NOERROR) is non-zero.  The
     truncated  part  of the message is lost and no indication of
     the truncation is given to the calling process.

     The msgtyp argument specifies the type of message  requested
     as follows:

        o  If msgtyp is 0, the first  message  on  the  queue  is
           received.

        o  If msgtyp is greater than 0, the first message of type
           msgtyp is received.

        o  If msgtyp is less than 0, the  first  message  of  the
           lowest type that is less than or equal to the absolute
           value of msgtyp is received.

     The msgflg argument specifies which of the following actions
     is  to  be  taken if a message of the desired type is not on
     the queue:
        o  If (msgflg&IPC_NOWAIT) is non-zero, the  calling  pro-
           cess will return immediately with a return value of -1
           and errno set to ENOMSG.

        o  If (msgflg&IPC_NOWAIT) is 0, the calling process  will
           suspend execution until one of the following occurs:

              o  A message of the desired type is placed  on  the
                 queue.

              o  The message queue identifier  msqid  is  removed
                 from  the  system  (see  msgctl(2));  when  this
                 occurs, errno is set equal to EIDRM  and  -1  is
                 returned.

              o  The calling process receives a signal that is to
                 be  caught;  in  this  case  a  message  is  not
                 received and the calling process resumes  execu-
                 tion in the manner prescribed in sigaction(2).

     Upon successful completion, the following actions are  taken
     with  respect  to  the  data structure associated with msqid
     (see intro(2)):

        o  msg_qnum is decremented by 1.

        o  msg_lrpid is set equal to the process ID of  the  cal-
           ling process.

        o  msg_rtime is set equal to the current time.

RETURN VALUES

     Upon successful completion, msgrcv() returns a  value  equal
     to  the  number  of  bytes  actually  placed into the buffer
     mtext. Otherwise, -1 is returned, no  message  is  received,
     and errno is set to indicate the error.

ERRORS

     The msgrcv() function will fail if:

     E2BIG The  value  of  mtext  is  greater  than   msgsz   and
           (msgflg&MSG_NOERROR) is 0.

     EACCES
           Operation permission is denied to the calling process.
           See intro(2).

     EIDRM The message queue identifier msqid is removed from the
           system.

     EINTR The msgrcv() function was interrupted by a signal.

     EINVAL
           The msqid argument is not a valid message queue  iden-
           tifier.

     ENOMSG
           The queue does not contain a message  of  the  desired
           type and (msgflg&IPC_NOWAIT) is non-zero.

     The msgrcv() function may fail if:

      EFAULT
           The msgp argument points to an illegal address.

USAGE

     The value passed as the msgp argument should be converted to
     type void *.

SEE ALSO

     intro(2), msgctl(2), msgget(2), msgsnd(2), sigaction(2)