unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (SunOS-5.10)
Page:
Section:
Apropos / Subsearch:
optional field

msgrcv(2)                        System Calls                        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  associated  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 mes-
       sage, and then a data portion that will hold the data bytes of the mes-
       sage.  The structure below is an example of what this user-defined buf-
       fer 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&&amp;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&&amp;IPC_NOWAIT)  is  non-zero,  the  calling  process will
            return immediately with a return value of  -1  and  errno  set  to
            ENOMSG.

         o  If (msgflg&&amp;IPC_NOWAIT) is 0, the calling process will suspend exe-
            cution 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 execution in the manner prescribed in  sigac-
                 tion(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 calling process.

         o  msg_rtime is set equal to the current time.


RETURN VALUES
       Upon successful completion, msgrcv() returns a value equal to the  num-
       ber  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&&amp;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 identi-
                       fier.



       ENOMSG          The  queue  does  not  contain a message of the desired
                       type and (msgflg&&amp;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
       *.

ATTRIBUTES
       See attributes(5) for descriptions of the following attributes:


       tab()     allbox;     cw(2.750000i)|    cw(2.750000i)    lw(2.750000i)|
       lw(2.750000i).  ATTRIBUTE TYPEATTRIBUTE VALUE Interface  StabilityStan-
       dard


SEE ALSO
       intro(2), msgctl(2), msgget(2), msgsnd(2), sigaction(2), attributes(5),
       standards(5)



SunOS 5.10                        19 May 1999                        msgrcv(2)