<!-- Copyright (c) 2000, 2001, 2002, 2003, 2004, 2005, 2008, 2009, 2013 The President and Fellows of Harvard College. Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: 1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. 2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. 3. Neither the name of the University nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission. THIS SOFTWARE IS PROVIDED BY THE UNIVERSITY AND CONTRIBUTORS ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE UNIVERSITY OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. --> <html> <head> <title>sbrk</title> <body bgcolor=#ffffff> <h2 align=center>sbrk</h2> <h4 align=center>OS/161 Reference Manual</h4> <h3>Name</h3> <p> sbrk - set process break (allocate memory) </p> <h3>Library</h3> <p> Standard C Library (libc, -lc) </p> <h3>Synopsis</h3> <p> <tt>#include <unistd.h></tt><br> <br> <tt>void *</tt><br> <tt>sbrk(intptr_t </tt><em>amount</em><tt>);</tt> </p> <h3>Description</h3> <p> The "break" is the end address of a process's heap region. The <tt>sbrk</tt> call adjusts the "break" by the amount <em>amount</em>. It returns the old "break". Thus, to determine the current "break", call <tt>sbrk(0)</tt>. </p> <p> The heap region is initially empty, so at process startup, the beginning of the heap region is the same as the end and may thus be retrieved using sbrk(0). </p> <p> In OS/161, the initial "break" must be page-aligned, and <tt>sbrk</tt> only need support values of <em>amount</em> that result in page-aligned "break" addresses. Other values of <em>amount</em> may be rejected. This may simplify the implementation. You may place the heap wherever you like in a process's address space (though obviously not on top of something else) and it need not appear at the same location in every process. </p> <p> Traditionally, the initial "break" is specifically defined to be the end of the BSS (uninitialized data) region, and traditionally any <em>amount</em>, page-aligned or not, may legally be used with <tt>sbrk</tt>. </p> <p> Ordinarily, user-level code should call <A HREF=../libc/malloc.html>malloc</A> for memory allocation. The <tt>sbrk</tt> interface is intended only to be the back-end interface for <tt>malloc</tt>. Mixing calls to <tt>malloc</tt> and <tt>sbrk</tt> will likely confuse <tt>malloc</tt> and produces undefined behavior. </p> <p> While one can lower the "break" by passing negative values of <em>amount</em>, one may not set the end of the heap to an address lower than the beginning of the heap. Attempts to do so must be rejected. </p> <p> The call (like all system calls) should be atomic. In this case, that means that if you have a multithreaded process, simultaneous calls to <tt>sbrk</tt> from different threads should not interfere with each other and should update the "break" state atomically. </p> <h3>Return Values</h3> <p> On success, <tt>sbrk</tt> returns the previous value of the "break". On error, ((void *)-1) is returned, and <A HREF=errno.html>errno</A> is set according to the error encountered. </p> <h3>Errors</h3> <p> The following error codes should be returned under the conditions given. Other error codes may be returned for other cases not mentioned here. <table width=90%> <tr><td width=5% rowspan=2> </td> <td with=10% valign=top>ENOMEM</td> <td>Sufficient virtual memory to satisfy the request was not available, or the process has reached the limit of the memory it is allowed to allocate.</td></tr> <tr><td valign=top>EINVAL</td> <td>The request would move the "break" below its initial value.</td></tr> </table> </p> <h3>Restrictions</h3> <p> While you can return pages that happen to be at the end of the heap to the system, there is no way to use the <tt>sbrk</tt> interface to return unused pages in the middle of the heap. If you wish to do this, you will need to design a new or supplemental interface. </p> </body> </html>