ChorusOS man pages section 2K: Kernel System Calls

ipcSend(2K)

NAME

ipcSend- send a message

SYNOPSIS

#include <ipc/chIpc.h>

msg

msgsrc

msgdest

FEATURES

IPC

DESCRIPTION

ipcSend sends an asynchronous message. msgdest defines the destination of the message. It is a pointer to a KnIpcDest structure the members of which are the following:

KnUniqueId       target ;          /* port or group */
KnUniqueId       coTarget ;        /* site qualifier */

If target is a port name, the message will be sent to that port. target may also be a port group name in which an addressing mode has been set using ipcTarget(2K). If the addressing mode is K_BROADMODE, the message will be sent to each reachable member of the group (i.e. ports which have been inserted in the group - see grpPortInsert(2K)). If the addressing mode is K_FUNCMODE, the message will be sent to one of the reachable members of the group. If the addressing mode is K_FUNCUMODE, the message will be sent to one of the reachable members of the group which reside on the site denoted by coTarget. coTarget is a unique identifier. This addressing mode is called associative functional mode. A site is denoted by such a unique identifier, if this unique identifier has been declared on the site. For example, the names of the ports owned by the actors located on the site and the pre-defined site unique identifiers (see uiSite(2K)) are identifiers which are automatically registered on a site. If the addressing mode is K_FUNCXMODE, the message will be sent to one of the reachable members of the group, assuming that the UI of the selected member is different from the UI given by coTarget. This addressing mode is called exclusive functional mode.

msgsrc is the local identifier of a port owned by the sender, and specifies the source port of the message. If one of the receivers of the message performs a ipcReply(2K) on it, the reply will be sent to that port. The unique identifier of this port is given to a receiver which performs a ipcSysInfo(2K), as the name of the source port of the message. If msgsrc is K_DEFAULTPORT, the current actor default port is used.

msg points to a descriptor for the message to be sent, and is a pointer to a KnMsgDesc structure, the members of which are the following:

unsigned int    flags ;     /* message structure definition */
unsigned int    bodySize ;  /* body size */
VmAddr          bodyAddr ;	 /* body address */
VmAddr          annexAddr ; /* fixed size annex address */
KnEvtNum        seqNum ;    /* not used */

The message data is composed of a message body, a byte string of variable size (limited to K_CMSGSIZEMAX), to which a message annex, a small fixed sized (K_CMSGANNEXSIZE) byte string, might be associated.

The bodySize and bodyAddr members of the message descriptor respectively give the size of the message body and its starting address in the sender address space. bodySize is limited to K_CMSGSIZEMAX. If bodySize is set to 0, or bodyAddr is NULL, the size in bytes of the message is zero.

The annexAddr member of the message descriptor gives the starting address of the message annex in the sender address space. If this field is NULL, no annex is sent with the message body.

The flags field of the message descriptor should in general be set to zero. Only trusted users should use non-zero flags.

Note -

If flag is equal to 0, none of the options listed below is selected: the message body will be copied (never "moved"), and body and annex are assumed to be part of the user (microkernel) address space when the caller is a USER (SUPERVISOR) thread.

K_USERBODY: If the caller thread is a SUPERVISOR thread, this flag indicates that the message body is part of the current user address space. If this flag is not set while the caller is a SUPERVISOR thread, the message body is assumed to be part of the microkernel address space. This flag is only to be used by trap handling routines, when data located in the user address space have to be directly used as a message body, without copying them into the microkernel address space. If the caller thread is not a SUPERVISOR thread, this flag is ignored (the message body is always assumed to be part of the user address space).
K_USERANNEX: This flag has exactly the same meaning as the K_USERBODY, but concerns the message annex instead of the message body.

The message is sent asynchronously.

RETURN VALUE

Upon successful completion, a value of 0 is returned. Otherwise, a negative error code is returned.

ERRORS

[K_EFULL]: The destination port is local and its queue is full, or the local communication subsystem is saturated.
[K_EINVAL]: msgsrc is not a valid local port identifier.
[K_EFAULT]: Some of the provided data are outside the current actor's address space.
[K_ENOMEM]: No memory available.
[K_ETOOMUCH]: bodysize is too big.
[K_EUNKNOWN]: Unreachable destination.

ATTRIBUTES

See attributes(5) for descriptions of the following attributes:

ATTRIBUTE TYPE	ATTRIBUTE VALUE
Interface Stability	Evolving