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

163 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_Images.html" title="Images" /><link rel="next" href="TheKernelKit_Semaphores.html" title="Semaphores" /></head><body><div id="header"><div id="headerT"><div id="headerTL"><a accesskey="p" href="TheKernelKit_Images.html" title="Images"><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_Semaphores.html" title="Semaphores"><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_Images.html">Images</a>  Up: <a href="TheKernelKit.html">The Kernel Kit</a>  Next: <a href="TheKernelKit_Semaphores.html">Semaphores</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_Ports"></a>Ports</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>A port is a system-wide message repository into which any thread can copy
a buffer of data, and from which any thread can then retrieve the buffer.
This repository is implemented as a first-in/first-out message queue: A
port stores its messages in the order in which they're received, and it
relinquishes them in the order in which they're stored. Each port has its
own message queue.</p><p>Ports are largely subsumed by the Application Kit's
<a class="link" href="BMessage.html" title="BMessage"><code class="classname">BMessage</code></a> class (and
relatives). The two features of ports that you can't get at the
<a class="link" href="BMessage.html" title="BMessage"><code class="classname">BMessage</code></a>
level are:</p><ul class="itemizedlist"><li><p>Ports let you set the length of the message queue.</p></li><li><p>Ports can be used in C code (as opposed to C++).</p></li></ul><p>For most applications, these are inessential additions.</p><p>For more information on ports, see
"<a class="link" href="TheKernelKit_Ports_Overview.html" title="Ports">Ports Overview</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="Ports_PortFunctions"></a>Port 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="create_port"></a>create_port()</h4></div></div></div><a id="id1103363" class="indexterm"></a><code class="methodsynopsis c"><span class="type">port_id </span><span class="methodname">create_port</span>(<span class="methodparam"><span class="type">int32 </span><span class="parameter">queue_length</span></span>,<br />                    <span class="methodparam"><span class="type">const char* </span><span class="parameter">name</span></span>);</code><p>Creates a new port and returns its <span class="type">port_id</span> number. The port's name is set
to <code class="parameter">name</code> and the length of its message queue is set to <code class="parameter">queue_length</code>.
Neither the name nor the queue length can be changed once they're set.
The name shouldn't exceed <code class="constant">B_OS_NAME_LENGTH</code> (32) characters.</p><p>In setting the length of a port's message queue, you're telling it how
many messages it can hold at a time. When the queue is filled—when
it's holding queue_length messages—subsequent invocations of
<a class="link" href="TheKernelKit_Ports.html#write_port" title="write_port(), write_port_etc()"><code class="function">write_port()</code></a>
(on that port) block until room is made in the queue (through calls to
<a class="link" href="TheKernelKit_Ports.html#read_port" title="read_port(), read_port_etc()"><code class="function">read_port()</code></a>)
for the additional messages. Once the queue length is set by
<code class="function">create_port()</code>, it can't be changed.</p><p>This function sets the owner of the port to be the team of the calling
thread. Ownership can subsequently be transferred through the
<a class="link" href="TheKernelKit_Ports.html#set_port_owner" title="set_port_owner()"><code class="function">set_port_owner()</code></a>
function. When a port's owner dies (when all the threads
in the team are dead), the port is automatically deleted. If you want to
delete a port prior to its owner's death, use the
<a class="link" href="TheKernelKit_Ports.html#delete_port" title="delete_port()"><code class="function">delete_port()</code></a>
function.</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><code class="parameter">queue_length</code> is too big or less than zero.</p></td></tr><tr><td><p><span class="term"><code class="constant">B_NO_MORE_PORTS</code>.</span></p></td><td><p>The system couldn't allocate another port.</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="close_port"></a>close_port()</h4></div></div></div><a id="id1103524" class="indexterm"></a><code class="methodsynopsis c"><span class="type">status_t </span><span class="methodname">close_port</span>(<span class="methodparam"><span class="type">port_id </span><span class="parameter">port</span></span>);</code><p>Closes the port so no more messages can be written to it. After you close
a port, you can call
<a class="link" href="TheKernelKit_Ports.html#read_port" title="read_port(), read_port_etc()"><code class="function">read_port()</code></a>
on it, but a
<a class="link" href="TheKernelKit_Ports.html#write_port" title="write_port(), write_port_etc()"><code class="function">write_port()</code></a>
call will return <code class="constant">B_BAD_PORT_ID</code>. You can't reopen a closed port; you call this
function so you can read through a port's unread messages prior to
deleting the port, while ensuring that no new messages will show up.
After you've read the messages, you should call
<a class="link" href="TheKernelKit_Ports.html#delete_port" title="delete_port()"><code class="function">delete_port()</code></a>
on <code class="parameter">port</code>.</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><code class="parameter">port</code> is now closed.</p></td></tr><tr><td><p><span class="term"><code class="constant">B_BAD_PORT_ID</code>.</span></p></td><td><p><code class="parameter">port</code> doesn't identify an open port.</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_port"></a>delete_port()</h4></div></div></div><a id="id1103646" class="indexterm"></a><code class="methodsynopsis c"><span class="type">status_t </span><span class="methodname">delete_port</span>(<span class="methodparam"><span class="type">port_id </span><span class="parameter">port</span></span>);</code><p>Deletes the given <code class="parameter">port</code>. The port's message queue doesn't have to be
empty—you can delete a port that's holding unread messages. Threads
that are blocked in
<a class="link" href="TheKernelKit_Ports.html#read_port" title="read_port(), read_port_etc()"><code class="function">read_port()</code></a>
or
<a class="link" href="TheKernelKit_Ports.html#write_port" title="write_port(), write_port_etc()"><code class="function">write_port()</code></a>
calls on the port are
automatically unblocked (and return <code class="constant">B_BAD_SEM_ID</code>).</p><p>The thread that calls <code class="function">delete_port()</code> doesn't have to be a member of the
team that owns the port; any thread can delete any port.</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 port was deleted.</p></td></tr><tr><td><p><span class="term"><code class="constant">B_BAD_PORT_ID</code>.</span></p></td><td><p><code class="parameter">port</code> isn't a valid port.</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_port"></a>find_port()</h4></div></div></div><a id="id1103765" class="indexterm"></a><code class="methodsynopsis c"><span class="type">port_id </span><span class="methodname">find_port</span>(<span class="methodparam"><span class="modifier">const </span><span class="type">char* </span><span class="parameter">port_name</span></span>);</code><p>Returns the <span class="type">port_id</span> of the named port.
<code class="parameter">port_name</code> should be no longer than
32 characters (<code class="constant">B_OS_NAME_LENGTH</code>).</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_NAME_NOT_FOUND</code>.</span></p></td><td><p><code class="parameter">port_name</code> doesn't name an existing port.</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="get_port_info"></a><a id="get_next_port_info"></a>
get_port_info(), get_next_port_info()</h4></div></div></div><a id="id1103853" class="indexterm"></a><a id="id1103860" class="indexterm"></a><code class="methodsynopsis c"><span class="type">status_t </span><span class="methodname">get_port_info</span>(<span class="methodparam"><span class="type">port_id </span><span class="parameter">port</span></span>,<br />                       <span class="methodparam"><span class="type">port_info* </span><span class="parameter">info</span></span>);</code><code class="methodsynopsis c"><span class="type">status_t </span><span class="methodname">get_next_port_info</span>(<span class="methodparam"><span class="type">team_id </span><span class="parameter">team</span></span>,<br />                            <span class="methodparam"><span class="type">uint32* </span><span class="parameter">cookie</span></span>,<br />                            <span class="methodparam"><span class="type">port_info* </span><span class="parameter">info</span></span>);</code><p>Copies information about a particular <code class="parameter">port</code>
into the <span class="type">port_info</span> structure
designated by <code class="parameter">info</code>. The first version of the function designates the port
directly, by <span class="type">port_id</span>.</p><p>The <code class="function">get_next_port_info()</code> version lets you step through the list of a
team's ports 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 ports to visit:</p><pre class="programlisting example c"><span class="comment">/* Get the port_info for every port in this team. */</span>
<span class="type">port_info</span> <code class="varname">info</code>;
<span class="type">int32</span> <code class="varname">cookie</code> = 0;
while (<code class="function">get_next_port_info</code>(0, &amp;<code class="varname">cookie</code>, &amp;<code class="varname">info</code>) == <code class="constant">B_OK</code>)
...</pre><p>The information in the <span class="type">port_info</span> structure is guaranteed to be internally
consistent, but the structure as a whole should be considered to be
out-of-date as soon as you receive it. It provides a picture of a port as
it exists just before the info-retrieving function returns.</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 port was found; <code class="parameter">info</code> contains valid information.</p></td></tr><tr><td><p><span class="term"><code class="constant">B_BAD_VALUE</code>.</span></p></td><td><p><code class="parameter">port</code> doesn't identify an existing port,
<code class="parameter">team</code> doesn't
identify an existing team, or there are no more ports to visit.</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="port_buffer_size"></a><a id="port_buffer_size_etc"></a>
port_buffer_size(), port_buffer_size_etc()</h4></div></div></div><a id="id1104107" class="indexterm"></a><a id="id1104114" class="indexterm"></a><code class="methodsynopsis c"><span class="type">ssize_t </span><span class="methodname">port_buffer_size</span>(<span class="methodparam"><span class="type">port_id </span><span class="parameter">port</span></span>);</code><code class="methodsynopsis c"><span class="type">ssize_t </span><span class="methodname">port_buffer_size_etc</span>(<span class="methodparam"><span class="type">port_id </span><span class="parameter">port</span></span>,<br />                             <span class="methodparam"><span class="type">uint32 </span><span class="parameter">flags</span></span>,<br />                             <span class="methodparam"><span class="type">bigtime_t </span><span class="parameter">timeout</span></span>);</code><p>These functions return the length (in bytes) of the message buffer that's
at the head of port's message queue. You call this function in order to
allocate a sufficiently large buffer in which to retrieve the message
data.</p><p>The <code class="function">port_buffer_size()</code> function blocks if the port is currently empty. It
unblocks when a
<a class="link" href="TheKernelKit_Ports.html#write_port" title="write_port(), write_port_etc()"><code class="function">write_port()</code></a>
call gives this function a buffer to measure
(even if the buffer is 0 bytes long), or when the port is deleted.</p><p>The <code class="function">port_buffer_size_etc()</code> function lets you set a limit on the amount of
time the function will wait for a message to show up. To set the limit,
you pass <code class="constant">B_TIMEOUT</code> as the flags argument, and set timeout to the amount
of time, in microseconds, that you're willing to wait.</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_PORT_ID</code>.</span></p></td><td><p>port doesn't identify an existing port, or the port
was deleted while the function was blocked.</p></td></tr><tr><td><p><span class="term"><code class="constant">B_TIMED_OUT</code>.</span></p></td><td><p>The timeout limit expired.</p></td></tr><tr><td><p><span class="term"><code class="constant">B_WOULD_BLOCK</code></span></p></td><td><p>You asked for a timeout of 0, but there are no
messages in the queue.</p></td></tr></tbody></table><p>See also:
<a class="link" href="TheKernelKit_Ports.html#read_port" title="read_port(), read_port_etc()"><code class="function">read_port()</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="port_count"></a>port_count()</h4></div></div></div><a id="id1104301" class="indexterm"></a><code class="methodsynopsis c"><span class="type">int32 </span><span class="methodname">port_count</span>(<span class="methodparam"><span class="type">port_id </span><span class="parameter">port</span></span>);</code><p>Returns the number of messages that are currently in port's message
queue. This is the number of messages that have been written to the port
through calls to
<a class="link" href="TheKernelKit_Ports.html#write_port" title="write_port(), write_port_etc()"><code class="function">write_port()</code></a>
but that haven't yet been picked up through corresponding
<a class="link" href="TheKernelKit_Ports.html#read_port" title="read_port(), read_port_etc()"><code class="function">read_port()</code></a>
calls.</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>This function is provided mostly as a convenience and a semi-accurate
debugging tool. The value that it returns is inherently undependable:
There's no guarantee that additional
<a class="link" href="TheKernelKit_Ports.html#read_port" title="read_port(), read_port_etc()"><code class="function">read_port()</code></a> or
<a class="link" href="TheKernelKit_Ports.html#write_port" title="write_port(), write_port_etc()"><code class="function">write_port()</code></a>
calls won't change the count as this function is returning.</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_BAD_PORT_ID</code></span></p></td><td><p><code class="parameter">port</code> doesn't identify an existing port.</p></td></tr></tbody></table><p>See also:
<a class="link" href="TheKernelKit_Ports.html#get_port_info" title="get_port_info(), get_next_port_info()"><code class="function">get_port_info()</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="read_port"></a><a id="read_port_etc"></a>
read_port(), read_port_etc()</h4></div></div></div><a id="id1104423" class="indexterm"></a><a id="id1104430" class="indexterm"></a><code class="methodsynopsis c"><span class="type">ssize_t </span><span class="methodname">read_port</span>(<span class="methodparam"><span class="type">port_id </span><span class="parameter">port</span></span>,<br />                  <span class="methodparam"><span class="type">int32* </span><span class="parameter">msg_code</span></span>,<br />                  <span class="methodparam"><span class="type">void* </span><span class="parameter">msg_buffer</span></span>,<br />                  <span class="methodparam"><span class="type">size_t </span><span class="parameter">buffer_size</span></span>);</code><code class="methodsynopsis c"><span class="type">ssize_t </span><span class="methodname">read_port_etc</span>(<span class="methodparam"><span class="type">port_id </span><span class="parameter">port</span></span>,<br />                      <span class="methodparam"><span class="type">int32* </span><span class="parameter">msg_code</span></span>,<br />                      <span class="methodparam"><span class="type">void* </span><span class="parameter">msg_buffer</span></span>,<br />                      <span class="methodparam"><span class="type">size_t </span><span class="parameter">buffer_size</span></span>,<br />                      <span class="methodparam"><span class="type">uint32 </span><span class="parameter">flags</span></span>,<br />                      <span class="methodparam"><span class="type">bigtime_t </span><span class="parameter">timeout</span></span>);</code><p>These functions remove the message at the head of <code class="parameter">port</code>'s message queue
and copy the messages's contents into the <code class="parameter">msg_code</code> and <code class="parameter">msg_buffer</code>
arguments. The size of the <code class="parameter">msg_buffer</code> buffer, in bytes, is given by
<code class="parameter">buffer_size</code>. It's up to the caller to ensure that the message buffer is
large enough to accommodate the message that's being read. If you want a
hint about the message's size, you should call
<a class="link" href="TheKernelKit_Ports.html#port_buffer_size" title="port_buffer_size(), port_buffer_size_etc()"><code class="function">port_buffer_size()</code></a>
before calling this function.</p><p>If <code class="parameter">port</code>'s message queue is empty
when you call <code class="function">read_port()</code>, the function
will block. It returns when some other thread writes a message to the
port through
<a class="link" href="TheKernelKit_Ports.html#write_port" title="write_port(), write_port_etc()"><code class="function">write_port()</code></a>.
A blocked read is also unblocked if the port is deleted.</p><p>The <code class="function">read_port_etc()</code> function lets you set a limit on the amount of time
the function will wait for a message to show up. To set the limit, you
pass <code class="constant">B_TIMEOUT</code> as the <code class="parameter">flags</code>
argument, and set timeout to the amount of
time, in microseconds, that you're willing to wait.</p><p>A successful call returns the number of bytes that were written into the
<code class="parameter">msg_buffer</code> argument.</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_PORT_ID</code>.</span></p></td><td><p><code class="parameter">port</code> doesn't identify an existing port, or the port
was deleted while the function was blocked.</p></td></tr><tr><td><p><span class="term"><code class="constant">B_TIMED_OUT</code>.</span></p></td><td><p>The timeout limit expired.</p></td></tr><tr><td><p><span class="term"><code class="constant">B_WOULD_BLOCK</code>.</span></p></td><td><p>You asked for a timeout of 0, but there are no
messages in the queue.</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_port_owner"></a>set_port_owner()</h4></div></div></div><a id="id1104705" class="indexterm"></a><code class="methodsynopsis c"><span class="type">status_t </span><span class="methodname">set_port_owner</span>(<span class="methodparam"><span class="type">port_id </span><span class="parameter">port</span></span>,<br />                        <span class="methodparam"><span class="type">team_id </span><span class="parameter">team</span></span>);</code><p>Transfers ownership of the designated port to team. A port can only be
owned by one team at a time; by setting a port's owner, you remove it
from its current owner.</p><p>There are no restrictions on who can own a port, or on who can transfer
ownership. In other words, the thread that calls <code class="function">set_port_owner()</code> needn't
be part of the team that currently owns the port, nor must you only
assign ports to the team that owns the calling thread (although these two
are the most likely scenarios).</p><p>Port ownership is meaningful for one reason: When a team dies (when all
its threads are dead), the ports that are owned by that team are freed.
Ownership, otherwise, has no significance—it carries no special
privileges or obligations.</p><p>To discover a port's owner, use the
<a class="link" href="TheKernelKit_Ports.html#get_port_info" title="get_port_info(), get_next_port_info()"><code class="function">get_port_info()</code></a>
function.</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>Ownership was successfully transferred.</p></td></tr><tr><td><p><span class="term"><code class="constant">B_BAD_PORT_ID</code>.</span></p></td><td><p><code class="parameter">port</code> doesn't identify a valid port.</p></td></tr><tr><td><p><span class="term"><code class="constant">B_BAD_TEAM_ID</code>.</span></p></td><td><p><code class="parameter">team</code> doesn't identify a valid team.</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="write_port"></a><a id="write_port_etc"></a>
write_port(), write_port_etc()</h4></div></div></div><a id="id1104857" class="indexterm"></a><a id="id1104864" class="indexterm"></a><code class="methodsynopsis c"><span class="type">status_t </span><span class="methodname">write_port</span>(<span class="methodparam"><span class="type">port_id </span><span class="parameter">port</span></span>,<br />                    <span class="methodparam"><span class="type">int32 </span><span class="parameter">msg_code</span></span>,<br />                    <span class="methodparam"><span class="type">void* </span><span class="parameter">msg_buffer</span></span>,<br />                    <span class="methodparam"><span class="type">size_t </span><span class="parameter">buffer_size</span></span>);</code><code class="methodsynopsis c"><span class="type">status_t </span><span class="methodname">write_port_etc</span>(<span class="methodparam"><span class="type">port_id </span><span class="parameter">port</span></span>,<br />                        <span class="methodparam"><span class="type">int32 </span><span class="parameter">msg_code</span></span>,<br />                        <span class="methodparam"><span class="type">void* </span><span class="parameter">msg_buffer</span></span>,<br />                        <span class="methodparam"><span class="type">size_t </span><span class="parameter">buffer_size</span></span>,<br />                        <span class="methodparam"><span class="type">uint32 </span><span class="parameter">flags</span></span>,<br />                        <span class="methodparam"><span class="type">bigtime_t </span><span class="parameter">timeout</span></span>);</code><p>These functions place a message at the tail of port's message queue. The
message consists of <code class="parameter">msg_code</code> and
<code class="parameter">msg_buffer</code>:</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">msg_code</code></span></p></td><td><p>Holds the "message code." This is a mask, flag, or other
predictable value that gives a general representation of the message.</p></td></tr><tr><td><p><span class="term"><code class="parameter">msg_buffer</code></span></p></td><td><p>Is a pointer to a buffer that can be used to supply
additional information. You pass the length of the buffer, in bytes, as
the value of the <code class="parameter">buffer_size</code> argument. The buffer can be arbitrarily
long.</p></td></tr></tbody></table><p>If the port's queue is full when you call <code class="function">write_port()</code>,
the function will block. It returns when a
<a class="link" href="TheKernelKit_Ports.html#read_port" title="read_port(), read_port_etc()"><code class="function">read_port()</code></a>
call frees a slot in the queue for the new message. A blocked
<code class="function">write_port()</code> will also return if the target
port is deleted or closed.</p><p>The <code class="function">write_port_etc()</code> function lets you set a limit on the amount of time
the function will wait for a free queue slot. To set the limit, you pass
<code class="constant">B_TIMEOUT</code> as the <code class="parameter">flags</code>
argument, and set timeout to the amount of time,
in microseconds, that you're willing to wait.</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 port was successully written to.
</td></tr><tr><td><p><span class="term"><code class="constant">B_BAD_PORT_ID</code>.</span></p></td><td><p><code class="parameter">port</code> doesn't identify an open port, or the port was
deleted while the function was blocked.</p></td></tr><tr><td><p><span class="term"><code class="constant">B_TIMED_OUT</code>.</span></p></td><td><p>The timeout limit expired.</p></td></tr><tr><td><p><span class="term"><code class="constant">B_WOULD_BLOCK</code>.</span></p></td><td><p>You asked for a timeout of 0, but there are no free
slots in the message queue.</p></td></tr></tbody></table></div></div><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="Ports_PortStructuresAndConstants"></a>Port Structures and Constants</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="port_info"></a>port_info</h4></div></div></div><a id="id1105177" class="indexterm"></a><pre class="programlisting definition c">struct {
<span class="type">port_id</span> <code class="varname">port</code>;
<span class="type">team_id</span> <code class="varname">team</code>;
<span class="type">char</span> <code class="varname">name</code>[<code class="constant">B_OS_NAME_LENGTH</code>];
<span class="type">int32</span> <code class="varname">capacity</code>;
<span class="type">int32</span> <code class="varname">queue_count</code>;
<span class="type">int32</span> <code class="varname">total_count</code>;
} <span class="type">port_info</span></pre><p>The <span class="type">port_info</span> structure provides information about a port. You retrieve
one of these structures through
<a class="link" href="TheKernelKit_Ports.html#get_port_info" title="get_port_info(), get_next_port_info()"><code class="function">get_port_info()</code></a> or
<a class="link" href="TheKernelKit_Ports.html#get_next_port_info"><code class="function">get_next_port_info()</code></a>.</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">port</code>.</span></p></td><td><p>The port_id number of the port.</p></td></tr><tr><td><p><span class="term"><code class="varname">team</code>.</span></p></td><td><p>The <span class="type">team_id</span> of the port's owner.</p></td></tr><tr><td><p><span class="term"><code class="varname">name</code>.</span></p></td><td><p>The name assigned to the port.</p></td></tr><tr><td><p><span class="term"><code class="varname">capacity</code>.</span></p></td><td><p>The length of the port's message queue.</p></td></tr><tr><td><p><span class="term"><code class="varname">queue_count</code>.</span></p></td><td><p>The number of messages currently in the queue.</p></td></tr><tr><td><p><span class="term"><code class="varname">total_count</code>.</span></p></td><td><p>The total number of message that have been read from
the port.</p></td></tr></tbody></table><p>Note that the <code class="varname">total_count</code> number doesn't
include the messages that are currently in the queue.</p></div></div></div><div id="footer"><hr /><div id="footerT">Prev: <a href="TheKernelKit_Images.html">Images</a>  Up: <a href="TheKernelKit.html">The Kernel Kit</a>  Next: <a href="TheKernelKit_Semaphores.html">Semaphores</a> </div><div id="footerB"><div id="footerBL"><a href="TheKernelKit_Images.html" title="Images"><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_Semaphores.html" title="Semaphores"><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