This page is available in: en

tk_rcv_mbx

Receive Message from Mailbox

[C Language Interface]

ER ercd = tk_rcv_mbx ( ID mbxid, T_MSG **ppk_msg, TMO tmout ) ;
[Parameters]

ID    mbxid    Mailbox ID
TMO   tmout    timeout
[Return Parameters]

ER      ercd    Error code
T_MSG*  pk_msg	Start address of message packet
[Error Codes]

E_OK     Normal completion
E_ID     Invalid ID number (mbxid is invalid or cannot be used)
E_NOEXS  Object does not exist (the mailbox specified in mbxid does not exist)
E_PAR    Parameter error (tmout ( ≤-2))
E_DLT    The object being waited for was deleted (the mailbox was deleted while waiting)
E_RLWAI  Wait state released (tk_rel_wai received in wait state)
E_TMOUT  Polling failed or timeout
E_CTX    Context error (issued from task-independent portion or in dispatch disabled state)
[Description]

Receives a message from the mailbox specified in mbxid. If no messages have been sent to the mailbox (the message queue is empty), the task issuing this system call enters WAIT state and is queued for message arrival. If there are messages in the mailbox, the task issuing this system call fetches the first message in the message queue and passes it in the return parameter pk_msg.

A maximum wait time (timeout) can be set in tmout. If the tmout time elapses before the wait release condition is met (no message arrives), the system call terminates, returning timeout error code E_TMOUT. Only positive values can be set in tmout. The time base for tmout (time unit) is the same as that for system time (= 1 ms).

When TMO_POL = 0 is set in tmout, this means 0 was specified as the timeout value, and E_TMOUT is returned without entering WAIT state even if no message arrives. When TMO_FEVR =(-1) is set in tmout, this means infinity was specified as the timeout value, and the task continues to wait for message arrival without timing out.

[Additional Notes]

pk_msg is the start address of the packet containing the message, including header. The message header is T_MSG (if TA_MFIFO attribute is specified) or @T_MSG@_PRI (if TA_MPRI).

[Difference with T-Kernel]

E_DISWAI does not exist in error codes. This is because in µT-Kernel, there is no wait-disabled function.

Comments

Click here to Post a Comment