msgsnd() — Message send operations

Standards

Standards / Extensions C or C++ Dependencies
XPG4
XPG4.2
Single UNIX Specification, Version 3
 both  

Format

#define _XOPEN_SOURCE
#include <sys/msg.h>

int msgsnd(int msgid, const void *msgp, size_t msgsz, int msgflg);

General description

The msgsnd() function is used to send a message to the queue associated with the message queue identifier specified by msgid.

The argument msgp points to a user-defined buffer that must contain first a field of type long int that will specify the type of the message, and then a data portion that will hold the data bytes of the message. The structure below is an example of what this user-defined buffer should look like: 
struct message 
{
    long int   mtype;    Message type
    int        mtext[n];  Message text
}

The structure member, mtype, must be a nonzero positive value that can be used by the receiving process for message selection. The structure member, mtext, is any text of length, msgsz, bytes.

The argument msgsz specifies the size in bytes of mtext. When only mtype is to be sent with no mtext, msgsz is set to zero. The argument can range from zero to a system-imposed maximum or the maximum number of bytes allowed in the message queue.

The argument msgflg specifies the action to be taken if one or more of the following are true:
  • Placing the message on the message queue would cause the current number of bytes on the message queue (msg_cbytes) to exceed the maximum number of bytes allowed on this queue, as specified in msg_qbytes.
  • The total number of messages on the queue is equal to the system-imposed limit.
These actions are as follows:
  • If the IPC_NOWAIT flag is on in msgflg, the message will not be sent and the calling process will return immediately. msgsnd() will return -1 and set errno to EAGAIN.
  • If the IPC_NOWAIT flag is off in msgflg, the calling process will suspend execution until one of the following occurs:
    1. The condition responsible for the suspension no longer exists, in which case the message is sent.
    2. The message queue identifier, msgid, is removed from the system; when this occurs, errno is set to EIDRM and a value of -1 is returned.
    3. The calling process receives a signal that is to be caught; in this case a message is not sent and the calling process resumes execution. A value of -1 is returned and error is set to EINTR.
If successful, the following actions are taken with respect to the data structure, msqid_ds, associated with msgid:
  1. msg_qnum is incremented by 1.
  2. msg_lspid is set equal to the process ID of the calling process.
  3. msg_stime is set equal to the current time.

Returned value

If successful, msgsnd() returns 0.

If unsuccessful, no message is sent, msgsnd() returns -1, and sets errno to one of the following values:
Error Code
Description
EACCES
The calling process does not have write permission to the message queue associated with the message queue identifier msgid or the message queue was built with IPC_SNDTYPEPID and the MSG_TYPE was other than the invoker's process ID (JRTypeNotPID).
EAGAIN
The message cannot be sent for one of the reasons cited above and IPC_NOWAIT was specified.
EIDRM
The message queue identifier, msgid, has been removed from the system while the caller of msgsnd() was waiting.
EINTR
The function msgsnd() was interrupted by a signal before a message could be sent.
EINVAL
The value of argument msgid is not a valid message queue identifier, or the value of mtype is less than 1; or the value of msgsz is less than zero or greater than the system-imposed limit.
ENOMEM
Not enough system storage exists to complete the msgsnd() function.

Related information