Manual Pages for UNIX Operating System command usage for man msgrcv

System Calls                                            msgrcv(2)



NAME
     msgrcv - message receive operation

SYNOPSIS
     #include 

     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.




SunOS 5.11          Last change: 19 May 1999                    1






System Calls                                            msgrcv(2)



         o    If msgtyp is less than 0, the first message of  the
              lowest type that is less than or equal to the abso-
              lute 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
              process 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
              calling 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:





SunOS 5.11          Last change: 19 May 1999                    2






System Calls                                            msgrcv(2)



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


     EACCES    Operation permission is denied to the calling pro-
               cess.  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
               identifier.


     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 *.

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



     ____________________________________________________________
    |       ATTRIBUTE TYPE        |       ATTRIBUTE VALUE       |
    |_____________________________|_____________________________|
    | Interface Stability         | Committed                   |
    |_____________________________|_____________________________|
    | Standard                    | See standards(5).           |
    |_____________________________|_____________________________|


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




SunOS 5.11          Last change: 19 May 1999                    3