📄 semlib.html
字号:
<html><head><!-- /vobs/wpwr/docs/vxworks/ref/semLib.html - generated by refgen from semLib.c --> <title> semLib </title></head><body bgcolor="#FFFFFF"> <hr><a name="top"></a><p align=right><a href="libIndex.html"><i>VxWorks Reference Manual : Libraries</i></a></p></blockquote><h1>semLib</h1> <blockquote></a></blockquote><h4>NAME</h4><blockquote> <p><strong>semLib</strong> - general semaphore library </p></blockquote><h4>ROUTINES</h4><blockquote><p><p><b><i><a href="./semLib.html#semGive">semGive</a></i>( )</b> - give a semaphore<br><b><i><a href="./semLib.html#semTake">semTake</a></i>( )</b> - take a semaphore<br><b><i><a href="./semLib.html#semFlush">semFlush</a></i>( )</b> - unblock every task pended on a semaphore<br><b><i><a href="./semLib.html#semDelete">semDelete</a></i>( )</b> - delete a semaphore<br><p></blockquote><h4>DESCRIPTION</h4><blockquote><p>Semaphores are the basis for synchronization and mutual exclusion inVxWorks. They are powerful in their simplicity and form the foundationfor numerous VxWorks facilities.<p>Different semaphore types serve different needs, and while the behaviorof the types differs, their basic interface is the same. This libraryprovides semaphore routines common to all VxWorks semaphore types. Forall types, the two basic operations are <b><i><a href="./semLib.html#semTake">semTake</a></i>( )</b> and <b><i><a href="./semLib.html#semGive">semGive</a></i>( )</b>, theacquisition or relinquishing of a semaphore.<p>Semaphore creation and initialization is handled by other libraries,depending on the type of semaphore used. These libraries containfull functional descriptions of the semaphore types:<p> <b><a href="./semBLib.html#top">semBLib</a></b> - binary semaphores<br> <b><a href="./semCLib.html#top">semCLib</a></b> - counting semaphores<br> <b><a href="./semMLib.html#top">semMLib</a></b> - mutual exclusion semaphores<br> <b><a href="./semSmLib.html#top">semSmLib</a></b> - shared memory semaphores<p>Binary semaphores offer the greatest speed and the broadest applicability.<p>The <b><a href="./semLib.html#top">semLib</a></b> library provides all other semaphore operations, includingroutines for semaphore control, deletion, and information. Semaphoresmust be validated before any semaphore operation can be undertaken. Aninvalid semaphore ID results in ERROR, and an appropriate <b>errno</b> is set.<p></blockquote><h4>SEMAPHORE CONTROL</h4><blockquote><p>The <b><i><a href="./semLib.html#semTake">semTake</a></i>( )</b> call acquires a specified semaphore, blocking the callingtask or making the semaphore unavailable. All semaphore types support atimeout on the <b><i><a href="./semLib.html#semTake">semTake</a></i>( )</b> operation. The timeout is specified as thenumber of ticks to remain blocked on the semaphore. Timeouts of<b>WAIT_FOREVER</b> and <b>NO_WAIT</b> codify common timeouts. If a <b><i><a href="./semLib.html#semTake">semTake</a></i>( )</b> timesout, it returns ERROR. Refer to the library of the specific semaphore type for the exact behavior of this operation.<p>The <b><i><a href="./semLib.html#semGive">semGive</a></i>( )</b> call relinquishes a specified semaphore, unblocking a pendedtask or making the semaphore available. Refer to the library of thespecific semaphore type for the exact behavior of this operation.<p>The <b><i><a href="./semLib.html#semFlush">semFlush</a></i>( )</b> call may be used to atomically unblock all tasks pended ona semaphore queue, i.e., all tasks will be unblocked before any are allowedto run. It may be thought of as a broadcast operation insynchronization applications. The state of the semaphore is unchanged bythe use of <b><i><a href="./semLib.html#semFlush">semFlush</a></i>( )</b>; it is not analogous to <b><i><a href="./semLib.html#semGive">semGive</a></i>( )</b>.<p></blockquote><h4>SEMAPHORE DELETION</h4><blockquote><p>The <b><i><a href="./semLib.html#semDelete">semDelete</a></i>( )</b> call terminates a semaphore and deallocates anyassociated memory. The deletion of a semaphore unblocks tasks pendedon that semaphore; the routines which were pended return ERROR. Takecare when deleting semaphores, particularly those used for mutualexclusion, to avoid deleting a semaphore out from under a task thatalready has taken (owns) that semaphore. Applications should adoptthe protocol of only deleting semaphores that the deleting task hassuccessfully taken.<p></blockquote><h4>SEMAPHORE INFORMATION</h4><blockquote><p>The <b><i><a href="./semShow.html#semInfo">semInfo</a></i>( )</b> call is a useful debugging aid, reporting all tasksblocked on a specified semaphore. It provides a snapshot of the queue atthe time of the call, but because semaphores are dynamic, the informationmay be out of date by the time it is available. As with the current state ofthe semaphore, use of the queue of pended tasks should be restricted todebugging uses only.<p></blockquote><h4>INCLUDE FILES</h4><blockquote><p><b>semLib.h</b><p></blockquote><h4>SEE ALSO</h4><blockquote><p><b><a href="./semLib.html#top">semLib</a></b>, <b><a href="./taskLib.html#top">taskLib</a></b>, <b><a href="./semBLib.html#top">semBLib</a></b>, <b><a href="./semCLib.html#top">semCLib</a></b>, <b><a href="./semMLib.html#top">semMLib</a></b>, <b><a href="./semSmLib.html#top">semSmLib</a></b>, <i>VxWorks Programmer's Guide: Basic OS</i><hr><a name="semGive"></a><p align=right><a href="rtnIndex.html"><i>Libraries : Routines</i></a></p></blockquote><h1><i>semGive</i>( )</h1> <blockquote></a></blockquote><h4>NAME</h4><blockquote> <p><strong><i>semGive</i>( )</strong> - give a semaphore</p></blockquote><h4>SYNOPSIS</h4><blockquote><p><pre>STATUS semGive ( SEM_ID semId /* semaphore ID to give */ )</pre></blockquote><h4>DESCRIPTION</h4><blockquote><p>This routine performs the give operation on a specified semaphore.Depending on the type of semaphore, the state of the semaphore and of thepending tasks may be affected. The behavior of <b><i><a href="./semLib.html#semGive">semGive</a></i>( )</b> is discussedfully in the library description of the specific semaphore type being used.<p></blockquote><h4>RETURNS</h4><blockquote><p>OK, or ERROR if the semaphore ID is invalid.<p></blockquote><h4>ERRNO</h4><blockquote><p>S_intLib_NOT_ISR_CALLABLE, S_objLib_OBJ_ID_ERROR,<br> S_semLib_INVALID_OPERATION<p></blockquote><h4>SEE ALSO</h4><blockquote><p><b><a href="./semLib.html#top">semLib</a></b>, <b><a href="./semBLib.html#top">semBLib</a></b>, <b><a href="./semCLib.html#top">semCLib</a></b>, <b><a href="./semMLib.html#top">semMLib</a></b>, <b><a href="./semSmLib.html#top">semSmLib</a></b><hr><a name="semTake"></a><p align=right><a href="rtnIndex.html"><i>Libraries : Routines</i></a></p></blockquote><h1><i>semTake</i>( )</h1> <blockquote></a></blockquote><h4>NAME</h4><blockquote> <p><strong><i>semTake</i>( )</strong> - take a semaphore</p></blockquote><h4>SYNOPSIS</h4><blockquote><p><pre>STATUS semTake ( SEM_ID semId, /* semaphore ID to take */ int timeout /* timeout in ticks */ )</pre></blockquote><h4>DESCRIPTION</h4><blockquote><p>This routine performs the take operation on a specified semaphore.Depending on the type of semaphore, the state of the semaphore andthe calling task may be affected. The behavior of <b><i><a href="./semLib.html#semTake">semTake</a></i>( )</b> isdiscussed fully in the library description of the specific semaphore type being used.<p>A timeout in ticks may be specified. If a task times out, <b><i><a href="./semLib.html#semTake">semTake</a></i>( )</b> willreturn ERROR. Timeouts of <b>WAIT_FOREVER</b> (-1) and <b>NO_WAIT</b> (0) indicate to waitindefinitely or not to wait at all.<p>When <b><i><a href="./semLib.html#semTake">semTake</a></i>( )</b> returns due to timeout, it sets the errno toS_objLib_OBJ_TIMEOUT (defined in <b>objLib.h</b>).<p>The <b><i><a href="./semLib.html#semTake">semTake</a></i>( )</b> routine is not callable from interrupt service routines.<p></blockquote><h4>RETURNS</h4><blockquote><p>OK, or ERROR if the semaphore ID is invalid or the task timed out.<p></blockquote><h4>ERRNO</h4><blockquote><p>S_intLib_NOT_ISR_CALLABLE, S_objLib_OBJ_ID_ERROR,<br> S_objLib_OBJ_UNAVAILABLE<p></blockquote><h4>SEE ALSO</h4><blockquote><p><b><a href="./semLib.html#top">semLib</a></b>, <b><a href="./semBLib.html#top">semBLib</a></b>, <b><a href="./semCLib.html#top">semCLib</a></b>, <b><a href="./semMLib.html#top">semMLib</a></b>, <b><a href="./semSmLib.html#top">semSmLib</a></b><hr><a name="semFlush"></a><p align=right><a href="rtnIndex.html"><i>Libraries : Routines</i></a></p></blockquote><h1><i>semFlush</i>( )</h1> <blockquote></a></blockquote><h4>NAME</h4><blockquote> <p><strong><i>semFlush</i>( )</strong> - unblock every task pended on a semaphore</p></blockquote><h4>SYNOPSIS</h4><blockquote><p><pre>STATUS semFlush ( SEM_ID semId /* semaphore ID to unblock everyone for */ )</pre></blockquote><h4>DESCRIPTION</h4><blockquote><p>This routine atomically unblocks all tasks pended on a specifiedsemaphore, i.e., all tasks will be unblocked before any is allowedto run. The state of the underlying semaphore is unchanged. Allpended tasks will enter the ready queue before having a chance toexecute.<p>The flush operation is useful as a means of broadcast insynchronization applications. Its use is illegal for mutual-exclusionsemaphores created with <b><i><a href="./semMLib.html#semMCreate">semMCreate</a></i>( )</b>.<p></blockquote><h4>RETURNS</h4><blockquote><p>OK, or ERROR if the semaphore ID is invalidor the operation is not supported.<p></blockquote><h4>ERRNO</h4><blockquote><p>S_objLib_OBJ_ID_ERROR<p></blockquote><h4>SEE ALSO</h4><blockquote><p><b><a href="./semLib.html#top">semLib</a></b>, <b><a href="./semBLib.html#top">semBLib</a></b>, <b><a href="./semCLib.html#top">semCLib</a></b>, <b><a href="./semMLib.html#top">semMLib</a></b>, <b><a href="./semSmLib.html#top">semSmLib</a></b><hr><a name="semDelete"></a><p align=right><a href="rtnIndex.html"><i>Libraries : Routines</i></a></p></blockquote><h1><i>semDelete</i>( )</h1> <blockquote></a></blockquote><h4>NAME</h4><blockquote> <p><strong><i>semDelete</i>( )</strong> - delete a semaphore</p></blockquote><h4>SYNOPSIS</h4><blockquote><p><pre>STATUS semDelete ( SEM_ID semId /* semaphore ID to delete */ )</pre></blockquote><h4>DESCRIPTION</h4><blockquote><p>This routine terminates and deallocates any memory associated with aspecified semaphore. Any pended tasks will unblock and return ERROR.<p></blockquote><h4>WARNING</h4><blockquote><p>Take care when deleting semaphores, particularly those used formutual exclusion, to avoid deleting a semaphore out from under atask that already has taken (owns) that semaphore. Applicationsshould adopt the protocol of only deleting semaphores that thedeleting task has successfully taken.<p></blockquote><h4>RETURNS</h4><blockquote><p>OK, or ERROR if the semaphore ID is invalid.<p></blockquote><h4>ERRNO</h4><blockquote><p>S_intLib_NOT_ISR_CALLABLE, S_objLib_OBJ_ID_ERROR,<br> S_smObjLib_NO_OBJECT_DESTROY<p></blockquote><h4>SEE ALSO</h4><blockquote><p><b><a href="./semLib.html#top">semLib</a></b>, <b><a href="./semBLib.html#top">semBLib</a></b>, <b><a href="./semCLib.html#top">semCLib</a></b>, <b><a href="./semMLib.html#top">semMLib</a></b>, <b><a href="./semSmLib.html#top">semSmLib</a></b></body></html>⌨️ 快捷键说明
复制代码
Ctrl + C
搜索代码
Ctrl + F
全屏模式
F11
切换主题
Ctrl + Shift + D
显示快捷键
?
增大字号
Ctrl + =
减小字号
Ctrl + -