nephele
/
haiku-website
0
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity
haiku-website/static/legacy-docs/bebook/TheKernelKit_Areas.html

196 lines
35 KiB
HTML
Raw Permalink Blame History

This file contains invisible Unicode characters

This file contains invisible Unicode characters that are indistinguishable to humans but may be processed differently by a computer. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>The Be Book - Classes And Methods - The Kernel Kit</title><link rel="stylesheet" href="be_book.css" type="text/css" media="all" /><link rel="shortcut icon" type="image/vnd.microsoft.icon" href="./images/favicon.ico" /><!--[if IE]>
<link rel="stylesheet" type="text/css" href="be_book_ie.css" />
<![endif]--><meta name="generator" content="DocBook XSL Stylesheets V1.73.2" /><meta name="keywords" content="Access, BeOS, BeBook, API" /><link rel="start" href="index.html" title="The Be Book" /><link rel="up" href="TheKernelKit.html" title="The Kernel Kit" /><link rel="prev" href="TheKernelKit.html" title="The Kernel Kit" /><link rel="next" href="TheKernelKit_Images.html" title="Images" /></head><body><div id="header"><div id="headerT"><div id="headerTL"><a accesskey="p" href="TheKernelKit.html" title="The Kernel Kit"><img src="./images/navigation/prev.png" alt="Prev" /></a> <a accesskey="u" href="TheKernelKit.html" title="The Kernel Kit"><img src="./images/navigation/up.png" alt="Up" /></a> <a accesskey="n" href="TheKernelKit_Images.html" title="Images"><img src="./images/navigation/next.png" alt="Next" /></a></div><div id="headerTR"><div id="navigpeople"><a href="http://www.haiku-os.org"><img src="./images/People_24.png" alt="haiku-os.org" title="Visit The Haiku Website" /></a></div><div class="navighome" title="Home"><a accesskey="h" href="index.html"><img src="./images/navigation/home.png" alt="Home" /></a></div><div class="navigboxed" id="navigindex"><a accesskey="i" href="ClassIndex.html" title="Index">I</a></div><div class="navigboxed" id="naviglang" title="English">en</div></div><div id="headerTC">The Be Book - Classes And Methods - The Kernel Kit</div></div><div id="headerB">Prev: <a href="TheKernelKit.html">The Kernel Kit</a>  Up: <a href="TheKernelKit.html">The Kernel Kit</a>  Next: <a href="TheKernelKit_Images.html">Images</a></div><hr /></div><div class="section"><div xmlns="" xmlns:d="http://docbook.org/ns/docbook" class="titlepage"><div><div xmlns:d="http://docbook.org/ns/docbook"><h2 xmlns="http://www.w3.org/1999/xhtml" class="title"><a id="TheKernelKit_Areas"></a>Areas</h2></div></div></div><div class="informaltable"><table border="0"><colgroup><col /><col /></colgroup><tbody><tr><td>Declared in:</td><td><code class="filename">kernel/OS.h</code></td></tr><tr><td>Library:</td><td><code class="filename">libroot.so</code></td></tr></tbody></table></div><p>An area is a chunk of virtual memory that can be shared between threads
(possibly in different teams). If your application needs to allocate
large chunks of memory, or wants to share lots of data with another
application, you should consider using an area.</p><p>For more on area concepts, see
"<a class="link" href="TheKernelKit_Areas_Overview.html" title="Areas">Areas Overview</a>".</p><p>For examples of creating and sharing areas, see
"<a class="link" href="TheKernelKit_Areas_Overview.html#Areas_Examples" title="Area Examples">Area Examples</a>".</p><div class="section"><div xmlns="" xmlns:d="http://docbook.org/ns/docbook" class="titlepage"><div><hr /><div xmlns:d="http://docbook.org/ns/docbook"><h3 xmlns="http://www.w3.org/1999/xhtml" class="title"><a id="Areas_Functions"></a>Area Functions</h3></div></div></div><div class="section"><div xmlns="" xmlns:d="http://docbook.org/ns/docbook" class="titlepage"><div><div xmlns:d="http://docbook.org/ns/docbook"><h4 xmlns="http://www.w3.org/1999/xhtml" class="title"><a id="area_for"></a>area_for()</h4></div></div></div><a id="id1099125" class="indexterm"></a><code class="methodsynopsis c"><span class="type">area_id </span><span class="methodname">area_for</span>(<span class="methodparam"><span class="type">void* </span><span class="parameter">addr</span></span>);</code><p>Returns the area that contains the given address (within your own team's
address space). The argument needn't be the starting address of an area,
nor must it start on a page boundary: If the address lies anywhere within
one of your application's areas, the ID of that area is returned.</p><p>Since the address is taken to be in the local address space, the area
that's returned will also be local—it will have been created or
cloned by your application.</p><table class="variablelist returncodes"><thead><tr><th>Return Code</th><th>Description</th></tr></thead><tbody><tr><td><p><span class="term"><code class="constant">B_ERROR</code>.</span></p></td><td><p>The address doesn't lie within an area.</p></td></tr></tbody></table><p>See also:
<a class="link" href="TheKernelKit_Areas.html#find_area" title="find_area()"><code class="function">find_area()</code></a></p></div><div class="section"><div xmlns="" xmlns:d="http://docbook.org/ns/docbook" class="titlepage"><div><div xmlns:d="http://docbook.org/ns/docbook"><h4 xmlns="http://www.w3.org/1999/xhtml" class="title"><a id="clone_area"></a>clone_area()</h4></div></div></div><a id="id1099211" class="indexterm"></a><code class="methodsynopsis c"><span class="type">area_id </span><span class="methodname">clone_area</span>(<span class="methodparam"><span class="type">const char* </span><span class="parameter">clone_name</span></span>,<br />                   <span class="methodparam"><span class="type">void** </span><span class="parameter">clone_addr</span></span>,<br />                   <span class="methodparam"><span class="type">uint32 </span><span class="parameter">clone_addr_spec</span></span>,<br />                   <span class="methodparam"><span class="type">uint32 </span><span class="parameter">clone_protection</span></span>,<br />                   <span class="methodparam"><span class="type">area_id </span><span class="parameter">source_area</span></span>);</code><p>Creates a new area (the clone area) that maps to the same physical memory
as an existing area (the source area).</p><table class="variablelist parameters"><thead><tr><th>Parameter</th><th>Description</th></tr></thead><tbody><tr><td><p><span class="term"><code class="parameter">clone_name</code></span></p></td><td><p>Is the name that you wish to assign to the clone area.
Area names are, at most, <code class="constant">B_OS_NAME_LENGTH</code> characters long.</p></td></tr><tr><td><p><span class="term"><code class="parameter">clone_addr</code></span></p></td><td><p>Points to a value that gives the address at which you want
the clone area to start; the pointed-to value must be a multiple of
<code class="constant">B_PAGE_SIZE</code> (4096). The function sets the value pointed to by
<code class="parameter">clone_addr</code> to the area's actual starting address—it may be
different from the one you requested. The constancy of
<span class="code">*<code class="parameter">clone_addr</code></span>
depends on the value of <code class="parameter">clone_addr_spec</code>, as explained next.</p></td></tr><tr><td><p><span class="term"><code class="parameter">clone_addr_spec</code></span></p></td><td><p>Is one of four constants that describes how
clone_addr is to be interpreted. The first three constants,
<code class="constant">B_EXACT_ADDRESS</code>, <code class="constant">B_BASE_ADDRESS</code>,
and <code class="constant">B_ANY_ADDRESS</code>, have meanings as
explained under
<a class="link" href="TheKernelKit_Areas.html#create_area" title="create_area()"><code class="function">create_area()</code></a>.</p><p>The fourth constant, <code class="constant">B_CLONE_ADDRESS</code>, specifies that the address of the
cloned area should be the same as the address of the source area. Cloning
the address is convenient if you have two (or more) applications that
want to pass pointers to each other—by using cloned addresses, the
applications won't have to offset the pointers that they receive. For
both the <code class="constant">B_ANY_ADDRESS</code> and <code class="constant">B_CLONE_ADDRESS</code> specifications, the value
that's pointed to by the <code class="parameter">clone_addr</code> argument is ignored.</p></td></tr><tr><td><p><span class="term"><code class="parameter">clone_protection</code></span></p></td><td><p>Is one or both of <code class="constant">B_READ_AREA</code> and <code class="constant">B_WRITE_AREA</code>.
These have the same meaning as in
<a class="link" href="TheKernelKit_Areas.html#create_area" title="create_area()"><code class="function">create_area()</code></a>;
keep in mind, as described there, that a cloned area can have a protection that's
different from that of its source.</p></td></tr><tr><td><p><span class="term"><code class="parameter">source_area</code></span></p></td><td><p>Is the <span class="type">area_id</span> of the area that you wish to clone. You
usually supply this value by passing an area name to the
<a class="link" href="TheKernelKit_Areas.html#find_area" title="find_area()"><code class="function">find_area()</code></a>
function.</p></td></tr></tbody></table><p>The cloned area inherits the source area's locking scheme.</p><p>Usually, the source area and clone area are in two different
applications. It's possible to clone an area from a source that's in the
same application, but there's not much reason to do so unless you want
the areas to have different protections.</p><p>If <code class="function">clone_area()</code> clone is successful,
the clone's <span class="type">area_id</span> is returned.
Otherwise, it returns a descriptive error code, listed below.</p><table class="variablelist returncodes"><thead><tr><th>Return Code</th><th>Description</th></tr></thead><tbody><tr><td><p><span class="term"><code class="constant">B_BAD_VALUE</code>.</span></p></td><td>
Bad argument value; you passed an unrecognized constant
for <code class="parameter">addr_spec</code> or <code class="parameter">lock</code>,
the <code class="parameter">addr</code> value isn't a multiple of <code class="constant">B_PAGE_SIZE</code>,
you set <code class="parameter">addr_spec</code> to <code class="constant">B_EXACT_ADDRESS</code>
or <code class="constant">B_CLONE_ADDRESS</code> but the address
request couldn't be fulfilled, or <code class="parameter">source_area</code> doesn't identify an
existing area.
</td></tr><tr><td><p><span class="term"><code class="constant">B_NO_MEMORY</code>.</span></p></td><td>
Not enough memory to allocate the system structures that
support this area (unlikely).
</td></tr><tr><td><p><span class="term"><code class="constant">B_ERROR</code>.</span></p></td><td>
Some other system error prevented the area from being
created.
</td></tr></tbody></table></div><div class="section"><div xmlns="" xmlns:d="http://docbook.org/ns/docbook" class="titlepage"><div><div xmlns:d="http://docbook.org/ns/docbook"><h4 xmlns="http://www.w3.org/1999/xhtml" class="title"><a id="create_area"></a>create_area()</h4></div></div></div><a id="id1099587" class="indexterm"></a><code class="methodsynopsis c"><span class="type">area_id </span><span class="methodname">create_area</span>(<span class="methodparam"><span class="type">const char* </span><span class="parameter">name</span></span>,<br />                    <span class="methodparam"><span class="type">void** </span><span class="parameter">addr</span></span>,<br />                    <span class="methodparam"><span class="type">uint32 </span><span class="parameter">addr_spec</span></span>,<br />                    <span class="methodparam"><span class="type">uint32 </span><span class="parameter">size</span></span>,<br />                    <span class="methodparam"><span class="type">uint32 </span><span class="parameter">lock</span></span>,<br />                    <span class="methodparam"><span class="type">uint32 </span><span class="parameter">protection</span></span>);</code><p>Creates a new area and returns its <span class="type">area_id</span>.</p><table class="variablelist parameters"><thead><tr><th>Parameter</th><th>Description</th></tr></thead><tbody><tr><td><p><span class="term"><code class="parameter">name</code></span></p></td><td>
Is the name that you wish to assign to the area. It needn't be
unique. Area names are, at most, <code class="constant">B_OS_NAME_LENGTH</code> (32) characters long.
</td></tr><tr><td><p><span class="term"><code class="parameter">addr</code></span></p></td><td><p>Points to the address at which you want the area to start. The
value of <span class="code">*<code class="parameter">addr</code></span> must signify a page boundary; in other words, it must be
an integer multiple of <code class="constant">B_PAGE_SIZE</code> (4096). Note that this is a pointer
to a pointer: <span class="code">*<code class="parameter">addr</code></span>—not <code class="parameter">addr</code>—should be set to the desired
address; you then pass the address of <code class="parameter">addr</code> as the argument, as shown
below:</p><pre class="programlisting example c"><span class="comment">/* Set the address to a page boundary. */</span>
<span class="type">char *</span><code class="varname">addr</code> = (<span class="type">char *</span>)(<code class="constant">B_PAGE_SIZE</code> * 100);
<span class="comment">/* Pass the address of addr as the second argument. */</span>
<code class="function">create_area</code>( "my area", &amp;<code class="varname">addr</code>, ...);</pre><p>The function sets the value of <span class="code">*<code class="parameter">addr</code></span> to the area's actual starting
address—it may be different from the one you requested. The
constancy of <span class="code">*<code class="parameter">addr</code></span> depends on the
value of <code class="parameter">addr_spec</code>, as explained next.</p></td></tr><tr><td><p><span class="term"><code class="parameter">addr_spec</code></span></p></td><td><p>Is a constant that tells the function how the
<span class="code">*<code class="parameter">addr</code></span> value
should be applied. There are three useful address specification
constants, and one that doesn't apply here:</p><table class="variablelist constants"><thead><tr><th>Constant</th><th>Description</th></tr></thead><tbody><tr><td><p><span class="term"><code class="constant">B_EXACT_ADDRESS</code></span></p></td><td><p>You want the value of
<span class="code">*<code class="parameter">addr</code></span>
to be taken literally and
strictly. If the area can't be allocated at that location, the function
fails.</p></td></tr><tr><td><p><span class="term"><code class="constant">B_BASE_ADDRESS</code></span></p></td><td><p>The area can start at a location equal to or greater than
<span class="code">*<code class="parameter">addr</code></span>.</p></td></tr><tr><td><p><span class="term"><code class="constant">B_ANY_ADDRESS</code></span></p></td><td><p>The starting address is determined by the system. In this
case, the value that's pointed to by <code class="parameter">addr</code> is ignored (going into the
function).</p></td></tr><tr><td><p><span class="term"><code class="constant">B_ANY_KERNEL_ADDRESS</code></span></p></td><td><p>The starting address is determined by the system,
and the new area will belong to the kernel's team; it won't be deleted
when the application quits. In this case, the value that's pointed to by
<code class="parameter">addr</code> is ignored (going into the function).</p></td></tr><tr><td><p><span class="term"><code class="constant">B_CLONE_ADDRESS</code></span></p></td><td><p>This is only meaningful to the
<a class="link" href="TheKernelKit_Areas.html#clone_area" title="clone_area()"><code class="function">clone_area()</code></a>
function.</p></td></tr></tbody></table></td></tr><tr><td><p><span class="term"><code class="parameter">size</code></span></p></td><td><p>Is the size, in bytes, of the area. The size must be an integer
multiple of <code class="constant">B_PAGE_SIZE</code> (4096). The upper limit of size depends on the
available swap space (or RAM, if the area is to be locked).</p></td></tr><tr><td><p><span class="term"><code class="parameter">lock</code></span></p></td><td><p>Describes how the physical memory should be treated with regard
to swapping. There are four locking constants:</p><table class="variablelist constants"><thead><tr><th>Constant</th><th>Description</th></tr></thead><tbody><tr><td><p><span class="term"><code class="constant">B_FULL_LOCK</code></span></p></td><td><p>The area's memory is locked into RAM when the area is
created, and won't be swapped out.</p></td></tr><tr><td><p><span class="term"><code class="constant">B_CONTIGUOUS</code></span></p></td><td><p>Not only is the area's memory locked into RAM, it's also
guaranteed to be contiguous. This is particularly—and perhaps
exclusively—useful to designers of certain types of device drivers.</p></td></tr><tr><td><p><span class="term"><code class="constant">B_LAZY_LOCK</code></span></p></td><td><p>Allows individual pages of memory to be brought into RAM
through the natural order of things and then locks them.</p></td></tr><tr><td><p><span class="term"><code class="constant">B_NO_LOCK</code></span></p></td><td><p>Pages are never locked, they're swapped in and out as needed.</p></td></tr><tr><td><p><span class="term"><code class="constant">B_LOMEM</code></span></p></td><td><p>This is a special constant that's used for for areas that need to
be locked, contiguous, and that fit within the first 16MB of physical
memory. The folks that need this constant know who they are.</p></td></tr></tbody></table></td></tr><tr><td><p><span class="term"><code class="parameter">protection</code></span></p></td><td><p>Is a mask that describes whether the memory can be written
and read. You form the mask by adding the constants <code class="constant">B_READ_AREA</code> (the
area can be read) and <code class="constant">B_WRITE_AREA</code> (it can be written). The protection
you describe applies only to this area. If your area is cloned, the
clone can specify a different protection.</p></td></tr></tbody></table><p>If <code class="function">create_area()</code> is successful, the new area_id number is returned. If
it's unsuccessful, one of the following error constants is returned.</p><table class="variablelist returncodes"><thead><tr><th>Return Code</th><th>Description</th></tr></thead><tbody><tr><td><p><span class="term"><code class="constant">B_BAD_VALUE</code>.</span></p></td><td><p>Bad argument value. You passed an unrecognized constant
for <code class="parameter">addr_spec</code> or <code class="parameter">lock</code>,
the <code class="parameter">addr</code> or <code class="parameter">size</code> value isn't a multiple of
<code class="constant">B_PAGE_SIZE</code>, or you set <code class="parameter">addr_spec</code>
to <code class="constant">B_EXACT_ADDRESS</code> but the address
request couldn't be fulfilled.</p></td></tr><tr><td><p><span class="term"><code class="constant">B_NO_MEMORY</code>.</span></p></td><td><p>Not enough memory to allocate the system structures that
support this area (unlikely), not enough physical memory to support a
locked area, or not enough swap space to allocate virtual memory (in
other words, size is too big.)</p></td></tr><tr><td><p><span class="term"><code class="constant">B_ERROR</code>.</span></p></td><td><p>Some other system error prevented the area from being
created.</p></td></tr></tbody></table></div><div class="section"><div xmlns="" xmlns:d="http://docbook.org/ns/docbook" class="titlepage"><div><div xmlns:d="http://docbook.org/ns/docbook"><h4 xmlns="http://www.w3.org/1999/xhtml" class="title"><a id="delete_area"></a>delete_area()</h4></div></div></div><a id="id1100231" class="indexterm"></a><code class="methodsynopsis c"><span class="type">status_t </span><span class="methodname">delete_area</span>(<span class="methodparam"><span class="type">area_id </span><span class="parameter">area</span></span>);</code><p>Deletes the designated area. If no one other area maps to the physical
memory that this area represents, the memory is freed. After being
deleted, the <code class="parameter">area</code> value is invalid as an area identifier.</p><div class="admonition warning"><div class="title">Warning</div><div class="graphic"><img class="icon" alt="Warning" width="32" src="./images/admonitions/Stop_32.png" /><div class="text"><p>Currently, anybody can delete any area—the act isn't denied if,
for example, the <span class="type">area_id</span> argument was created by another application.
This freedom will be rescinded in a later release. Until then, try to
avoid deleting other application's areas.</p></div></div></div><table class="variablelist returncodes"><thead><tr><th>Return Code</th><th>Description</th></tr></thead><tbody><tr><td><p><span class="term"><code class="constant">B_OK</code>.</span></p></td><td><p>The area was deleted; <code class="parameter">area</code> is now invalid.</p></td></tr><tr><td><p><span class="term"><code class="constant">B_ERROR</code>.</span></p></td><td><p><code class="parameter">area</code> doesn't designate an actual area.</p></td></tr></tbody></table></div><div class="section"><div xmlns="" xmlns:d="http://docbook.org/ns/docbook" class="titlepage"><div><div xmlns:d="http://docbook.org/ns/docbook"><h4 xmlns="http://www.w3.org/1999/xhtml" class="title"><a id="find_area"></a>find_area()</h4></div></div></div><a id="id1100342" class="indexterm"></a><code class="methodsynopsis c"><span class="type">area_id </span><span class="methodname">find_area</span>(<span class="methodparam"><span class="type">const char* </span><span class="parameter">name</span></span>);</code><p>Returns an area that has a name that matches the argument. Area names
needn't be unique—successive calls to this function with the same
argument value may not return the same <span class="type">area_id</span>.</p><p>What you do with the area you've found depends on where it came from:</p><ul class="itemizedlist"><li><p>If you're finding an area that your own application created or
cloned, you can use the returned ID directly.</p></li><li><p>If the area was created or cloned by some other application, you
should immediately clone the area (unless you're doing something truly
innocuous, such as simply examining the area's info structure).</p></li></ul><table class="variablelist returncodes"><thead><tr><th>Return Code</th><th>Description</th></tr></thead><tbody><tr><td><p><span class="term"><code class="constant">B_NAME_NOT_FOUND</code>.</span></p></td><td><p>The argument doesn't identify an existing area.</p></td></tr></tbody></table><p>See also:
<a class="link" href="TheKernelKit_Areas.html#area_for" title="area_for()"><code class="function">area_for()</code></a></p></div><div class="section"><div xmlns="" xmlns:d="http://docbook.org/ns/docbook" class="titlepage"><div><div xmlns:d="http://docbook.org/ns/docbook"><h4 xmlns="http://www.w3.org/1999/xhtml" class="title"><a id="get_area_info"></a><a id="get_next_area_info"></a>
<a id="area_info"></a>
get_area_info(), get_next_area_info(), area_info</h4></div></div></div><a id="id1100462" class="indexterm"></a><a id="id1100469" class="indexterm"></a><a id="id1100476" class="indexterm"></a><code class="methodsynopsis c"><span class="type">status_t </span><span class="methodname">get_area_info</span>(<span class="methodparam"><span class="type">area_id </span><span class="parameter">area</span></span>,<br />                       <span class="methodparam"><span class="type">area_info* </span><span class="parameter">info</span></span>);</code><code class="methodsynopsis c"><span class="type">status_t </span><span class="methodname">get_next_area_info</span>(<span class="methodparam"><span class="type">team_id </span><span class="parameter">team</span></span>,<br />                            <span class="methodparam"><span class="type">int32* </span><span class="parameter">cookie</span></span>,<br />                            <span class="methodparam"><span class="type">area_info* </span><span class="parameter">info</span></span>);</code><pre class="programlisting definition c">struct {} <span class="type">area_info</span></pre><p>Copies information about a particular area into the <span class="type">area_info</span> structure
designated by <code class="parameter">info</code>. The first version of the function designates the area
directly, by <span class="type">area_id</span>.</p><p>The <code class="function">get_next_area_info()</code> version lets you step through the list of a
team's areas through iterated calls on the function. The <code class="parameter">team</code> argument
identifies the team you want to look at; a <code class="parameter">team</code> value of 0 means the team
of the calling thread. The <code class="parameter">cookie</code> argument is a placemark; you set it to
0 on your first call, and let the function do the rest. The function
returns <code class="constant">B_BAD_VALUE</code> when there are no more areas to visit:</p><pre class="programlisting example c"><span class="comment">/* Get the area_info for every area in this team. */</span>
<span class="type">area_info</span> <code class="varname">info</code>;
<span class="type">int32</span> <code class="varname">cookie</code> = 0;
while (<code class="function">get_next_area_info</code>(0, &amp;<code class="varname">cookie</code>, &amp;<code class="varname">info</code>) == <code class="constant">B_OK</code>)
...</pre><p>The <span class="type">area_info</span> structure is:</p><pre class="programlisting definition c">typedef struct area_info {
<span class="type">area_id</span> <code class="varname">area</code>;
<span class="type">char</span> <code class="varname">name</code>[<code class="constant">B_OS_NAME_LENGTH</code>];
<span class="type">size_t</span> <code class="varname">size</code>;
<span class="type">uint32</span> <code class="varname">lock</code>;
<span class="type">uint32</span> <code class="varname">protection</code>;
<span class="type">team_id</span> <code class="varname">team</code>;
<span class="type">size_t</span> <code class="varname">ram_size</code>;
<span class="type">uint32</span> <code class="varname">copy_count</code>;
<span class="type">uint32</span> <code class="varname">in_count</code>;
<span class="type">uint32</span> <code class="varname">out_count</code>;
<span class="type">void*</span> <code class="varname">address</code>;
} <span class="type">area_info</span>;</pre><p>The fields are:</p><table class="variablelist fields"><thead><tr><th>Field</th><th>Description</th></tr></thead><tbody><tr><td><p><span class="term"><code class="varname">area</code></span></p></td><td><p>Is the <span class="type">area_id</span> that identifies the area.</p></td></tr><tr><td><p><span class="term"><code class="varname">name</code></span></p></td><td><p>Is the name that was assigned to the area when it was created or
cloned.</p></td></tr><tr><td><p><span class="term"><code class="varname">size</code></span></p></td><td><p>Is the (virtual) size of the area, in bytes.</p></td></tr><tr><td><p><span class="term"><code class="varname">lock</code></span></p></td><td><p>Is a constant that represents the area's locking scheme. This
will be one of <code class="constant">B_FULL_LOCK</code>, <code class="constant">B_CONTIGUOUS</code>,
<code class="constant">B_LAZY_LOCK</code>, <code class="constant">B_NO_LOCK</code>, or
<code class="constant">B_LOMEM</code>.</p></td></tr><tr><td><p><span class="term"><code class="varname">protection</code></span></p></td><td><p>Specifies whether the area's memory can be read or
written. It's a combination of <code class="constant">B_READ_AREA</code>
and <code class="constant">B_WRITE_AREA</code>.</p></td></tr><tr><td><p><span class="term"><code class="varname">team</code></span></p></td><td><p>Is the <span class="type">team_id</span> of the team that created or cloned this area.</p></td></tr><tr><td><p><span class="term"><code class="varname">address</code></span></p></td><td><p>Is a pointer to the area's starting address. Keep in mind
that this address is only meaningful to the team that created (or
cloned) the area.</p></td></tr></tbody></table><p>The final four fields give information about the area that's useful in
diagnosing system use. The fields are particularly valuable if you're
hunting for memory leaks:</p><table class="variablelist fields"><thead><tr><th>Field</th><th>Description</th></tr></thead><tbody><tr><td><p><span class="term"><code class="varname">ram_size</code></span></p></td><td><p>Gives the amount of the area, in bytes, that's currently
swapped in.</p></td></tr><tr><td><p><span class="term"><code class="varname">copy_count</code></span></p></td><td><p>Is a "copy-on write" count that can be ignored—it
doesn't apply to the areas that you create. The system can create
copy-on-write areas (it does so when it loads the data section of an
executable, for example), but you can't.</p></td></tr><tr><td><p><span class="term"><code class="varname">in_count</code></span></p></td><td><p>Is a count of the total number of times any of the pages in
the area have been swapped in.</p></td></tr><tr><td><p><span class="term"><code class="varname">out_count</code></span></p></td><td><p>Is a count of the total number of times any of the pages in
the area have been swapped out.</p></td></tr></tbody></table><table class="variablelist returncodes"><thead><tr><th>Return Code</th><th>Description</th></tr></thead><tbody><tr><td><p><span class="term"><code class="constant">B_OK</code>.</span></p></td><td>
The area was found; <code class="parameter">info</code> contains valid information.
</td></tr><tr><td><p><span class="term"><code class="constant">B_BAD_VALUE</code>.</span></p></td><td><code class="parameter">area</code> doesn't identify an existing area,
<code class="parameter">team</code> doesn't
identify an existing team, or there are no more areas to visit.
</td></tr></tbody></table></div><div class="section"><div xmlns="" xmlns:d="http://docbook.org/ns/docbook" class="titlepage"><div><div xmlns:d="http://docbook.org/ns/docbook"><h4 xmlns="http://www.w3.org/1999/xhtml" class="title"><a id="resize_area"></a>resize_area()</h4></div></div></div><a id="id1101330" class="indexterm"></a><code class="methodsynopsis c"><span class="type">status_t </span><span class="methodname">resize_area</span>(<span class="methodparam"><span class="type">area_id </span><span class="parameter">area</span></span>,<br />                     <span class="methodparam"><span class="type">size_t </span><span class="parameter">new_size</span></span>);</code><p>Sets the size of the designated area to <code class="parameter">new_size</code>, measured in bytes. The
<code class="parameter">new_size</code> argument must be a multiple of
<code class="constant">B_PAGE_SIZE</code> (4096).</p><p>Size modifications affect the end of the area's existing memory
allocation: If you're increasing the size of the area, the new memory is
added to the end of area; if you're shrinking the area, end pages are
released and freed. In neither case does the area's starting address
change, nor is existing data modified (except, of course, for data that's
lost due to shrinkage).</p><p>Resizing affects all areas that refer to this areas physical memory. For
example, if B is a clone of A, and you resize A, B will be automatically
resized (if possible).</p><table class="variablelist returncodes"><thead><tr><th>Return Code</th><th>Description</th></tr></thead><tbody><tr><td><p><span class="term"><code class="constant">B_OK</code>.</span></p></td><td><p>The area was successfully resized.</p></td></tr><tr><td><p><span class="term"><code class="constant">B_BAD_VALUE</code>.</span></p></td><td><p><code class="parameter">area</code> doesn't signify a valid area,
or <code class="parameter">new_size</code> isn't a
multiple of <code class="constant">B_PAGE_SIZE</code>.</p></td></tr><tr><td><p><span class="term"><code class="constant">B_NO_MEMORY</code>.</span></p></td><td><p>Not enough memory to support the new portion of the
area. This should only happen if you're increasing the size of the area.</p></td></tr><tr><td><p><span class="term"><code class="constant">B_ERROR</code>.</span></p></td><td><p>Some other system error prevented the area from being
created.</p></td></tr></tbody></table></div><div class="section"><div xmlns="" xmlns:d="http://docbook.org/ns/docbook" class="titlepage"><div><div xmlns:d="http://docbook.org/ns/docbook"><h4 xmlns="http://www.w3.org/1999/xhtml" class="title"><a id="set_area_protection"></a>set_area_protection()</h4></div></div></div><a id="id1101499" class="indexterm"></a><code class="methodsynopsis c"><span class="type">status_t </span><span class="methodname">set_area_protection</span>(<span class="methodparam"><span class="type">area_id </span><span class="parameter">area</span></span>,<br />                             <span class="methodparam"><span class="type">uint32 </span><span class="parameter">new_protection</span></span>);</code><p>Sets the given area's read and write protection. The new_protection
argument is a mask that specifies one or both of the values <code class="constant">B_READ_AREA</code>
and <code class="constant">B_WRITE_AREA</code>. The former means that the area can be read; the latter,
that it can be written to. An area's protection only applies to access to
the underlying memory through that specific area. Different area clones
that refer to the same memory may have different protections.</p><table class="variablelist returncodes"><thead><tr><th>Return Code</th><th>Description</th></tr></thead><tbody><tr><td><p><span class="term"><code class="constant">B_OK</code>.</span></p></td><td>
The protection was changed.
</td></tr><tr><td><p><span class="term"><code class="constant">B_BAD_VALUE</code>.</span></p></td><td><code class="parameter">area</code> doesn't identify a valid area.
</td></tr></tbody></table></div></div></div><div id="footer"><hr /><div id="footerT">Prev: <a href="TheKernelKit.html">The Kernel Kit</a>  Up: <a href="TheKernelKit.html">The Kernel Kit</a>  Next: <a href="TheKernelKit_Images.html">Images</a> </div><div id="footerB"><div id="footerBL"><a href="TheKernelKit.html" title="The Kernel Kit"><img src="./images/navigation/prev.png" alt="Prev" /></a> <a href="TheKernelKit.html" title="The Kernel Kit"><img src="./images/navigation/up.png" alt="Up" /></a> <a href="TheKernelKit_Images.html" title="Images"><img src="./images/navigation/next.png" alt="Next" /></a></div><div id="footerBR"><div><a href="http://www.haiku-os.org"><img src="./images/People_24.png" alt="haiku-os.org" title="Visit The Haiku Website" /></a></div><div class="navighome" title="Home"><a accesskey="h" href="index.html"><img src="./images/navigation/home.png" alt="Home" /></a></div></div><div id="footerBC"><a href="http://www.access-company.com/home.html" title="ACCESS Co."><img alt="Access Company" src="./images/access_logo.png" /></a></div></div></div><div id="licenseFooter"><div id="licenseFooterBL"><a rel="license" href="http://creativecommons.org/licenses/by-nc-nd/3.0/" title="Creative Commons License"><img alt="Creative Commons License" style="border-width:0" src="https://licensebuttons.net/l/by-nc-nd/3.0/88x31.png" /></a></div><div id="licenseFooterBR"><a href="./LegalNotice.html">Legal Notice</a></div><div id="licenseFooterBC"><span id="licenseText">This work is licensed under a
<a rel="license" href="http://creativecommons.org/licenses/by-nc-nd/3.0/">Creative
Commons Attribution-Non commercial-No Derivative Works 3.0 License</a>.</span></div></div></body></html>
Reference in New Issue View Git Blame Copy Permalink