NAME

msgsnd − Sends a message to a message queue

SYNOPSIS

#include <sys/types.h>
#include <sys/ipc.h>
#include <sys/msg.h> int msgsnd(
int msqid,
const void ∗msgp,
size_t msgsz,
int msgflg);

PARAMETERS

msqidSpecifies the ID of the message queue on which to place the message.  The ID is typically returned by a previous msgget() function. 

msgpSpecifies a pointer to the msgbuf structure that contains the message.  See NOTES. 

msgszSpecifies the size of the data array in the msgbuf structure. 

msgflgSpecifies the action to be taken by the kernel if it runs out of internal buffer space. 

DESCRIPTION

The msgsnd() function sends a message to the queue associated with the msqid parameter. 

The msgp parameter points to a user-defined msgbuf structure.  The structure identifies the message type and contains a data array with the message text. 

The size of the data array is specified by the msgsz parameter.  The msgsz value can be from zero to a system-defined maximum. 

The msgflg parameter specifies the action that the kernel should take if either or both of the following are true:

       •The current number of bytes in the message queue is equal to msg_qbytes (in the msqid_ds structure). 

       •The total number of messages on all message queues is equal to the system-defined limit. 

Either of two kernel actions can be specified, as follows:

       •If IPC_NOWAIT is set, the kernel does not send the message and returns to the calling process immediately. 

       •If IPC_NOWAIT is not set, the kernel suspends the calling process.  The process remains suspended until one of the following occurs:

       —
The blocking condition is removed.  In this case, the kernel sends the message.

       —
The specified message queue ID is removed from the system.  In this case, the kernel sets errno to [EIDRM] and returns -1 to the calling process. 

       —
The process catches a signal.  In this case, the message is not sent and the process resumes execution as directed by the signal() function. 

If the msgsnd() function completes successfully, the kernel updates the msqid_ds structure associated with the msgid parameter.  Specifically, it:

       •Increments msg_qnum by 1. 

       •Increments msg_cbytes by the message text size. 

       •Sets msg_lspid equal to the process ID of the calling process. 

       •Sets msg_stime equal to the current time. 

NOTES

The user-specified msgbuf structure is defined as follows: struct msgbuf {
mtyp_t mtype;
char mtext[]; }

The mytpe field is a user-chosen positive integer.  A receiving process can use the message type to select only those messages it wants to receive from the queue.  See the msgrcv() function. 

The mtext field is any text of length msgsz. 

When the kernel sends a message, it allocates space for the message and copies the data from user space.  The kernel then allocates a msg (message header) structure, sets its fields, and inserts the structure at the tail of the message queue associated with the message queue ID.  The msg structure is defined as follows: struct msg {
        struct msg     ∗msg_next;
        long            msg_type;
        long            msg_ts;
        caddr_t         msg_addr;
};

The msg_next field is a pointer to the next message in the queue.  The msg_type field is the message type supplied in the user-specified msgbuf structure.  The msg_ts field is the size of the message text.  The msg_addr field is the address of the message text. 

RETURN VALUES

Upon successful completion, a value of 0 (zero) is returned.  Otherwise, a value of -1 is returned and errno is set to indicate the error. 

ERRORS

If the msgsnd() function fails, errno may be set to one of the following values:

[EINVAL]The msqid parameter is not a valid message queue ID, mtype is less than 1, or msgsz is less than 0 (zero) or greater than the system-defined limit. 

[EACCES]The calling process does not have permission for the operation. 

[EAGAIN]If the maximum number of message headers has been allocated or if the bytes for the message exceed the maximum number of bytes on the queue, the message cannot be sent and the IPC_NOWAIT flag is set. 

[EINTR]The operation was interrupted by a signal. 

[EIDRM]The msqid parameter has been removed from the system. 

[ENOSYS]The requested operation is not supported by this implementation. 

RELATED INFORMATION

Functions: msgctl(2), msgget(2), msgrcv(2), sigaction(2)

Data Structures: msqid_ds(4)