NAME | SYNOPSIS | FEATURES | DESCRIPTION | RETURN VALUE | ERRORS | ATTRIBUTES | SEE ALSO
#include <ipc/chIpc.h>int ipcReceive(KnMsgDesc *msg, int *portli, int delay);
IPC
ipcReceive blocks the caller until a message (sent by ipcSend(2K), or ipcReply(2K), or ipcCall(2K)) is received on the port(s) specified by portli or the optional delay expires.
delay is the blocking waiting time, expressed in milliseconds. A delay of 0 means a non blocking attempt. If delay has a negative value, the blocking time is unbound.
At call time, portli is a pointer to the local identifier of the port on which a message is expected. If portli points to the value K_DEFAULTPORT, the default port of the current actor is used.
If portli points to the value K_ANYENABLED, a message is expected on any of the enabled ports owned by the current actor (see portEnable(2K)). In that case, the value pointed by portli is set, at return-time, to the local identifier of the port on which a message has been received. If more than one enabled port are holding messages at the time of the call, a message is received on the enabled port with the highest priority.
msg points to a message descriptor for the expected message. msg is a pointer to a KnMsgDesc structure whose members 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 ; /* sequence number */ |
The annexAddr member of the message descriptor gives the starting address at which the system must copy the message annex in the receiver's address space. If this member is set to NULL, the annex is not copied. Otherwise, K_CMSGANNEXSIZE bytes are copied by the system in the area starting at annexAddr in the receiver's address space. If the message was not sent with an annex (see ipcSend(2K)), this area is not affected.
The bodySize and bodyAddr members of the message descriptor respectively give the size of the expected body size and the starting address at which the system must copy it in the receiver's address space. If the body size is smaller than the real message size, only the expected amount is received and the remainder is discarded.
If bodyAddr is NULL or bodySize is set to zero, and if the message contains a body, the message body is not copied to the receiver address space but rather is kept in system buffers. If the body was not copied at receive time (NULL bodyAddr), it can be copied by an invocation of ipcGetData(2K). This allows the receiver to fix the message body location in its address space only when the message body size is known.
This call invalidates the current thread's previous current message. If the ipcReceive is successful, the received message becomes the current thread's current message, on which ipcReply(2K), ipcSysInfo(2K), ipcGetData(2K) or ipcSave(2K) may be applied.
The flags field of the message descriptor is a logical combination of the following options:
If this flag is set, ipcReceive is ABORTABLE. Otherwise, it is NONABORTABLE. These two different states determine the behavior of the thread when a threadAbort(2K) is applied to it. See threadAbort(2K) for a description of this behavior in the two different cases.
If the caller thread is a SUPERVISOR thread, this flag indicates that the message body destination address is part of the current user address space. If this flag is not set while the caller is a SUPERVISOR thread, the message body destination is assumed to be part of the microkernel address space. This flag is only to be used by trap handling routines, when a received message body has to be directly received in the user address space, without copying it into the microkernel address space. If the caller thread is not a SUPERVISOR thread, this flag is ignored (the message body destination is always assumed to be part of the user address space).
This flag has exactly the same meaning as the K_USERBODY, but concerns the message annex instead of the message body.
If flag is equal to 0, none of the previous options is selected: the blocking is NONABORTABLE, and message and annex are assumed to be part of the user (microkernel) address space when the caller is a USER (SUPERVISOR) thread.
Upon successful completion:
If bodyAddr is not NULL, and bodySize is greater than zero,the number of bytes of the message body that has been copied. If the system encountered a memory access fault while copying the message body to the receiver address space, the returned value is equal to the copied body size.
If bodyAddr is NULL, or if bodySize is set to 0, the size in bytes of the message body.
Otherwise, a negative error code is returned.
No port corresponds to portli.
A handler is attached to the port.
Some of the provided data are outside the current actor's address space.
The time out occurred.
The thread has been aborted while waiting.
See attributes(5) for descriptions of the following attributes:
ATTRIBUTE TYPE | ATTRIBUTE VALUE |
---|---|
Interface Stability | Evolving |
ipcSend(2K), ipcReply(2K), ipcCall(2K), ipcSave(2K), ipcSysInfo(2K), ipcGetData(2K), threadAbort(2K), svMsgHandler(2K)
NAME | SYNOPSIS | FEATURES | DESCRIPTION | RETURN VALUE | ERRORS | ATTRIBUTES | SEE ALSO