msgsnd()

NAME

msgsnd() - send message to message queue

SYNOPSIS

#include <sys/msg.h>


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

DESCRIPTION

The msgsnd(2) function sends a message to the queue associated with the identifier msqid. The message is held in the data structure pointed to by msgp; the size of the message in bytes is indicated by msgsz, and can be any value from 0 to the system limit. The msgflg argument specifies what is to be done if the queue already holds the maximum number of bytes or if the total number of messages on all queues on the system meets the system-imposed limit. The important instruction for msgflg is IPC_NOWAIT.

When the msgsnd(2) function succeeds, the data structure associated with msqid is modified:

• msg_qnum is increased by 1
• msg_lspid is set to the process ID of the calling process
• msg_stime is set to the current time.

The msgp structure is defined by the user, but the first member must be a non-zero positive long int which holds a value used for selecting messages. The second member must hold the data text. The length must be the same as msgsz.

If the message queue is full, or if the system-limit on queued messages is reached, the behavior of msgsnd(2) depends upon the value of msgflg:

• If (msgflg is non-zero, the message isn't sent and the calling process returns immediately.
• If (msgflg is zero, the calling process suspends execution until one of:
  • the condition is relieved (messages are removed from the message queue, the total number of queued messages shrinks), and the message is sent;
  • the identifier for this message queue is removed from the system, and msgsnd(2) returns -1 and sets errno to [EIDRM].
  • The calling process is interrupted by a signal that is to be caught, in which case the signal is handled and the message is not sent.

RETURN VALUE

The msgsnd(2) function returns 0 on success. On failure, it returns -1, doesn't send the message, and sets errno to indicate the error.

ERRORS

[EACCES]

The calling process does not have permission to perform that operation.

[EAGAIN]

The operation failed for some reason and The non-wait bit is set (that is, (msgflg is non-zero).

[EIDRM]

The message queue identifier msqid has been removed from the system.

[EINTR]

The function was interrupted by a signal.

[EINVAL]

The msqid is not a valid message queue identifier, or the message size value is negative or too large, or the value of the message type is less than 1.

EXAMPLES

A simple structure for data which sends four-character strings as messages might be:

struct a_msg {
   long int msg_type;   /* message type */
   char msg_text[5]; /* message text */
};

For this structure, the value of msgsz would be 5.

SEE ALSO

msgctl(2)

msgget(2)

msgrcv(2)