msgxrcv(3) — AIX PS/2 1.2.1



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



-------------------------------------------------------------------------------
msgxrcv



PURPOSE

Receives an extended message.

LIBRARY

Standard C Library (libc.a)

SYNTAX

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

int msgxrcv (msqid, msgp, msgsz, msgtyp, msgflg)
int msqid;
struct msgxbuf *msgp;
int msgsz, msgflg;
long msgtyp;

DESCRIPTION

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

     time_t          mtime; /* Time and date message was sent */
     suid_t          muid; /* Sender's effective user ID */
     suid_t          mgid; /* Sender's effective group ID */
     unsigned long   mnid; /* Sender's node ID */
     pid_t           mpid; /* Sender's process ID */
     long            mtype; /* Message type */
     char            mtext[1]; /* Beginning of message text */

The msgsz parameter specifies the size of mtext in bytes.  The receive message
is truncated to the size specified by the msgsz parameter if it is larger than
the msgsz parameter and MSG_NOERROR is true.  The truncated part of the message
is lost and no indication of the truncation is given to the calling process.

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 larger 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




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



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



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.

  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 prescribed 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, msgxrcv 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:



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



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




  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 msgxrcv system call fails, a value of -1 is returned and errno is set to
indicate the error.

ERROR CONDITIONS

The msgxrcv 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     msgxrcv received a signal.

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

RELATED INFORMATION

In this book:  "msgctl," "msgget," and "msgrcv."





















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

Museum

Related Articles