msgsnd Subroutine

Purpose

Sends a message.

Library

Standard C Library (libc.a)

Syntax

#include <sys/msg.h>

Description

The msgsnd subroutine sends a message to the queue specified by the MessageQueueID parameter. The current process must have write permission to perform this operation. The MessagePointer parameter points to an msgbuf structure containing the message. The sys/msg.h file defines the msgbuf structure. The structure contains the following fields:

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

The mtype field specifies a positive integer used by the receiving process for message selection. The mtext field can be any text of the length in bytes specified by the MessageSize parameter. The MessageSize parameter can range from 0 to the maximum limit imposed by the system.

The following example shows a typical user-defined msgbuf structure that includes sufficient space for the largest message:

struct my_msgbuf
mtyp_t     mtype;
char       mtext[MSGSIZ]; /* MSGSIZ is the size of the largest message */

The following system limits apply to the message queue:

• Maximum message size is 4 Megabytes.
• Maximum number of messages per queue is 524288.
• Maximum number of message queue IDs is 131072
• Maximum number of bytes in a queue is 4 Megabytes.

The MessageFlag parameter specifies the action to be taken if the message cannot be sent for one of the following reasons:

• The number of bytes already on the queue is equal to the number of bytes defined by themsg_qbytes structure.
• The total number of messages on the queue is equal to a system-imposed limit.

These actions are as follows:

• If the MessageFlag parameter is set to the IPC_NOWAIT value, the message is not sent, and the msgsnd subroutine returns a value of -1 and sets the errno global variable to the EAGAIN error code.
• If the MessageFlag parameter is set to 0, the calling process suspends execution until one of the following occurs:
  • The condition responsible for the suspension no longer exists, in which case the message is sent.
  • The MessageQueueID parameter is removed from the system. (For information on how to remove the MessageQueueID parameter, see the msgctl. When this occurs, the errno global variable is set equal to the EIDRM error code, and a value of -1 is returned.
  • The calling process receives a signal that is to be caught. In this case the message is not sent and the calling process resumes execution in the manner prescribed in the sigaction subroutine.

Parameters

Return Values

Upon successful completion, a value of 0 is returned and the following actions are taken with respect to the data structure associated with the MessageQueueID parameter:

• The msg_qnum field is incremented by 1.
• The msg_lspid field is set equal to the process ID of the calling process.
• The msg_stime field is set equal to the current time.

If the msgsnd subroutine is unsuccessful, a value of -1 is returned and the errno global variable is set to indicate the error.

Error Codes

The msgsnd subroutine is unsuccessful and no message is sent if one or more of the following conditions is true: