T-Kernel Specification (1.B0.02)

112 CHAPTER 4. T-KERNEL/OS FUNCTIONS
tk loc mtx
Lock Mutex
[C Language Interface]
ER ercd = tk_loc_mtx ( ID mtxid, TMO tmout ) ;
[Parameters]
ID mtxid Mutex ID
TMO tmout Timeout designation
[Return Parameters]
ER ercd Error code
[Error Codes]
E OK
E ID
E NOEXS
E PAR
E DLT
E RLWAI
E DISWAI
E TMOUT
E CTX
E ILUSE
Normal completion
Invalid ID number (mtxid is invalid or cannot be used)
Object does not exist (the mutex designated in mtxid does not exist)
Parameter error (tmout ≤ (−2))
The object being waited for was deleted (the mutex was deleted while waiting for a lock)
Wait state released (tk rel wai received in wait state)
Wait released by wait disabled state
Polling failed or timeout
Context error (issued from task-independent portion or in dispatch disabled state)
Illegal use (multiple lock, or upper priority limit exceeded)
[Description]
Locks the mutex designated in mtxid. If the mutex can be locked immediately, the task issuing this
system call continue executing without entering WAIT state, and the mutex goes to locked status. If
the mutex cannot be locked, the task issuing this system call enters WAIT state. That is, the task is
put in the queue of this mutex.
A maximum wait time (timeout) can be set in tmout. If the tmout time elapses before the wait release
condition is met, 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 designated as the timeout value, and E TMOUT is
returned without entering WAIT state even if the resource cannot be locked. When TMO FEVR = (−1)
is set in tmout, this means infinity was designated as the timeout value, and the task continues wait to
until the resource is locked.
If the invoking task has already locked the designated mutex, error code E ILUSE (multiple lock) is
returned.
Copyright c○ 2002, 2003 by T-Engine Forum
T-Kernel 1.B0.02