msgrcv(PCI)                    6 January 1993                    msgrcv(PCI)


 Name

    msgrcv - message receiving

 Syntax


    #include <pcilib.h>


    #include <memmdl.h>


    #include <ipc.h>

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


 Description

    msgrcv reads a message from the queue associated with the message queue
    identifier specified by msqid and places it in the structure pointed to
    by msgp. This structure is composed of the following members:

       long        mtype;                /* message type */
       char        mtext[];              /* message text */


    mtype is the type of the received message as specified by the sending
    process.  mtext is the text of the message.  msgsz specifies the size in
    bytes of mtext, which can be no greater than 1008.  The received message
    is truncated to msgsz bytes if it is larger than msgsz and (msgflg &
    MSGNOERROR) is "true."  The truncated part of the message is lost, and
    no indication of the truncation is given to the calling process.

    msgtyp specifies the type of message requested, as follows:

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

    +  If msgtyp is greater than 0, the first message of type msgtyp is
       received.

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

    msgflg specifies the action to be taken if a message of the desired type
    is not on the queue, as follows:

    +  If (msgflg & IPCNOWAIT) is "true," the calling process immediately
       returns a value of -1 and errno is set to ENOMSG.

    +  If (msgflg & IPCNOWAIT) is "false," the calling function returns a
       value of -1 and errno is set to EIDRM.

    msgrcv fails and no message is received 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 (msgflg & MSGNOERROR) is
              "false."

    [ENOMSG]  The queue does not contain a message of the desired type and
              (msgtyp & IPCNOWAIT ) is "true."

    [EFAULT]  msgp points to an illegal address.

    On successful completion, the following actions are taken with respect to
    the data structure associated with msqid; see Intro(PCI).

    +  msgqnum is decremented by 1.

    +  msglrpid is set to the process ID of the calling process.

    +  msgrtime is set to the current time.


 Return value

    On successful completion, msgrcv returns the number of bytes actually
    placed into mtext.

    If msgrcv returns due to removal of msqid from the system, a value of -1
    returns and errno is set to EIDRM.

    Otherwise, a value of -1 returns and errno is set to indicate the error.

 See also

    dflthost(PCI), Intro(PCI), msgctl(PCI), msgget(PCI), msgsnd(PCI),
    sleeph(PCI)

 Difference from System V

    msgrcv calls that would cause a process to suspend in System V-compatible
    operating system cause an error to be returned in DOS.  DOS tasks may not
    be suspended using msgrcv functions; sleeph may be used instead.