msgsnd(2)msgsnd(2)NAMEmsgsnd - Send a message to a message queue
SYNOPSIS
#include <sys/msg.h>
int msgsnd(
int msqid,
const void *msgp,
size_t msgsz,
int msgflg );
Application developers may want to specify #include statements for
<sys/types.h> and <sys/ipc.h> before the one for <sys/msg.h> if pro‐
grams are being developed for multiple platforms. The additional
#include statements are not required on Tru64 UNIX systems or by ISO or
XSH standards, but may be required on other vendors' systems that con‐
form to these standards.
STANDARDS
Interfaces documented on this reference page conform to industry stan‐
dards as follows:
msgsnd(): XSH4.0, XSH4.2, XSH5.0
Refer to the standards(5) reference page for more information about
industry standards and associated tags.
PARAMETERS
Specifies the ID of the message queue on which to place the message.
The ID is typically returned by a previous msgget() function. Speci‐
fies a pointer to the msgbuf structure that contains the message.
Specifies the size of the data array in the msgbuf structure. Speci‐
fies 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. When the kernel sends a message, it allocates space
for the message and copies the data from user space. The kernel then
allocates a structure of type msg (message header), sets its fields,
and inserts the structure at the end 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 msg‐
buf structure. The msg_ts field is the size of the message text. The
msg_addr field is the address of the message text.
You pass the message that the kernel adds to the message queue in the
msgp parameter. This parameter points to a msgbuf structure that you
define as follows:
struct msgbuf {
long int mtype;
char mtext[]; };
The mtype field is a positive integer that indicates the type of the
message. A receiving process can use this message type to select only
those messages it wants to receive from the queue. For more information
about the values you can specify in this field, see msgrcv(2).
The mtext field contains the text of the message. You specify the size
in bytes of the message in the msgsz parameter. You can specify a value
between 0 (zero) and, by default, 8192 bytes. Note that the maximum
number of bytes allowed in a message string is configured at system
configuration time using the msgmax configuration file keyword, so the
limit might be different for your system.
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 limit defined by the msgtql configuration file keyword.
By default the limit is 40, but it might have been changed for your
system at system configuration time.
One 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 follow‐
ing 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 calling process catches a signal. In this
case, the message is not sent and the process resumes execution as
directed by the signaction() 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. [Tru64 UNIX] 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.
RETURN VALUES
Upon successful completion, the msgrcv() function returns a value of 0
(zero). Otherwise, the function returns a value of -1 and sets errno to
indicate the error.
ERRORS
The msgsnd() function sets errno to the specified values for the fol‐
lowing conditions: The calling process does not have permission for the
operation. The IPC_NOWAIT flag is set, and either the maximum number
of message headers has been allocated or the message queue is full.
[Tru64 UNIX] Indicates that the requested address is in some way
invalid, for example, out of bounds. The message queue identified by
the msqid parameter has been removed from the system. The operation
was interrupted by a signal. The msqid parameter is not a valid mes‐
sage queue ID, mtype is less than 1, or msgsz is less than 0 (zero) or
greater than the limit defined by the msgmax configuration file key‐
word. By default the limit is 8192 bytes, but it might have been
changed for your system at system configuration time.
SEE ALSO
Functions: msgctl(2), msgget(2), msgrcv(2), sigaction(2)
Data Structures: msqid_ds(4)
Standards: standards(5)msgsnd(2)