August 25, 1999 MSGRCV 2

### NAME

msgrcv - receive a message from a message queue

### LIBRARY

Standard C Library (libc, -lc)

### SYNOPSIS

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

### DESCRIPTION

The msgrcv(``) function receives a message from the message queue specified in ```msqid`, and places it into the user-defined structure pointed to by ```msgp`. This structure must contain a first field of type long that will indicate the user-defined type of the message. The remaining fields will contain the contents of the message. The following is an example of what this user-defined structure might look like: `

    struct mymsg {
        long mtype;    /* message type */
        char mtext[1]; /* body of message */
    };

`

mtype is an integer greater than 0 that can be used to select messages. mtext is an array of bytes, with size up to the system limit ```MSGMAX`.

The value of ```msgtyp` has one of the following meanings:

- ```msgtyp` is greater than 0. The first message of type ```msgtyp` will be received.

- ```msgtyp` is equal to 0. The first message on the queue will be received.

- ```msgtyp` is less than 0. The first message of the lowest message type that is less than or equal to the absolute value of ```msgtyp` will be received.

```msgsz` specifies the maximum length of the requested message. If the received message has a length greater than ```msgsz` it will be silently truncated if the ```MSG_NOERROR` flag is set in ```msgflg`, otherwise an error will be returned.

If no matching message is present on the message queue specified by ```msqid`, the behaviour of msgrcv(``) depends on whether the ```IPC_NOWAIT` flag is set in ```msgflg` or not. If ```IPC_NOWAIT` is set, then msgrcv(``) will immediately return a value of -1 and set errno to ```EAGAIN`. If ```IPC_NOWAIT` is not set, the calling process will block until:

- A message of the requested type becomes available on the message queue.

- The message queue is removed, in which case -1 will be returned and errno set to ```EIDRM`.

- A signal is received and caught. -1 is returned and errno is set to ```EINTR`.

If a message is successfully received, the data structure associated with ```msqid` is updated as follows:

- msg_lrpid is set to the pid of the caller.

- msg_lrtime is set to the current time.

- msg_qnum is decremented by 1.

### RETURN VALUES

Upon successful completion, msgrcv(``) returns the number of bytes received into the mtext field of the structure pointed to by ```msgp`. Otherwise, -1 is returned, and errno set to indicate the error.

### ERRORS

msgrcv(``) will fail if:

[```EINVAL`]
  ```msqid` is not a valid message queue identifier

  The message queue was removed while msgrcv(``) was waiting for a message of the requested type to become available in it.

  ```msgsz` is less than 0.

[```E2BIG`]
  A matching message was received, but its size was greater than ```msgsz` and the ```MSG_NOERROR` flag was not set in ```msgflg`.

[```EACCES`]
  The calling process does not have read access to the message queue.

[```EFAULT`]
  ```msgp` points to an invalid address.

[```EINTR`]
  The system call was interrupted by the delivery of a signal.

[```EAGAIN`]
  There is no message of the requested type available on the message queue, and ```IPC_NOWAIT` is set in ```msgflg`.

[```EIDRM`]
  The message queue identifier ```msqid` is removed from the system.

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

### SEE ALSO

msgctl(2), msgget(2), msgsnd(2)

### STANDARDS

The msgrcv system call conforms to X/Open System Interfaces and Headers Issue 5 (``XSH5'') .

### HISTORY

Message queues appeared in the first release of `AT&T` System V `UNIX`.