--- name: "msgrcv_secure" section: "2" platform: "linux" package: "libselinux-dev" version: "2002031409-4" release: "Debian 3.0 (Woody)" platforms: ["linux"] url: "https://new.carta.tech/msgop" --- # msgrcv\_secure(2) message operations Part of [msgop(2)](/msgop/2.md). ## NAME msgop - message operations ## SYNOPSIS ``` # include # include /* for *_secure variants */ # include # include ``` **int msgsnd ( int** *msqid***,** **struct msgbuf \****msgp***,** **int** *msgsz***,** **int** *msgflg* **)** **int msgrcv ( int** *msqid***,** **struct msgbuf \****msgp***,** **int** *msgsz***,** **long** *msgtyp***,** **int** *msgflg* **)** **int msgsnd\_secure ( int** *msqid***,** **struct msgbuf \****msgp***,** **int** *msgsz***,** **int** *msgflg***,** **security\_id\_t** *sid* **)** **int msgrcv\_secure ( int** *msqid***,** **struct msgbuf \****msgp***,** **int** *msgsz***,** **long** *msgtyp***,** **int** *msgflg***,** **security\_id\_t \*** *sid* **)** ## DESCRIPTION To send or receive a message, the calling process allocates a structure that looks like the following **struct msgbuf {**\ **long mtype;** /\* message type, must be \> 0 \*/\ **char mtext\[1\];** /\* message data \*/\ **};** but with an array **mtext** of size *msgsz*, a non-negative integer value. The structure member **mtype** must have a strictly positive integer value that can be used by the receiving process for message selection (see the section about **msgrcv**). To send a message, the calling process must have write access permission to the queue, permission to send a message at the given or default *sid ,* and the message *sid* must be allowable on the given queue. To read a message, the calling process must have read access permission on the queue. If msgrcv\_secure is used and a sid other than *SECSID\_WILD* or *SECSID\_NULL* is given, only messages with a matching *sid* will be received. Only messages for which the calling process has access to read and receive the message will be returned as appropriate. If an appropriate message is not available, the call will wait for a message to become available. The **msgsnd** system call enqueues a copy of the message pointed to by the *msgp* argument on the message queue whose identifier is specified by the value of the *msqid* argument. The argument *msgflg* specifies the system call behaviour if enqueuing the new message will require more than **msg\_qbytes** in the queue. Asserting **IPC\_NOWAIT** the message will not be sent and the system call fails returning with **errno** set to **EAGAIN**. Otherwise the process is suspended until the condition for the suspension no longer exists (in which case the message is sent and the system call succeeds), or the queue is removed (in which case the system call fails with **errno** set to **EIDRM**), or the process receives a signal that has to be caught (in which case the system call fails with **errno** set to **EINTR**). Upon successful completion the message queue data structure is updated as follows: - **msg\_lspid** is set to the process-ID of the calling process. - **msg\_qnum** is incremented by 1. - **msg\_stime** is set to the current time. The system call **msgrcv** reads a message from the message queue specified by *msqid* into the **msgbuf** pointed to by the *msgp* argument removing from the queue, on success, the read message. The argument *msgsz* specifies the maximum size in bytes for the member **mtext** of the structure pointed to by the *msgp* argument. If the message text has length greater than *msgsz*, then if the *msgflg* argument asserts **MSG\_NOERROR**, the message text will be truncated (and the truncated part will be lost), otherwise the message isn't removed from the queue and the system call fails returning with **errno** set to **E2BIG**. The argument *msgtyp* specifies the type of message requested as follows: - If *msgtyp* is **0**, then the message on the queue's front is read. - If *msgtyp* is greater than **0**, then the first message on the queue of type *msgtyp* is read if **MSG\_EXCEPT** isn't asserted by the *msgflg* argument, otherwise the first message on the queue of type not equal to *msgtyp* will be read. - If *msgtyp* is less than **0**, then the first message on the queue with the lowest type less than or equal to the absolute value of *msgtyp* will be read. The *msgflg* argument asserts none, one or more (or-ing them) among the following flags: - **IPC\_NOWAIT** For immediate return if no message of the requested type is on the queue. The system call fails with errno set to **ENOMSG**. - **MSG\_EXCEPT** Used with *msgtyp* greater than **0** to read the first message on the queue with message type that differs from *msgtyp*. - **MSG\_NOERROR** To truncate the message text if longer than *msgsz* bytes. If no message of the requested type is available and **IPC\_NOWAIT** isn't asserted in *msgflg*, the calling process is blocked until one of the following conditions occurs: - A message of the desired type is placed on the queue. - The message queue is removed from the system. In such a case the system call fails with **errno** set to **EIDRM**. - The calling process receives a signal that has to be caught. In such a case the system call fails with **errno** set to **EINTR**. Upon successful completion the message queue data structure is updated as follows: - **msg\_lrpid** is set to the process-ID of the calling process. - **msg\_qnum** is decremented by 1. - **msg\_rtime** is set to the current time. ## RETURN VALUE On a failure both functions return **-1** with **errno** indicating the error, otherwise **msgsnd** returns **0** and **msgrcv** returns the number of bytes actually copied into the **mtext** array. **msgrcv\_secure returns the** *sid* of the message returned in the *sid* parameter. ## ERRORS When **msgsnd** fails, at return **errno** will be set to one among the following values: - **EAGAIN** The message can't be sent due to the **msg\_qbytes** limit for the queue and **IPC\_NOWAIT** was asserted in *mgsflg*. - **EACCES** The calling process has no write access permissions on the message queue. - **EFAULT** The address pointed to by *msgp* isn't accessible. - **EIDRM** The message queue was removed. - **EINTR** Sleeping on a full message queue condition, the process received a signal that had to be caught. - **EINVAL** Invalid *msqid* value, or nonpositive *mtype* value, or invalid *msgsz* value (less than 0 or greater than the system value **MSGMAX**). - **ENOMEM** The system has not enough memory to make a copy of the supplied **msgbuf**. When **msgrcv** fails, at return **errno** will be set to one among the following values: - **E2BIG** The message text length is greater than *msgsz* and **MSG\_NOERROR** isn't asserted in *msgflg*. - **EACCES** The calling process has no read access permissions on the message queue. - **EFAULT** The address pointed to by *msgp* isn't accessible. - **EIDRM** While the process was sleeping to receive a message, the message queue was removed. - **EINTR** While the process was sleeping to receive a message, the process received a signal that had to be caught. - **EINVAL** Illegal *msgqid* value, or *msgsz* less than **0**. - **ENOMSG** **IPC\_NOWAIT** was asserted in *msgflg* and no message of the requested type existed on the message queue. ## NOTES The followings are system limits affecting a **msgsnd** system call: - **MSGMAX** Maximum size for a message text: the implementation set this value to 4080 bytes. - **MSGMNB** Default maximum size in bytes of a message queue: policy dependent. The super-user can increase the size of a message queue beyond **MSGMNB** by a **msgctl** system call. The implementation has no intrinsic limits for the system wide maximum number of message headers (**MSGTQL**) and for the system wide maximum size in bytes of the message pool (**MSGPOOL**). ## CONFORMING TO SVr4, SVID. ## SEE ALSO [**ipc**(5)](/ipc/5.md), [**msgctl**(2)](/msgctl/2.md), [**msgget**(2)](/msgget/2.md), [**msgsid**(2)](/msgsid/2.md), [**msgget\_secure**(2)](/msgget_secure/2.md), [**msgrcv**(2)](/msgrcv/2.md), [**msgrcv\_secure**(2)](/msgrcv_secure/2.md), [**msgsnd**(2)](/msgsnd/2.md), [**msgsnd\_secure**(2)](/msgsnd_secure/2.md).