NAME
msg_send - transmits a message

SYNOPSIS
#include <sys/message.h>

msg_return_t msg_send(header, option, timeout)
msg_header_t *header;
msg_option_t option;
msg_timeout_t timeout;

ARGUMENTS
header The address of the message to be sent. A message
consists of a fixed sized header followed by a
variable number of data descriptors and data items.
See <sys/message.h> for a definition of the message
structure.

timeout In the event that the destination port is full and
the SEND_TIMEOUT option has been specified, this
value specifies the maximum wait time (in
milliseconds).

option The failure conditions under which msg_send should
terminate; the value of this parameter is an or’ed
combination of the following two options. Unless
one of the two following values for the option
parameter is explicitly specified, msg_send does
not return until the message is successfully queued
for the intended receiver.

SEND_TIMEOUT Specifies that the msg_send request should terminate
after the timeout period has elapsed, even if the
kernel has been unable to queue the message.

SEND_NOTIFY Allows the sender to give exactly one message to the
operating system without being suspended should the
destination port be full. When that message can in
fact be posted to the receiving port’s queue, the
sending task receives a message which notifies it
that another message can be sent. A second attempt
to send a message with the notify option before the
first notification arrives results in an error. If
SEND_TIMEOUT is also specified, msg_send will wait
until the specified timeout has elapsed before
invoking the SEND_NOTIFY option.

SEND_INTERRUPT Specifies that msg_send should return if a software
interrupt occurs in this thread.

MSG_OPTION_NONE
A constant defined as zero which may be used to
specify that neither of the previous options are
wanted.

DESCRIPTION
msg_send transmits a message from the current task to the remote
port specified in the message header field (msg_remote_port). The
message consists of its header, followed by a variable number of
data descriptors and data items. (See the introduction to this
section for details on message formatting.)

If the msg_local_port field is not set to PORT_NULL, send rights to
that port will be passed to the receiver of this message. The
receiver task may use that port to send a reply to this message.

If the SEND_NOTIFY option is used and this call returns a
SEND_WILL_NOTIFY code, then the user can expect to receive a notify
message from the kernel. This message will either be a
NOTIFY_MSG_ACCEPTED or a NOTIFY_PORT_DELETED message depending on
what happened to the queued message. The first and only data item
in these messages is the port to which the original message was
sent. The ids and formats for these messages are defined in
<sys/notify.h>.

DIAGNOSTICS
SEND_SUCCESS The message has been queued for the destination
port.

SEND_INVALID_MEMORY The message header or body was not readable by
the calling task, or the message body specified
out-of-line data which was not readable.

SEND_INVALID_PORT The message refers to a name for which the
current task does not have access, or to which
access was explicitly removed from the current
task (see port_deallocate) while waiting for
the message to be posted, or a msg_type_name
field in the message specifies rights that the
name doesn’t denote in the task (eg, specifying
MSG_TYPE_SEND and supplying a port set’s name).

SEND_TIMED_OUT The message was not sent since the destination
port was still full after timeout milliseconds.

SEND_WILL_NOTIFY The destination port was full but the
SEND_NOTIFY option was specified. A
notification message will be sent when the
message can be posted.

SEND_NOTIFY_IN_PROGRESS
The SEND_NOTIFY option was specified but a
notification request is already outstanding for
this thread and given destination port.

FILES
<sys/message.h>
<sys/notify.h>
<mach_init.h>