msgrcv(3) — AIX PS/2 1.2.1



MSGRCV(3,L)                 AIX Technical Reference                 MSGRCV(3,L)



-------------------------------------------------------------------------------
msgrcv



PURPOSE

Reads a message from a queue.

LIBRARY

Standard C Library (libc.a)

SYNTAX

#include <sys/types.h>
#include <sys/ipc.h>
#include <sys/msg.h>

int msgrcv (msqid, msgp, msgsz, msgtyp, msgflg)
int msqid;
struct msgbuf *msgp;
int msgsz;
long msgtyp;
int msgflg;

DESCRIPTION

The msgrcv system call reads a message from the queue specified by the msqid
parameter and stores it into the structure pointed to by the msgp parameter.
The current process must have read permission in order to perform this
operation.  The msgbuf structure is defined in the sys/msg.h header file, and
it contains the following members:

      long  mtype;     /* Message type */
      char  mtext[1];  /* Beginning of message text */

The mtype field contains the type of the received message as specified by the
sending process.  mtext is the text of the message.

The msgsz parameter specifies the size of mtext in bytes.  The received message
is truncated to the size specified by the msgsz parameter if it is longer than
the size specified by the msgsz parameter and if MSG_NOERROR is set in msgflg.
The truncated part of the message is lost and no indication of the truncation
is given to the calling process.  If the message is longer than msgsz bytes and
MSG_NOERROR is not set, then the msgrcv system call fails and sets errno to
E2BIG.

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

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



Processed November 7, 1990        MSGRCV(3,L)                                 1



MSGRCV(3,L)                 AIX Technical Reference                 MSGRCV(3,L)




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

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

The msgflg parameter is either 0, or is constructed by logically ORing one or
more of the following values:

MSG_NOERROR  Truncates the message if it is longer than msgsz bytes.

IPC_NOWAIT   Specifies the action to take if a message of the desired type is
             not on the queue:

               o If IPC_NOWAIT is set, then the calling process returns a value
                 of -1 and sets errno to ENOMSG.

               o If IPC_NOWAIT is not set, then the calling process suspends
                 execution until one of the following occurs:

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

                   - The message queue identifier specified by the msqid
                     parameter is removed from the system.  When this occurs,
                     errno is set to EIDRM, and a value of -1 is returned.

                   - The calling process receives a signal that is to be
                     caught.  In this case, a message is not received and the
                     calling process resumes in the manner described in
                     "sigaction, sigvec, signal."

Warning:  If the Transparent Computing Facility is installed, a message queue
exists only on the cluster site on which the queue was created.  There is no
provision for accessing a message queue on a remote cluster site.
Consequently, processes that use message queues cannot be migrated to other
sites.

RETURN VALUE

Upon successful completion, msgrcv returns a value equal to the number of bytes
actually stored into mtext and the following actions are taken with respect to
the data structure associated with the msqid parameter:

  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.

If the msgrcv system call fails, a value of -1 is returned and errno is set to
indicate the error.




Processed November 7, 1990        MSGRCV(3,L)                                 2



MSGRCV(3,L)                 AIX Technical Reference                 MSGRCV(3,L)



ERROR CONDITIONS

The msgrcv system call fails if one or more of the following are true:

EINVAL    msqid is not a valid message queue identifier.

EACCES    Operation permission is denied to the calling process.

EINVAL    msgsz is less than 0.

E2BIG     mtext is greater than msgsz and MSG_NOERROR is not set.

ENOMSG    The queue does not contain a message of the desired type and
          IPC_NOWAIT is set.

EFAULT    The msgp parameter points to a location outside of the process's
          allocated address space.

EINTR     msgrcv received a signal.

EIDRM     The message queue identifier specified by msqid has been removed from
          the system.

RELATED INFORMATION

In this book:  "msgctl,"  "msgget,"  "msgsnd," "msgxrcv," and  "sigaction,
sigvec, signal."




























Processed November 7, 1990        MSGRCV(3,L)                                 3

Museum

Related Articles