— Function: mach_msg_return_t mach_msg (mach_msg_header_t *msg, mach_msg_option_t option, mach_msg_size_t send_size, mach_msg_size_t rcv_size, mach_port_t rcv_name, mach_msg_timeout_t timeout, mach_port_t notify)

The mach_msg function is used to send and receive messages. Mach messages contain typed data, which can include port rights and references to large regions of memory.

msg is the address of a buffer in the caller's address space. Message buffers should be aligned on long-word boundaries. The message options option are bit values, combined with bitwise-or. One or both of MACH_SEND_MSG and MACH_RCV_MSG should be used. Other options act as modifiers. When sending a message, send_size specifies the size of the message buffer. Otherwise zero should be supplied. When receiving a message, rcv_size specifies the size of the message buffer. Otherwise zero should be supplied. When receiving a message, rcv_name specifies the port or port set. Otherwise MACH_PORT_NULL should be supplied. When using the MACH_SEND_TIMEOUT and MACH_RCV_TIMEOUT options, timeout specifies the time in milliseconds to wait before giving up. Otherwise MACH_MSG_TIMEOUT_NONE should be supplied. When using the MACH_SEND_NOTIFY, MACH_SEND_CANCEL, and MACH_RCV_NOTIFY options, notify specifies the port used for the notification. Otherwise MACH_PORT_NULL should be supplied.

If the option argument is MACH_SEND_MSG, it sends a message. The send_size argument specifies the size of the message to send. The msgh_remote_port field of the message header specifies the destination of the message.

If the option argument is MACH_RCV_MSG, it receives a message. The rcv_size argument specifies the size of the message buffer that will receive the message; messages larger than rcv_size are not received. The rcv_name argument specifies the port or port set from which to receive.

If the option argument is MACH_SEND_MSG|MACH_RCV_MSG, then mach_msg does both send and receive operations. If the send operation encounters an error (any return code other than MACH_MSG_SUCCESS), then the call returns immediately without attempting the receive operation. Semantically the combined call is equivalent to separate send and receive calls, but it saves a system call and enables other internal optimizations.

If the option argument specifies neither MACH_SEND_MSG nor MACH_RCV_MSG, then mach_msg does nothing.

Some options, like MACH_SEND_TIMEOUT and MACH_RCV_TIMEOUT, share a supporting argument. If these options are used together, they make independent use of the supporting argument's value.

— Data type: mach_msg_timeout_t

This is a natural_t used by the timeout mechanism. The units are milliseconds. The value to be used when there is no timeout is MACH_MSG_TIMEOUT_NONE.