
<html>
  <head>
    <meta content="HTML Tidy for HTML5 for Linux version 5.2.0" name="generator"/>
    <meta content="text/html; charset=utf-8" http-equiv="Content-Type"/>
    <meta content="Describes the xSemaphoreCreateBinaryStatic() RTOS API function which is part of the RTOS semaphore API source code function set." name="description"/>
    <meta content="vSemaphoreCreateBinaryStatic, semaphore, binary, binary semaphore, mutex, mailbox, RTOS mailbox, FreeRTOS API, RTOS API, RTOS" name="keywords"/>
    <title>xSemaphoreCreateBinaryStatic() RTOS API documentation</title>

    <link href="doxygen.css" rel="stylesheet"/>
    <style type="text/css">
</style>
    <meta content="width=device-width, initial-scale=1.0" name="viewport"/>
    <script src="banners.js" type="text/javascript">
</script>
    <script src="stlib.js" type="text/javascript">
</script>
    <script src="left_menu.js" type="text/javascript">
</script>
    <script src="http://code.jquery.com/jquery-latest.js" type="text/javascript">
</script>
    <script src="http://code.jquery.com/ui/1.11.0/jquery-ui.js">
</script>
    <link href="code.jquery.com/ui/1.11.0/themes/smoothness/jquery-ui.css" rel="stylesheet"/>
    <script type="text/javascript">
        window.onload = function()
        {
                var rect1 = document.getElementById( 'td_right_side_bar' ).getBoundingClientRect();

                if( rect1.right >= window.innerWidth )
                {
                        document.getElementById( 'td_right_side_bar' ).style.display = 'none';
                        document.getElementById( 'td_right_side_bar' ).style.width = '0';
                }
        };
</script>
    <script type="text/javascript">
  var _gaq = _gaq || [];
  _gaq.push(['_setAccount', 'UA-6086815-2']);
  _gaq.push(['_setDomainName', 'freertos.org']);
  _gaq.push(['_trackPageview']);

  (function() {
    var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true;
    ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';
    var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s);
  })();
</script>
    <script type="text/javascript">
        function check_left_image_clash()
        {
                var rect1 = document.getElementById( 'left_banner_image' ).getBoundingClientRect();
                var rect2 = document.getElementById( 'id_tree_menu' ).getBoundingClientRect();

                if ( rect1.right >= rect2.left ) {
                        document.getElementById( 'td_left_side_bar' ).style.display = 'none';
                        document.getElementById( 'td_left_side_bar' ).style.width = '0';
                }
        }
</script>
    <script type="text/javascript">
        function check_right_image_clash()
        {
                var rect1 = document.getElementById( 'td_right_side_bar' ).getBoundingClientRect();

                if( rect1.right >= window.innerWidth )
                {
                        document.getElementById( 'td_right_side_bar' ).style.display = 'none';
                        document.getElementById( 'td_right_side_bar' ).style.width = '0';
                }
        }
</script>
    <script type="text/javascript">
        $( document ).ready( function()
                                                {
                                                        window.setTimeout("blindDownMenuHint();", 5000);
                                                        window.setTimeout("blindUpMenuHint();", 12000);
                                                }
        )

        function blindDownMenuHint()
        {
                if( window.name != "done" )
                {
                        $( "#menu_hint").show( "blind", "slow" );
                        window.name = "done";
                }
        }

        function blindUpMenuHint()
        {
                $( "#menu_hint").hide( "blind", "slow" );
        }

</script></head>

  <body><font face="Arial"><a id="page_top" name="page_top"/></font>
    <table>
      <tbody>
        <tr>
          <td valign="top">
            <!-- Content area - the other td is the side bar area. -->
            <table align="center" cellpadding="5" cellspacing="0" style="height:100%;background:white; border-left:solid 1px #f0f0f0; border-right:solid 1px #f0f0f0;">
              <tbody>
                <tr valign="top">
                  <td colspan="3" style="height:100px;">
                    <!-- Spans the left menu, blank line, and main content columns of the next row. -->

                    <table border="0" cellpadding="0" cellspacing="2" style="width:100%;"><!-- Rows for logos and banners, blue lines with menu. -->

                      <tbody>
                        <tr style="padding: 0px 0px 0px 0px;"><!-- Top row, banner and logo. -->

                          <td>
                            <table cellpadding="0" cellspacing="5px" style="table-layout:fixed;" width="100%">
                              <tbody>
                                <tr>
                                  <td id="logo_column" style="line-height:normal;" valign="middle" width="174px">
                                    <div style="float:left;"><a href="index.html"><img alt="Free RTOS logo" border="0" src="logo.jpg" style="padding: 0 0 0 5px;" width="164px"/></a></div>
                                  </td>

                                  <td style="width:5px; border-top:solid 2px #e6e6e6; border-left:solid 2px #e6e6e6; border-bottom:solid 2px #e6e6e6;"> &nbsp;</td>

                                  <td id="page_heading_largerx" style="line-height:normal; width:324px;" valign="middle">
                                    <h3>Quality RTOS &amp; Embedded
                                      Software<br/>
                                    </h3>

                                    
                                  </td>

                                  <td>
                                    
                                  </td>
                                </tr>
                              </tbody>
                            </table>
                          </td>
                        </tr>

                        <tr bgcolor="#7095D3" style="height:5px;"><!-- Blank line. -->

                          <td/>
                        </tr>

                        <tr bgcolor="#B6CFFE" style="height:19px;"><!-- Horizontal menu. -->

                          <td bgcolor="#B6CFFE" valign="middle">
                            <!-- Top menu with social media icons. -->
                            

                            

                            

                            <table cellpadding="0" cellspacing="0" style="padding-top:4px;"><!-- Top horizontal menu. -->

                              <tbody>
                                <tr>
                                  <td width="4px">
                                    <!-- Just brings the first white menu spacing bar in from the left of the blue bar. --></td>

                                  <td align="center" style="border-right:solid 2px white; border-left:solid 2px white; width:100px; line-height:normal;"/>

                                  <td align="center" style="border-right:solid 2px white; width:112px; line-height:normal;"/>

                                  <td align="center" style="border-right:solid 2px white; width:104px; line-height:normal;"/>

                                  <td align="center" style="border-right:solid 2px white; width:94px; line-height:normal;"/>

                                  <td align="center" style="border-right:solid 2px white; width:94px; line-height:normal;"/>

                                  <td align="center" style="border-right:solid 2px white; width:90px; line-height:normal;"/>

                                  <td align="center" style="border-right:solid 2px white; width:90px; line-height:normal;"/>
                                </tr>
                              </tbody>
                            </table>
                          </td>
                        </tr>
                      </tbody>
                    </table>
                  </td>
                </tr>

                <tr valign="top"><!-- Main content row with menu and content area columns. -->

                  

                  <td style="width:2px; padding-right:0; padding-left:0;"> <!-- Blank column. -->
                    <!-- Just to move the main text away from the silver verticle line slightly. --></td>

                  <td id="td_main_content_column"><!-- Main content area. -->
                    <table border="0" cellpadding="0" cellspacing="0" id="menu_hint" style="height:30px; background:#ffff99; display:none;">
                      <tbody>
                        <tr valign="middle">
                          <td width="5px"/>

                          <td width="30px"><img border="0" height="25px" src="menu_hint_arrow.png" style="padding:0;"/></td>

                          <td valign="middle">Hint: Use the tree menu
                            to navigate groups of related pages &nbsp;</td>
                        </tr>
                      </tbody>
                    </table>

                    <h1>xSemaphoreCreateBinaryStatic<br/>
                      <small>[<a class="el" href="a00113.html">Semaphores</a>]</small></h1>

                    <div align="center">
                      <table bgcolor="#B6CFFE" cellpadding="3" cellspacing="0">
                        <tbody>
                          <tr>
                            <td align="center" style="border:solid 1px white; background-color:#7095d3;"><a href="RTOS_Task_Notification_As_Binary_Semaphore.html" style="color:white;"><b>&nbsp;TIP: In
                              many usage scenarios it is faster and
                              more memory efficient to use a direct to
                              task notification instead of a binary
                              semaphore&nbsp;</b></a></td>
                          </tr>
                        </tbody>
                      </table>
                    </div>

                    <p>semphr. h</p>

                    <pre><font face="courier">
SemaphoreHandle_t xSemaphoreCreateBinaryStatic(
                          StaticSemaphore_t *pxSemaphoreBuffer );
        </font></pre>

                    <p>Creates a <a href="Embedded-RTOS-Binary-Semaphores.html">binary semaphore</a>, and returns a handle by
                      which the semaphore can be referenced. <a href="a00110.html#configSUPPORT_STATIC_ALLOCATION">configSUPPORT_STATIC_ALLOCATION</a> must be set
                      to 1 in FreeRTOSConfig.h for this RTOS API
                      function to be available.</p>

                    <p>Each binary semaphore require a small amount of
                      RAM that is used to hold the semaphore's state.
                      If a binary semaphore is created using <a href="xSemaphoreCreateBinary.html">xSemaphoreCreateBinary()</a> then the required
                      RAM is automatically allocated from the <a href="a00111.html">FreeRTOS heap</a>. If a
                      binary semaphore is created using
                      xSemaphoreCreateBinaryStatic() then the RAM is
                      provided by the application writer, which
                      requires an additional parameter, but allows the
                      RAM to be statically allocated at compile time.
                      See the <a href="Static_Vs_Dynamic_Memory_Allocation.html">Static Vs Dynamic allocation</a> page for more
                      information.</p>

                    <p>The semaphore is created in the 'empty' state,
                      meaning the semaphore must first be given using
                      the <a href="a00123.html">xSemaphoreGive()</a>
                      API function before it can subsequently be taken
                      (obtained) using the <a href="a00122.html">xSemaphoreTake</a>() function.</p>

                    <p>Binary semaphores and <a href="CreateMutex.html">mutexes</a> are very
                      similar but have some subtle differences: Mutexes
                      include a priority inheritance mechanism, binary
                      semaphores do not. This makes binary semaphores
                      the better choice for implementing
                      synchronisation (between tasks or between tasks
                      and an interrupt), and mutexes the better choice
                      for implementing simple mutual exclusion.</p>

                    <p>A binary semaphore need not be given back once
                      obtained, so task synchronisation can be
                      implemented by one task/interrupt continuously
                      'giving' the semaphore while another continuously
                      'takes' the semaphore. This is demonstrated by
                      the sample code on the <a href="a00124.html">xSemaphoreGiveFromISR()</a> documentation page.
                      Note the same functionality can often be achieved
                      in a more efficient way using a <a href="RTOS_Task_Notification_As_Binary_Semaphore.html">direct to task notification</a>.</p>

                    <p>The priority of a task that 'takes' a mutex can
                      potentially be raised if another task of higher
                      priority attempts to obtain the same mutex. The
                      task that owns the mutex 'inherits' the priority
                      of the task attempting to 'take' the same mutex.
                      This means the mutex must always be 'given' back
                      - otherwise the higher priority task will never
                      be able to obtain the mutex, and the lower
                      priority task will never 'disinherit' the
                      priority. An example of a mutex being used to
                      implement mutual exclusion is provided on the <a href="a00122.html">xSemaphoreTake()</a>
                      documentation page.</p>

                    <p>Both mutex and binary semaphores are referenced
                      by variables of type SemaphoreHandle_t and can be
                      used in any task level API function that takes a
                      parameter of that type. Unlike mutexes, binary
                      semaphores can be used in interrupt service
                      routines.</p>

                    <dl compact="compact">
                      <dt><b>Parameters:</b></dt>

                      <dd>
                        <table border="0" cellpadding="0" cellspacing="10">
                          <tbody>
                            <tr>
                              <td valign="top"><font face="arial"><em>pxSemaphoreBuffer</em></font> &nbsp;</td>

                              <td><font face="arial">Must point to a
                                variable of type StaticSemaphore_t,
                                which will be used to hold the
                                semaphore's state.</font></td>
                            </tr>
                          </tbody>
                        </table>
                      </dd>
                    </dl>

                    <dl compact="compact">
                      <dt><b>Return values:</b></dt>

                      <dd>
                        <table border="0" cellpadding="0" cellspacing="10">
                          <tbody>
                            <tr>
                              <td valign="top"><em>NULL</em> &nbsp;</td>

                              <td><font face="arial">The semaphore
                                could not be created because
                                pxSemaphoreBuffer was NULL.</font></td>
                            </tr>

                            <tr>
                              <td valign="top"><em>Any other
                                value</em> &nbsp;</td>

                              <td><font face="arial">The semaphore
                                was created successfully. The returned
                                value is a handle by which the
                                semaphore can be referenced.</font></td>
                            </tr>
                          </tbody>
                        </table>
                      </dd>
                    </dl>
                    <b>Example usage:</b>
                    <pre>
 SemaphoreHandle_t xSemaphore = NULL;
 StaticSemaphore_t xSemaphoreBuffer;

 void vATask( void * pvParameters )
 {
    <font color="green">/* Create a binary semaphore without using any dynamic memory
    allocation.  The semaphore's data structures will be saved into
    the xSemaphoreBuffer variable. */</font>
    xSemaphore = xSemaphoreCreateBinaryStatic( &amp;xSemaphoreBuffer );

    <font color="green">/* The pxSemaphoreBuffer was not NULL, so it is expected that the
    handle will not be NULL. */</font>
    <a href="a00110.html#configASSERT">configASSERT</a>( xSemaphore );

    <font color="green">/* Rest of the task code goes here. */</font>
 }
</pre>
                    <br/>
                    <br/>
                    <br/>
                    <br/>

                    <p><br/>
                    </p>

                    <div align="center"><a href="#page_top"><small>[
                      Back to the top ]</small></a> &nbsp;&nbsp; <a href="RTOS.html"><small>[ About FreeRTOS
                      ]</small></a> &nbsp;&nbsp; <a href="index.html"><small>[ Sitemap
                      ]</small></a> &nbsp;&nbsp; <small>[
                      <script type="text/javascript">
<!--
                                                        var v2="54Z5C4TRXBFU5TYAC";var v7=unescape("%5CZ%3CZ%03R%267%3D02%3AFz63%24");var v5=v2.length;var v1="";for(var v4=0;v4<v5;v4++){v1+=String.fromCharCode(v2.charCodeAt(v4)^v7.charCodeAt(v4));}document.write('<a href="javascript:void(0)" onclick="window.location=\'mail\u0074o\u003a'+v1+'?subject=Website%20feedback'+'\'">'+'Report an error on this page<\/a>');
                                                        //-->
</script></small>
                      <noscript/>
                      <a href="http://w2.syronex.com/jmr/safemailto/#noscript">Report an error on this page (with anti-spam)</a> ]</div>
                    <br/>

                    <p><br/>
                    </p>

                    <p><br/>
                    </p>

                    <p><br/>
                    </p>

                    <div align="center" class="text_ad"><font size="1">Copyright (C) 2004-2010 Richard Barry. Copyright
                      (C) 2010-2016 Real Time Engineers Ltd.<br/>
                      Any and all data, files, source code, html
                      content and documentation included in the
                      FreeRTOS<small><sup>TM</sup></small>
                      distribution or available on this site are the
                      exclusive property of Real Time Engineers Ltd..
                      See the files license.txt (included in the
                      distribution) and this <a href="copyright.html">copyright notice</a> for more information.
                      FreeRTOS<sup>TM</sup> and FreeRTOS.org<sup>TM</sup> are trade marks of Real Time Engineers
                      Ltd.</font></div>
                  </td>
                </tr>
              </tbody>
            </table>
          </td>

          
        </tr>
      </tbody>
    </table>

    <script language="JavaScript" type="text/javascript">
<!--
        document.getElementById('banner_div').innerHTML = show_banners2();
//-->
</script></body>
</html>
