*nix Documentation Project
·  Home
 +   man pages
·  Linux HOWTOs
·  FreeBSD Tips
·  *niX Forums

  man pages->Tru64 Unix man pages -> msgrcv (2)              



NAME    [Toc]    [Back]

       msgrcv - Receive a message from a message queue

SYNOPSIS    [Toc]    [Back]

       #include <sys/msg.h>

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

       Application developers may want to specify #include statements
 for <sys/types.h> and <sys/ipc.h> before the one for
       <sys/msg.h>  if  programs are being developed for multiple
       platforms.  The additional  #include  statements  are  not
       required on Tru64 UNIX systems or by ISO or XSH standards,
       but may be required on other vendors' systems that conform
       to these standards.

STANDARDS    [Toc]    [Back]

       Interfaces  documented  on  this reference page conform to
       industry standards as follows:

       msgrcv():  XSH4.0, XSH4.2, XSH5.0

       Refer to the standards(5) reference page for more information
 about industry standards and associated tags.

PARAMETERS    [Toc]    [Back]

       Specifies  the  ID  of  the  message  queue  from which to
       receive the message.  Specifies a pointer  to  the  msgbuf
       structure  that  is to receive the message.  See the NOTES
       section for more information.  Specifies the maximum  number
  of  bytes  allowed  for  the received data. The msgsz
       parameter is only used to specify the  size  of  the  msgbuf.mtext
  field. It cannot include the msgbuf.mtype field
       or else the msgbuf buffer is overwritten.   Specifies  the
       message type to read from the queue.  Specifies the action
       to be taken by the kernel if there are no msgtyp  messages
       on the queue.

DESCRIPTION    [Toc]    [Back]

       The  msgrcv()  function  receives a message from the queue
       associated with the msqid parameter. The function  returns
       the number of bytes in the received message.

       The  msgp parameter points to a user-defined msgbuf structure.
  This structure receives the message read  from  the

       The msgsz parameter specifies the maximum size allowed for
       the received data.  If the message is longer  than  msgsz,
       the  following  occurs,  depending upon the setting of the
       MSG_NOERROR flag: If MSG_NOERROR is not  set,  the  kernel
       returns an [E2BIG] error to the calling process and leaves
       the message on the queue.  If MSG_NOERROR is set, the kernel
  truncates the message to msgsz and discards the truncated
 portion without notifying the calling process.

       The msgtyp parameter specifies the message type  that  the
       process  expects  to  receive.   Possible values and their
       results are as follows: The process receives  the  message
       at  the head of the queue.  The process receives the first
       message of the requested positive-integer type.  The  process
  receives the first message of the lowest type on the
       queue. To qualify as the lowest type, the negative-integer
       type  must  be less than or equal to the absolute value of

       The msgflg parameter specifies the action that the  kernel
       should take if the queue does not contain a message of the
       requested type.  Either of two kernel actions can be specified,
  as  follows:  If  IPC_NOWAIT  is set, the function
       returns immediately with a return value of (ssize_t)-1 and
       sets  errno  to  [ENOMSG].   If IPC_NOWAIT is not set, the
       kernel suspends the calling process.

              The process remains suspended until one of the following
  occurs:  A  message  of  the requested type
              appears on the queue.  In  this  case,  the  kernel
              wakes  the  process  to  receive  the message.  The
              specified message queue ID is removed from the system.
   In  this  case,  the  kernel  sets  errno to
              [EIDRM] and returns (ssize_t)-1 to the calling process.
  The process catches a signal.  In this case,
              the process  does  not  receive  the  message  and,
              instead,  resumes  execution  as  directed  by  the
              sigaction() call.

NOTES    [Toc]    [Back]

       The parameter msgp points to a user-specified buffer  that
       must contain first a field of type long int that specifies
       the type of the message, and  then  a  data  portion  that
       holds the data bytes of the message.  For example:

       struct msgbuf {
          long int mtype;
          char mtext[]; }

       The mytpe field is set to the message type supplied by the

       The mtext field  is  set  to  the  message  text.   Unless
       MSG_NOERROR  is set, the message size will be less than or
       equal to the msgsz specified on the call to msgrcv().

RETURN VALUES    [Toc]    [Back]

       Upon successful completion, the msgrcv() function  returns
       a  value  equal  to the number of bytes actually stored in
       mtext. Also, the kernel  updates  the  msqid_ds  structure
       associated  with  the  message queue ID as follows: Decrements
 msg_qnum by 1.  Sets msg_lrpid equal to the  process
       ID  of  the  calling process.  Sets msg_rtime equal to the
       current time.  [Tru64 UNIX]  Decrements msg_cbytes by  the
       message text size.

       When  the  msgrcv()  function fails, it returns a value of
       (ssize_t)-1 and sets errno to indicate the error.

ERRORS    [Toc]    [Back]

       The msgrcv() function sets errno to the  specified  values
       for  the  following  conditions: The number of bytes to be
       received in mtext is greater than msgsz and the  MSG_NOERROR
  flag  is  not set.  The calling process does not have
       permission  for  the  operation.    Indicates   that   the
       requested address is in some way invalid, for example, out
       of bounds.  The message  queue  identified  by  the  msqid
       parameter has been removed from the system.  The operation
       was interrupted by a signal.  The msqid parameter is not a
       valid message queue ID.  The queue does not contain a message
 of the requested type and the IPC_NOWAIT flag is set.

SEE ALSO    [Toc]    [Back]

       Functions: msgctl(2), msgget(2), msgsnd(2), sigaction(2)

       Data Structures: msqid_ds(4)

       Standards: standards(5)

[ Back ]
 Similar pages
Name OS Title
mq_receive IRIX receive a message from a queue
mq_open Tru64 Establishes the connection between a message queue and a message queue descriptor (P1003.1b)
recvmsg Tru64 Receive a message from a socket using a message structure
mq_receive Tru64 Receives the oldest, highest-priority message from the message queue (P1003.1b)
mq_send Tru64 Places a message in the message queue (P1003.1b)
msgsnd Tru64 Send a message to a message queue
msgsnd OpenBSD send a message to a message queue
mq_send HP-UX send a message to a message queue
msgsnd FreeBSD send a message to a message queue
msgsnd NetBSD send a message to a message queue
Copyright © 2004-2005 DeniX Solutions SRL
newsletter delivery service