📄 sempxlib.html
字号:
<html><head><!-- /vobs/wpwr/docs/vxworks/ref/semPxLib.html - generated by refgen from semPxLib.c --> <title> semPxLib </title></head><body bgcolor="#FFFFFF"> <hr><a name="top"></a><p align=right><a href="libIndex.htm"><i>VxWorks API Reference : OS Libraries</i></a></p></blockquote><h1>semPxLib</h1> <blockquote></a></blockquote><h4>NAME</h4><blockquote> <p><strong>semPxLib</strong> - semaphore synchronization library (POSIX) </p></blockquote><h4>ROUTINES</h4><blockquote><p><p><b><a href="./semPxLib.html#semPxLibInit">semPxLibInit</a>( )</b> - initialize POSIX semaphore support<br><b><a href="./semPxLib.html#sem_init">sem_init</a>( )</b> - initialize an unnamed semaphore (POSIX)<br><b><a href="./semPxLib.html#sem_destroy">sem_destroy</a>( )</b> - destroy an unnamed semaphore (POSIX)<br><b><a href="./semPxLib.html#sem_open">sem_open</a>( )</b> - initialize/open a named semaphore (POSIX)<br><b><a href="./semPxLib.html#sem_close">sem_close</a>( )</b> - close a named semaphore (POSIX)<br><b><a href="./semPxLib.html#sem_unlink">sem_unlink</a>( )</b> - remove a named semaphore (POSIX)<br><b><a href="./semPxLib.html#sem_wait">sem_wait</a>( )</b> - lock (take) a semaphore, blocking if not available (POSIX)<br><b><a href="./semPxLib.html#sem_trywait">sem_trywait</a>( )</b> - lock (take) a semaphore, returning error if unavailable (POSIX)<br><b><a href="./semPxLib.html#sem_post">sem_post</a>( )</b> - unlock (give) a semaphore (POSIX)<br><b><a href="./semPxLib.html#sem_getvalue">sem_getvalue</a>( )</b> - get the value of a semaphore (POSIX)<br><p></blockquote><h4>DESCRIPTION</h4><blockquote><p><p>This library implements the POSIX 1003.1b semaphore interface. Foralternative semaphore routines designed expressly for VxWorks, seethe manual page for <b><a href="./semLib.html#top">semLib</a></b> and other semaphore librariesmentioned there. POSIX semaphores are counting semaphores; assuch they are most similar to the <b><a href="./semCLib.html#top">semCLib</a></b> VxWorks-specific semaphores.<p>The main advantage of POSIX semaphores is portability (to the extentthat alternative operating systems also provide these POSIXinterfaces). However, VxWorks-specific semaphores providethe following features absent from the semaphores implemented in thislibrary: priority inheritance, task-deletion safety, the ability for asingle task to take a semaphore multiple times, ownership ofmutual-exclusion semaphores, semaphore timeout, and the choice ofqueuing mechanism.<p>POSIX defines both named and unnamed semaphores; <b><a href="./semPxLib.html#top">semPxLib</a></b> includesseparate routines for creating and deleting each kind. For otheroperations, applications use the same routines for both kinds ofsemaphore.<p></blockquote><h4>TERMINOLOGY</h4><blockquote><p>The POSIX standard uses the terms <i>wait</i> or <i>lock</i> where<i>take</i> is normally used in VxWorks, and the terms <i>post</i> or<i>unlock</i> where <i>give</i> is normally used in VxWorks. VxWorksdocumentation that is specific to the POSIX interfaces (such as theremainder of this manual entry, and the manual entries for subroutinesin this library) uses the POSIX terminology, in order to make iteasier to read in conjunction with other references on POSIX.<p></blockquote><h4>SEMAPHORE DELETION</h4><blockquote><p>The <b><a href="./semPxLib.html#sem_destroy">sem_destroy</a>( )</b> call terminates an unnamed semaphore and deallocatesany associated memory; the combination of <b><a href="./semPxLib.html#sem_close">sem_close</a>( )</b> and <b><a href="./semPxLib.html#sem_unlink">sem_unlink</a>( )</b>has the same effect for named semaphores. Take care when deletingsemaphores, particularly those used for mutual exclusion, to avoiddeleting a semaphore out from under a task that has already lockedthat semaphore. Applications should adopt the protocol of onlydeleting semaphores that the deleting task has successfully locked.(Similarly, for named semaphores, applications should take care toonly close semaphores that the closing task has opened.)<p>If there are tasks blocked waiting for the semaphore, <b><a href="./semPxLib.html#sem_destroy">sem_destroy</a>( )</b>fails and sets <b>errno</b> to EBUSY.<p></blockquote><h4>INCLUDE FILES</h4><blockquote><p><b>semaphore.h</b><p></blockquote><h4>SEE ALSO</h4><blockquote><p>POSIX 1003.1b document, <b><a href="./semLib.html#top">semLib</a></b>, <i>VxWorks Programmer's Guide: Basic OS </i><hr><a name="semPxLibInit"></a><p align=right><a href="rtnIndex.htm"><i>OS Libraries : Routines</i></a></p></blockquote><h1>semPxLibInit( )</h1> <blockquote></a></blockquote><h4>NAME</h4><blockquote> <p><strong>semPxLibInit( )</strong> - initialize POSIX semaphore support</p></blockquote><h4>SYNOPSIS</h4><blockquote><p><pre>STATUS semPxLibInit (void)</pre></blockquote><h4>DESCRIPTION</h4><blockquote><p>This routine must be called before using POSIX semaphores.<p></blockquote><h4>RETURNS</h4><blockquote><p>OK, or ERROR if there is an error installing the semaphore library.</blockquote><h4>SEE ALSO</h4><blockquote><p><b><a href="./semPxLib.html#top">semPxLib</a></b><hr><a name="sem_init"></a><p align=right><a href="rtnIndex.htm"><i>OS Libraries : Routines</i></a></p></blockquote><h1>sem_init( )</h1> <blockquote></a></blockquote><h4>NAME</h4><blockquote> <p><strong>sem_init( )</strong> - initialize an unnamed semaphore (POSIX)</p></blockquote><h4>SYNOPSIS</h4><blockquote><p><pre>int sem_init ( sem_t * sem, /* semaphore to be initialized */ int pshared, /* process sharing */ unsigned int value /* semaphore initialization value */ )</pre></blockquote><h4>DESCRIPTION</h4><blockquote><p>This routine is used to initialize the unnamed semaphore <i>sem</i>.The value of the initialized semaphore is <i>value</i>. Following a successfulcall to <b><a href="./semPxLib.html#sem_init">sem_init</a>( )</b> the semaphore may be used in subsequent calls to<b><a href="./semPxLib.html#sem_wait">sem_wait</a>( )</b>, <b><a href="./semPxLib.html#sem_trywait">sem_trywait</a>( )</b>, and <b><a href="./semPxLib.html#sem_post">sem_post</a>( )</b>. This semaphore remains usableuntil the semaphore is destroyed.<p>The <i>pshared</i> parameter currently has no effect.<p>Only <i>sem</i> itself may be used for synchronization.<p></blockquote><h4>RETURNS</h4><blockquote><p>0 (OK), or -1 (ERROR) if unsuccessful.<p></blockquote><h4>ERRNO</h4><blockquote><p><p> EINVAL<br> - <i>value</i> exceeds <b>SEM_VALUE_MAX</b>.<br> ENOSPC <br> - unable to initialize semaphore due to resource constraints.<p></blockquote><h4>SEE ALSO</h4><blockquote><p><b><a href="./semPxLib.html#top">semPxLib</a></b>, <b><a href="./semPxLib.html#sem_wait">sem_wait</a>( )</b>, <b><a href="./semPxLib.html#sem_trywait">sem_trywait</a>( )</b>, <b><a href="./semPxLib.html#sem_post">sem_post</a>( )</b><hr><a name="sem_destroy"></a><p align=right><a href="rtnIndex.htm"><i>OS Libraries : Routines</i></a></p></blockquote><h1>sem_destroy( )</h1> <blockquote></a></blockquote><h4>NAME</h4><blockquote> <p><strong>sem_destroy( )</strong> - destroy an unnamed semaphore (POSIX)</p></blockquote><h4>SYNOPSIS</h4><blockquote><p><pre>int sem_destroy ( sem_t * sem /* semaphore descriptor */ )</pre></blockquote><h4>DESCRIPTION</h4><blockquote><p>This routine is used to destroy the unnamed semaphore indicated by <i>sem</i>.<p>The <b><a href="./semPxLib.html#sem_destroy">sem_destroy</a>( )</b> call can only destroy a semaphore created by <b><a href="./semPxLib.html#sem_init">sem_init</a>( )</b>.Calling <b><a href="./semPxLib.html#sem_destroy">sem_destroy</a>( )</b> with a named semaphore will cause a EINVAL error.Subsequent use of the <i>sem</i> semaphore will cause an EINVAL error in thecalling function.<p>If one or more tasks is blocked on the semaphore, the semaphore is notdestroyed.<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 has already locked that semaphore. Applications shouldadopt the protocol of only deleting semaphores that the deletingtask has successfully locked.<p></blockquote><h4>RETURNS</h4><blockquote><p>0 (OK), or -1 (ERROR) if unsuccessful.<p></blockquote><h4>ERRNO</h4><blockquote><p><p> EINVAL <br> - invalid semaphore descriptor.<br> EBUSY<br> - one or more tasks is blocked on the semaphore.<p></blockquote><h4>SEE ALSO</h4><blockquote><p><b><a href="./semPxLib.html#top">semPxLib</a></b>, <b><a href="./semPxLib.html#sem_init">sem_init</a>( )</b><hr><a name="sem_open"></a><p align=right><a href="rtnIndex.htm"><i>OS Libraries : Routines</i></a></p></blockquote><h1>sem_open( )</h1> <blockquote></a></blockquote><h4>NAME</h4><blockquote> <p><strong>sem_open( )</strong> - initialize/open a named semaphore (POSIX)</p></blockquote><h4>SYNOPSIS</h4><blockquote><p><pre>sem_t * sem_open ( const char * name, /* semaphore name */ int oflag, /* semaphore creation flags */ ... /* extra optional parameters */ )</pre></blockquote><h4>DESCRIPTION</h4><blockquote><p>This routine establishes a connection between a named semaphore anda task. Following a call to <b><a href="./semPxLib.html#sem_open">sem_open</a>( )</b> with a semaphore name <i>name</i>,the task may reference the semaphore associated with <i>name</i> usingthe address returned by this call. This semaphore may be used in subsequent calls to <b><a href="./semPxLib.html#sem_wait">sem_wait</a>( )</b>, <b><a href="./semPxLib.html#sem_trywait">sem_trywait</a>( )</b>, and <b><a href="./semPxLib.html#sem_post">sem_post</a>( )</b>. The semaphore remains usable until the semaphore is closed by a successfulcall to <b><a href="./semPxLib.html#sem_close">sem_close</a>( )</b>. <p>The <i>oflag</i> argument controls whether the semaphore is created or merelyaccessed by the call to <b><a href="./semPxLib.html#sem_open">sem_open</a>( )</b>. The following flag bits may be setin <i>oflag</i>:<p><dl><dt><b>O_CREAT</b><dd>Use this flag to create a semaphore if it does not already exist. If<b>O_CREAT</b> is set and the semaphore already exists, <b>O_CREAT</b> has no effectexcept as noted below under <b>O_EXCL</b>. Otherwise, <b><a href="./semPxLib.html#sem_open">sem_open</a>( )</b> creats asemaphore. <b>O_CREAT</b> requires a third and fourth argument: <i>mode</i>, which isof type <b>mode_t</b>, and <i>value</i>, which is of type unsigned int. <i>mode</i> has noeffect in this implementation. The semaphore is created with an initialvalue of <i>value</i>. Valid initial values for semaphores must be less thanor equal to <b>SEM_VALUE_MAX</b>.<p><dt><b>O_EXCL</b><dd>If <b>O_EXCL</b> and <b>O_CREAT</b> are set, <b><a href="./semPxLib.html#sem_open">sem_open</a>( )</b> will fail if the semaphore nameexists. If <b>O_EXCL</b> is set and <b>O_CREAT</b> is not set, the named semaphore is not created.</dl><p>To determine whether a named semaphore already exists in the system,call <b><a href="./semPxLib.html#sem_open">sem_open</a>( )</b> with the flags <b>O_CREAT | O_EXCL</b>. If the<b><a href="./semPxLib.html#sem_open">sem_open</a>( )</b> call fails, the semaphore exists.<p>If a task makes multiple calls to <b><a href="./semPxLib.html#sem_open">sem_open</a>( )</b> with the same valuefor <i>name</i>, then the same semaphore address is returned for each suchcall, provided that there have been no calls to <b><a href="./semPxLib.html#sem_unlink">sem_unlink</a>( )</b>for this semaphore.<p>References to copies of the semaphore will produce undefined results.<p></blockquote><h4>NOTE</h4><blockquote><p>The current implementation has the following limitations:<p> - A semaphore cannot be closed with calls to <b>_exit( )</b> or <b>exec( )</b>.<br> - A semaphore cannot be implemented as a file.<br> - Semaphore names will not appear in the file system. <p></blockquote><h4>RETURNS</h4><blockquote><p>A pointer to <b>sem_t</b>, or -1 (ERROR) if unsuccessful. <p></blockquote><h4>ERRNO</h4><blockquote><p><p> EEXIST<br> - <b>O_CREAT</b> | <b>O_EXCL</b> are set and the semaphore already exists.<br> EINVAL<br> - <i>value</i> exceeds <b>SEM_VALUE_MAX</b> or the semaphore name is invalid.<br> ENAMETOOLONG<br> - the semaphore name is too long.<br>⌨️ 快捷键说明
复制代码
Ctrl + C
搜索代码
Ctrl + F
全屏模式
F11
切换主题
Ctrl + Shift + D
显示快捷键
?
增大字号
Ctrl + =
减小字号
Ctrl + -