MSGSND(2)

MSGSND(2) | System Calls Manual | MSGSND(2)

# NAME

msgsnd — send a message to a message queue

# LIBRARY

Standard C Library (libc, -lc)

# SYNOPSIS

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

# DESCRIPTION

The msgsnd() function sends a message from the message queue specified in msqid. The msgp argument is a pointer to a user-defined structure containing the message. This structure must contain a first field of type long that will indicate the user-defined type of the message. The remaining fields will contain the contents of the message. The following is an example of what this user-defined structure might look like:

    struct mymsg {
        long mtype;    /* message type */
        char mtext[1]; /* body of message */
    };

The mtype field is an integer greater than 0 that can be used for selecting messages (see msgrcv(2)). The mtext field is an array of bytes of length msgsz, with size up to the system limit `MSGMAX`.
If the number of bytes already on the message queue plus msgsz is greater than the maximum number of bytes in the message queue (msg_qbytes, see msgctl(2)), or if the number of messages on all queues system-wide is already equal to the system limit, msgflg determines the action of msgsnd(). If msgflg has `IPC_NOWAIT` mask set in it, the call will return immediately. If msgflg does not have `IPC_NOWAIT` set in it, the call will block until:

- The condition which caused the call to block no longer exists. The message was sent.
- The message queue is removed, in which case -1 will be returned and errno set to `EINVAL`.
- The caller catches a signal. The call returns with errno set to `EINTR`.

After a successful call, the data structure associated with the message queue is updated in the following way:

- msg_qnum is incremented by 1.
- msg_lspid is set to the pid of the calling process.
- msg_stime is set to the current time.

# RETURN VALUES

Upon successful completion, 0 is returned. Otherwise, -1 is returned and errno is set to indicate the error.

# ERRORS

msgsnd() will fail if:

[`EACCES`]
  The calling process does not have write access to the message queue.
[`EAGAIN`]
  There was no space for this message either on the queue or in the whole system, and `IPC_NOWAIT` was set in msgflg.
[`EFAULT`]
  msgp points to an invalid address.
[`EINTR`]
  The system call was interrupted by the delivery of a signal.
[`EINVAL`]
  The msqid argument is not a valid message queue identifier, or the value of mtype is less than 1.
  The message queue was removed while msgsnd() was waiting for a resource to become available in order to deliver the message.
  The msgsz argument is greater than msg_qbytes or `SSIZE_MAX`.

# SEE ALSO

msgctl(2), msgget(2), msgrcv(2)

# STANDARDS

The msgsnd system call conforms to X/Open System Interfaces and Headers Issue 5 (“XSH5”) and IEEE Std 1003.1-2001 (“POSIX.1”).

# HISTORY

Message queues appeared in the first release of AT&T System V UNIX.

July 24, 2013 | NetBSD 8.0