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

276 lines
43 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.

This file contains Unicode characters that might be confused with other characters. 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 Storage 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="TheStorageKit.html" title="The Storage Kit" /><link rel="prev" href="BDirectory.html" title="BDirectory" /><link rel="next" href="BEntryList.html" title="BEntryList" /></head><body><div id="header"><div id="headerT"><div id="headerTL"><a accesskey="p" href="BDirectory.html" title="BDirectory"><img src="./images/navigation/prev.png" alt="Prev" /></a> <a accesskey="u" href="TheStorageKit.html" title="The Storage Kit"><img src="./images/navigation/up.png" alt="Up" /></a> <a accesskey="n" href="BEntryList.html" title="BEntryList"><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 Storage Kit</div></div><div id="headerB">Prev: <a href="BDirectory.html">BDirectory</a>  Up: <a href="TheStorageKit.html">The Storage Kit</a>  Next: <a href="BEntryList.html">BEntryList</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="BEntry"></a>BEntry</h2></div></div></div><a id="id1228747" class="indexterm"></a><div class="classheader"><table border="0"><colgroup><col /><col /></colgroup><tbody><tr><td><table width="100%" border="0"><colgroup><col /><col /></colgroup><tbody><tr><td>Derived From:</td><td><a class="link" href="BStatable.html" title="BStatable"><code class="classname">BStatable</code></a></td></tr><tr><td>Mix-in Classes:</td><td>None</td></tr><tr><td>Declared In:</td><td><code class="filename">storage/Entry.h</code></td></tr><tr><td>Library:</td><td><code class="filename">libbe.so</code></td></tr><tr><td>Allocation:</td><td>–</td></tr></tbody></table></td><td>
<a class="link overview" href="BEntry_Overview.html" title="BEntry">Class Overview</a>
<div class="toc"><ul><li><span class="section"><a href="BEntry.html#BEntry_ConstructorDestructor">Constructor and Destructor</a></span></li><li><span class="section"><a href="BEntry.html#BEntry_Member_Functions">Member Functions</a></span></li><li><span class="section"><a href="BEntry.html#BEntry_Operators">Operators</a></span></li><li><span class="section"><a href="BEntry.html#BEntry_Functions">Global C Function</a></span></li><li><span class="section"><a href="BEntry.html#BEntry_DefinedTypes">Defined Types</a></span></li></ul></div>
</td></tr></tbody></table></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="BEntry_ConstructorDestructor"></a>Constructor and Destructor</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="BEntry_Constructor"></a>BEntry()</h4></div></div></div><div class="synopsisgroup">
<code class="constructorsynopsis cpp"><span class="methodname">BEntry</span>();</code>
<code class="constructorsynopsis cpp"><span class="methodname">BEntry</span>(<span class="methodparam"><span class="modifier">const </span><span class="type"><a class="link" href="BDirectory.html" title="BDirectory"><code class="classname">BDirectory</code></a>* </span><span class="parameter">dir</span></span>,<br />       <span class="methodparam"><span class="modifier">const </span><span class="type">char* </span><span class="parameter">path</span></span>,<br />       <span class="methodparam"><span class="type">bool </span><span class="parameter">traverse</span><span class="initializer"> = <span class="constant">false</span></span></span>);</code>
<code class="constructorsynopsis cpp"><span class="methodname">BEntry</span>(<span class="methodparam"><span class="modifier">const </span><span class="type">entry_ref* </span><span class="parameter">entry</span></span>,<br />       <span class="methodparam"><span class="type">bool </span><span class="parameter">traverse</span><span class="initializer"> = <span class="constant">false</span></span></span>);</code>
<code class="constructorsynopsis cpp"><span class="methodname">BEntry</span>(<span class="methodparam"><span class="modifier">const </span><span class="type">char* </span><span class="parameter">path</span></span>,<br />       <span class="methodparam"><span class="type">bool </span><span class="parameter">traverse</span><span class="initializer"> = <span class="constant">false</span></span></span>);</code>
<code class="constructorsynopsis cpp"><span class="methodname">BEntry</span>(<span class="methodparam"><span class="modifier">const </span><span class="type">BEntry&amp; </span><span class="parameter">entry</span></span>);</code>
</div><p>
Creates a new <code class="classname">BEntry</code> object that represents the entry described by the
arguments. See the analogous
<a class="link" href="BEntry.html#BEntry_SetTo"><code class="methodname">SetTo()</code></a>
functions for descriptions of the flavorful constructors.
</p><p>
The default constructor does nothing; it should be followed by a call to
<a class="link" href="BEntry.html#BEntry_SetTo"><code class="methodname">SetTo()</code></a>.
</p><p>
The copy constructor points the new object to the entry that's
represented by the argument. The two objects themselves maintain separate
representation of the entry; in other words, they each contain their own
a) file descriptor and b) string to identify the entry's a) directory and
b) name.
</p><p>
To see if the initialization was successful, call
<a class="link" href="BEntry.html#BEntry_InitCheck" title="InitCheck()"><code class="methodname">InitCheck()</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="BEntry_Desctructor"></a>~BEntry</h4></div></div></div><code class="destructorsynopsis cpp"><span class="modifier">virtual </span><span class="methodname">BEntry</span>();</code><p>
Closes the <code class="classname">BEntry</code>'s file descriptor and destroys the
<code class="classname">BEntry</code> object.
</p></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="BEntry_Member_Functions"></a>Member 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="BEntry_Exists"></a>Exists()</h4></div></div></div><code class="methodsynopsis cpp"><span class="type">bool </span><span class="methodname">Exists</span>() <span class="modifier">const</span>;</code><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">true</code></span></p></td><td><p>The entry exists.</p></td></tr><tr><td><p><span class="term"><code class="constant">false</code></span></p></td><td><p>otherwise.</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="BEntry_GetName"></a><a id="BEntry_GetPath"></a>
GetName(), GetPath()</h4></div></div></div><code class="methodsynopsis cpp"><span class="type">status_t </span><span class="methodname">GetName</span>(<span class="methodparam"><span class="type">char* </span><span class="parameter">buffer</span></span>) <span class="modifier">const</span>;</code><code class="methodsynopsis cpp"><span class="type">status_t </span><span class="methodname">GetPath</span>(<span class="methodparam"><span class="type"><a class="link" href="BPath.html" title="BPath"><code class="classname">BPath</code></a>* </span><span class="parameter">path</span></span>) <span class="modifier">const</span>;</code><p>
These functions return the leaf name and full pathname of the <code class="classname">BEntry</code>'s
entry. The arguments must be allocated before they're passed in.
</p><p>
<code class="methodname">GetName()</code> copies the leaf name into <code class="parameter">buffer</code>. The <code class="parameter">buffer</code> must be large
enough to accommodate the name; <code class="constant">B_FILE_NAME_LENGTH</code> is a 100% safe bet:
</p><pre class="programlisting example cpp"><span class="type">char</span> <code class="varname">name</code>[<code class="constant">B_FILE_NAME_LENGTH</code>];
<code class="varname">entry</code>.<code class="methodname">GetName</code>(<code class="varname">name</code>);</pre><p>
If <code class="methodname">GetName()</code> fails, <code class="parameter">*buffer</code> is pointed at <code class="constant">NULL</code>.
</p><p>
<code class="methodname">GetPath()</code> takes the entry's full pathname and initializes the
<a class="link" href="BPath.html" title="BPath"><code class="classname">BPath</code></a>
argument with it. To retrieve the path from the
<a class="link" href="BPath.html" title="BPath"><code class="classname">BPath</code></a> object, call
<a class="link" href="BPath.html#BPath_Path" title="Path(), Leaf()"><code class="methodname">BPath::Path()</code></a>:
</p><pre class="programlisting example cpp"><code class="classname">BPath</code> <code class="varname">path</code>;
<code class="varname">entry</code>.<code class="methodname">GetPath</code>(&amp;<code class="varname">path</code>);
<code class="function">printf</code>("&gt;Entry pathname: %sn", <code class="varname">path</code>.<code class="methodname">Path()</code>);</pre><p>
If <code class="methodname">GetPath()</code> fails, the argument is
<a class="link" href="BEntry.html#BEntry_Unset" title="SetTo(), Unset()"><code class="methodname">Unset()</code></a>.
</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 information was successfully retrieved.</p></td></tr><tr><td><p><span class="term"><code class="constant">B_NO_INIT</code>.</span></p></td><td><p>The <code class="classname">BEntry</code> isn't initialized.</p></td></tr><tr><td><p><span class="term"><code class="constant">B_BUSY</code></span></p></td><td><p>(<code class="methodname">GetPath()</code> only). A directory in the entry's path is locked.</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="BEntry_GetParent"></a>GetParent()</h4></div></div></div><div class="synopsisgroup">
<code class="methodsynopsis cpp"><span class="type">status_t </span><span class="methodname">GetParent</span>(<span class="methodparam"><span class="type">BEntry* </span><span class="parameter">entry</span></span>) <span class="modifier">const</span>;</code>
<code class="methodsynopsis cpp"><span class="type">status_t </span><span class="methodname">GetParent</span>(<span class="methodparam"><span class="type"><a class="link" href="BDirectory.html" title="BDirectory"><code class="classname">BDirectory</code></a>* </span><span class="parameter">dir</span></span>) <span class="modifier">const</span>;</code>
</div><p>
Gets the directory, as a <code class="classname">BEntry</code> or
<a class="link" href="BDirectory.html" title="BDirectory"><code class="classname">BDirectory</code></a> object, in which the
object's entry lives. The argument must be allocated before it's passed
in.
</p><p>
If the function is unsuccessful, the argument is
<a class="link" href="BEntry.html#BEntry_Unset" title="SetTo(), Unset()"><code class="methodname">Unset()</code></a>. Because of
this, you should be particularly careful if you're using the
<code class="classname">BEntry</code>-argument version to destructively get a
<code class="classname">BEntry</code>'s parent:
</p><pre class="programlisting example cpp">if (<code class="varname">entry</code>.<code class="methodname">GetParent</code>(&amp;<code class="varname">entry</code>) != <code class="constant">B_OK</code>) {
<span class="comment">/* you just lost 'entry' */</span>
}</pre><p>
This example <span class="emphasis"><em>is</em></span> legal; for example, you can use destructive iteration to
loop your way up to the root directory. When you reach the root ("/"),
<code class="methodname">GetParent()</code> returns <code class="constant">B_ENTRY_NOT_FOUND</code>:
</p><pre class="programlisting example cpp"><code class="classname">BEntry</code> <code class="varname">entry</code>("/boot/home/fido");
<span class="type">status_t</span> <code class="varname">err</code>;
<span class="type">char</span> <code class="varname">name</code>[<code class="constant">B_FILE_NAME_LENGTH</code>];
<span class="comment">/* Spit out the path components backwards, one at a time. */</span>
do {
<code class="varname">entry</code>.<code class="methodname">GetName</code>(<code class="varname">name</code>);
<code class="function">printf</code>("&gt; %sn", <code class="varname">name</code>);
} while ((<code class="varname">err</code>=<code class="varname">entry</code>.<code class="methodname">GetParent</code>(&amp;<code class="varname">entry</code>)) == <code class="constant">B_OK</code>);
<span class="comment">/* Complain for reasons other than reaching the top. */</span>
if (<code class="varname">err</code> != <code class="constant">B_ENTRY_NOT_FOUND</code>)
<code class="function">printf</code>("&gt;&gt; Error: %sn", <code class="function">strerror</code>(<code class="varname">err</code>));</pre><p>
This produces:
</p><pre class="screen">
&gt; fido
&gt; home
&gt; boot
&gt; /
</pre><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 information was successfully retrieved.</p></td></tr><tr><td><p><span class="term"><code class="constant">B_NO_INIT</code>.</span></p></td><td><p>This <code class="classname">BEntry</code> isn't initialized.</p></td></tr><tr><td><p><span class="term"><code class="constant">B_ENTRY_NOT_FOUND</code>.</span></p></td><td><p>Attempt to get the parent of the root directory.</p></td></tr><tr><td><p><span class="term"><code class="constant">B_NO_MORE_FDS</code>.</span></p></td><td><p>Couldn't get another file descriptor.</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="BEntry_GetRef"></a>GetRef()</h4></div></div></div><code class="methodsynopsis cpp"><span class="type">status_t </span><span class="methodname">GetRef</span>(<span class="methodparam"><span class="type">entry_ref* </span><span class="parameter">ref</span></span>) <span class="modifier">const</span>;</code><p>
Gets the <span class="type">entry_ref</span> for the object's entry; <code class="parameter">ref</code> must be allocated before
it's passed in. As with <code class="classname">BEntry</code> objects, <span class="type">entry_ref</span> structures can be
abstract—getting a valid <span class="type">entry_ref</span> does <span class="emphasis"><em>not</em></span> guarantee that the
entry actually exists.
</p><p>
If the function isn't successful, <code class="parameter">ref</code> is unset.
</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 <span class="type">entry_ref</span> was successfully retrieved.</p></td></tr><tr><td><p><span class="term"><code class="constant">B_NO_INIT</code>.</span></p></td><td><p>This object isn't initialized.
</p></td></tr><tr><td><p><span class="term"><code class="constant">B_NO_MEMORY</code>.</span></p></td><td><p>Storage for the <span class="type">entry_ref</span>'s name couldn't be allocated.</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="BEntry_GetStat"></a>GetStat()</h4></div></div></div><code class="methodsynopsis cpp"><span class="modifier">virtual </span><span class="type">status_t </span><span class="methodname">GetStat</span>(<span class="methodparam"><span class="type">struct stat* </span><span class="parameter">st</span></span>) <span class="modifier">const</span>;</code><p>
<code class="methodname">GetStat()</code> returns the <span class="type">stat</span> structure for the entry. The structure is
copied into the <code class="parameter">st</code> argument, which must be allocated. The
<a class="link" href="BStatable.html" title="BStatable"><code class="classname">BStatable</code></a>
object does not cache the <span class="type">stat</span> structure; every time you call
<code class="methodname">GetStat()</code>,
fresh stat information is retrieved.
</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>Success.</p></td></tr><tr><td><p><span class="term"><code class="constant">B_NO_MEMORY</code>.</span></p></td><td><p>Couldn't get the necessary resources to complete the
transaction.</p></td></tr><tr><td><p><span class="term"><code class="constant">B_BAD_VALUE</code>.</span></p></td><td><p>The entry doesn't exist (abstract entry).</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="BEntry_InitCheck"></a>InitCheck()</h4></div></div></div><code class="methodsynopsis cpp"><span class="type">status_t </span><span class="methodname">InitCheck</span>() <span class="modifier">const</span>;</code><p>
Returns the status of the previous construction, assignment operation, or
<a class="link" href="BEntry.html#BEntry_SetTo"><code class="methodname">SetTo()</code></a> call.
</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 initialization was successful.</p></td></tr><tr><td><p><span class="term"><code class="constant">B_NO_INIT</code>.</span></p></td><td><p>The object is uninitialized (this includes
<a class="link" href="BEntry.html#BEntry_Unset" title="SetTo(), Unset()"><code class="methodname">Unset()</code></a>).</p></td></tr><tr><td><p><span class="term">Other errors.</span></p></td><td><p>See <a class="link" href="BEntry.html#BEntry_SetTo"><code class="methodname">SetTo()</code></a></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="BEntry_Remove"></a>Remove()</h4></div></div></div><code class="methodsynopsis cpp"><span class="type">status_t </span><span class="methodname">Remove</span>();</code><p>
<code class="methodname">Remove()</code> "unlinks" the entry from its directory. The entry's node isn't
destroyed until all file descriptors that are open on the node are
closed. This means that if you create
<a class="link" href="BFile.html" title="BFile"><code class="classname">BFile</code></a> based on
a <code class="classname">BEntry</code>, and then
<code class="methodname">Remove()</code> the <code class="classname">BEntry</code>, the
<a class="link" href="BFile.html" title="BFile"><code class="classname">BFile</code></a> will still be
able to read and write the
file's data—the <a class="link" href="BFile.html" title="BFile"><code class="classname">BFile</code></a>
has no way of knowing that the entry is gone.
When the <a class="link" href="BFile.html" title="BFile"><code class="classname">BFile</code></a>
is deleted, the node will be destroyed as well.
</p><div class="admonition note"><div class="title">Note</div><div class="graphic"><img class="icon" alt="Note" width="32" src="./images/admonitions/Info_32.png" /><div class="text"><p><code class="methodname">Remove()</code> does <span class="emphasis"><em>not</em></span> invalidate the
<code class="classname">BEntry</code>. It simply makes it abstract
(see "<a class="xref" href="BEntry_Overview.html#BEntry_Abstract_Entries" title="Abstract Entries">Abstract Entries</a>").</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>Success.</p></td></tr><tr><td><p><span class="term"><code class="constant">B_NO_INIT</code>.</span></p></td><td><p>The <code class="classname">BEntry</code> is not initialized.</p></td></tr><tr><td><p><span class="term"><code class="constant">B_BUSY</code>.</span></p></td><td><p>The entry's directory is locked.</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="BEntry_Rename"></a><a id="BEntry_MoveTo"></a>
Rename(), MoveTo()</h4></div></div></div><code class="methodsynopsis cpp"><span class="type">status_t </span><span class="methodname">Rename</span>(<span class="methodparam"><span class="modifier">const </span><span class="type">char* </span><span class="parameter">path</span></span>,<br />                <span class="methodparam"><span class="type">bool </span><span class="parameter">clobber</span><span class="initializer"> = <span class="constant">false</span></span></span>);</code><code class="methodsynopsis cpp"><span class="type">status_t </span><span class="methodname">MoveTo</span>(<span class="methodparam"><span class="type"><a class="link" href="BDirectory.html" title="BDirectory"><code class="classname">BDirectory</code></a>* </span><span class="parameter">dir</span></span>,<br />                <span class="methodparam"><span class="modifier">const </span><span class="type">char* </span><span class="parameter">path</span><span class="initializer"> = <span class="constant">NULL</span></span></span>,<br />                <span class="methodparam"><span class="type">bool </span><span class="parameter">clobber</span><span class="initializer"> = <span class="constant">false</span></span></span>);</code><p>
These functions move the <code class="classname">BEntry</code>'s entry and node to a new location. In
both cases, the <code class="classname">BEntry</code> must not be abstract—you can't rename or
move an abstract entry.
</p><p>
<code class="methodname">Rename()</code> moves the entry to a new name, as given
by <code class="parameter">path</code>. <code class="parameter">path</code> is usually
a simple leaf name, but it can be a relative path. In the former case
(simple leaf) the entry is renamed within its current directory. In the
latter, the entry is moved into a subdirectory of its current directory,
as given by the argument.
</p><p>
<code class="methodname">MoveTo()</code> moves the entry to a different directory and optionally renames
the leaf. Again, <code class="parameter">path</code> can be a simple leaf or a relative path; in both
cases, <code class="parameter">path</code> is reckoned off of <code class="parameter">dir</code>.
If path is <code class="constant">NULL</code>, the entry is moved
to <code class="parameter">dir</code>, but retains its old leaf name.
</p><p>
If the entry's new location is already taken, the clobber argument
decides whether the existing entry is removed to make way for yours. If
it's <code class="constant">true</code>, the existing entry is removed; if it's
<code class="constant">false</code>, the <code class="methodname">Rename()</code> or
<code class="methodname">MoveTo()</code> function fails.
</p><p>
Upon success, this is updated to reflect the change to its entry. For
example, when you invoke <code class="methodname">Rename()</code> on a
<code class="classname">BEntry</code>, the name of <span class="emphasis"><em>that specific</em></span>
<code class="classname">BEntry</code> object also changes. If the rename or move-to isn't successful,
this isn't altered.
</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>Success.</p></td></tr><tr><td><p><span class="term"><code class="constant">B_NO_INIT</code>.</span></p></td><td><p>The <code class="classname">BEntry</code> is not initialized.</p></td></tr><tr><td><p><span class="term"><code class="constant">B_ENTRY_NOT_FOUND</code>.</span></p></td><td><p>A directory to the new location doesn't exist, or
this is an abstract entry.</p></td></tr><tr><td><p><span class="term"><code class="constant">B_FILE_EXISTS</code>.</span></p></td><td><p>The new location is already taken (and you're not clobbering).</p></td></tr><tr><td><p><span class="term"><code class="constant">B_BUSY</code>.</span></p></td><td><p>The directory that you're moving the entry into is locked.</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="BEntry_Unset"></a><a id="BEntry_SetTo"></a>
SetTo(), Unset()</h4></div></div></div><div class="synopsisgroup">
<code class="methodsynopsis cpp"><span class="type">status_t </span><span class="methodname">SetTo</span>(<span class="methodparam"><span class="modifier">const </span><span class="type">entry_ref* </span><span class="parameter">ref</span></span>,<br />               <span class="methodparam"><span class="type">bool </span><span class="parameter">traverse</span><span class="initializer"> = <span class="constant">false</span></span></span>);</code>
<code class="methodsynopsis cpp"><span class="type">status_t </span><span class="methodname">SetTo</span>(<span class="methodparam"><span class="modifier">const </span><span class="type">char* </span><span class="parameter">path</span></span>,<br />               <span class="methodparam"><span class="type">bool </span><span class="parameter">traverse</span><span class="initializer"> = <span class="constant">false</span></span></span>);</code>
<code class="methodsynopsis cpp"><span class="type">status_t </span><span class="methodname">SetTo</span>(<span class="methodparam"><span class="modifier">const </span><span class="type"><a class="link" href="BDirectory.html" title="BDirectory"><code class="classname">BDirectory</code></a>* </span><span class="parameter">dir</span></span>,<br />               <span class="methodparam"><span class="modifier">const </span><span class="type">char* </span><span class="parameter">path</span></span>,<br />               <span class="methodparam"><span class="type">bool </span><span class="parameter">traverse</span><span class="initializer"> = <span class="constant">false</span></span></span>);</code>
</div><code class="methodsynopsis cpp"><span class="void">void </span><span class="methodname">Unset</span>();</code><p>
Frees the <code class="classname">BEntry</code>'s current entry reference, and initializes it to refer
to the entry identified by the argument(s):
</p><ul class="itemizedlist"><li><p>
In the <code class="parameter">ref</code> version, the <code class="classname">BEntry</code>
is initialized to refer to the given
<span class="type">entry_ref</span>.
</p></li><li><p>
In the <code class="parameter">path</code> version, <code class="parameter">path</code> can be absolute or relative, and can
contain "." and ".." elements. If <code class="parameter">path</code> is relative, it's reckoned off
of the current working directory.
</p></li><li><p>
In the <code class="parameter">dir</code>/<code class="parameter">path</code> version,
<code class="parameter">path</code> must be relative. It's reckoned off of
the directory given by <code class="parameter">dir</code>.
</p></li></ul><p>
The <code class="parameter">traverse</code> argument is used to resolve (or not) entries that are
symlinks:
</p><ul class="itemizedlist"><li><p>
If <code class="parameter">traverse</code> is <code class="constant">true</code>, the link is resolved.
</p></li><li><p>
If <code class="parameter">traverse</code> is <code class="constant">false</code>,
the <code class="classname">BEntry</code> refers to the link itself.
</p></li></ul><p>
See "<a class="xref" href="BEntry_Overview.html#BEntry_Initializing_And_Traversing" title="Initializing and Traversing">Initializing and Traversing</a>" for more information.
</p><p>
When you initialize a <code class="classname">BEntry</code>, you're describing a leaf name within a
directory. The directory <span class="emphasis"><em>must</em></span> exist, but the leaf doesn't have to. This
allows you to create a <code class="classname">BEntry</code> to a file that doesn't exist (yet). See
"<a class="xref" href="BEntry_Overview.html#BEntry_Abstract_Entries" title="Abstract Entries">Abstract Entries</a>" for more information.
</p><div class="admonition note"><div class="title">Note</div><div class="graphic"><img class="icon" alt="Note" width="32" src="./images/admonitions/Info_32.png" /><div class="text"><p>Remember—successfully initializing a <code class="classname">BEntry</code> consumes a file
descriptor. When you re-initialize, the old file descriptor is closed.</p></div></div></div><p>
<code class="methodname">Unset()</code> removes the object's association with its current entry, and sets
<a class="link" href="BEntry.html#BEntry_InitCheck" title="InitCheck()"><code class="methodname">InitCheck()</code></a>
to <code class="constant">B_NO_INIT</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>The <code class="classname">BEntry</code> was successfully initialized.</p></td></tr><tr><td><p><span class="term"><code class="constant">B_BAD_VALUE</code>.</span></p></td><td><p>Bad argument value; uninitialized
<code class="parameter">ref</code> or <code class="parameter">dir</code>.</p></td></tr><tr><td><p><span class="term"><code class="constant">B_ENTRY_NOT_FOUND</code>.</span></p></td><td><p>A directory in the path to the entry doesn't exist.</p></td></tr><tr><td><p><span class="term"><code class="constant">B_ENTRY_NOT_FOUND</code>.</span></p></td><td><p>The entry's directory is locked.</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="BEntry_Operators"></a>Operators</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="BEntry_operator_equals"></a>= (assignment)</h4></div></div></div><code class="methodsynopsis cpp"><span class="type">BEntry&amp; </span><span class="methodname">operator=</span>(<span class="methodparam"><span class="modifier">const </span><span class="type">BEntry&amp; </span><span class="parameter">entry</span></span>);</code><p>
In the expression
</p><pre class="programlisting example cpp"><code class="classname">BEntry</code> <code class="varname">a</code> = <code class="varname">b</code>;</pre><p>
<code class="classname">BEntry</code> <code class="varname">a</code> is initialized to refer
to the same entry as <code class="varname">b</code>. To gauge the
success of the assignment, you should call
<a class="link" href="BEntry.html#BEntry_InitCheck" title="InitCheck()"><code class="methodname">InitCheck()</code></a>
immediately afterwards. Assigning a <code class="classname">BEntry</code> to itself is safe.
</p><p>
Assigning from an uninitialized <code class="classname">BEntry</code> is "successful": The assigned-to
<code class="classname">BEntry</code> will also be uninitialized (<code class="constant">B_NO_INIT</code>).
</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="BEntry_operator_equality"></a><a id="BEntry_operator_inequality"></a>
== , != (comparison)</h4></div></div></div><code class="methodsynopsis cpp"><span class="type">bool </span><span class="methodname">operator==</span>(<span class="methodparam"><span class="modifier">const </span><span class="type">BEntry&amp; </span><span class="parameter">entry</span></span>) <span class="modifier">const</span>;</code><code class="methodsynopsis cpp"><span class="type">bool </span><span class="methodname">operator!=</span>(<span class="methodparam"><span class="modifier">const </span><span class="type">BEntry&amp; </span><span class="parameter">entry</span></span>) <span class="modifier">const</span>;</code><p>
Two <code class="classname">BEntry</code> objects are said to be equal if they refer to the same entry
(even if the entry is abstract), or if they're both uninitialized.
</p></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="BEntry_Functions"></a>Global C Function</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="get_ref_for_path"></a>get_ref_for_path()</h4></div></div></div><a id="id1231390" class="indexterm"></a><code class="methodsynopsis cpp"><span class="type">status_t </span><span class="methodname">get_ref_for_path</span>(<span class="methodparam"><span class="modifier">const </span><span class="type">char* </span><span class="parameter">path</span></span>,<br />                          <span class="methodparam"><span class="type">entry_ref* </span><span class="parameter">ref</span></span>);</code><p>
Returns in <code class="parameter">ref</code> an <span class="type">entry_ref</span>
for the file specified by the <code class="parameter">path</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_OK</code>.</span></p></td><td><p>The ref was returned successfully.</p></td></tr><tr><td><p><span class="term"><code class="constant">B_ENTRY_NOT_FOUND</code>.</span></p></td><td><p>The file wasn't found, or the pathname string is
empty.</p></td></tr><tr><td><p><span class="term"><code class="constant">B_NO_MEMORY</code>.</span></p></td><td><p>Not enough memory.</p></td></tr><tr><td><p><span class="term">Other file errors.</span></p></td><td></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="BEntry_DefinedTypes"></a>Defined Types</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="entry_ref"></a>entry_ref</h4></div></div></div><a id="id1231534" class="indexterm"></a><p>
Declared in: <code class="filename">storage/Entry.h</code>
</p><pre class="programlisting definition cpp">struct <span class="type">entry_ref</span> {
<code class="methodname">entry_ref</code>();
<code class="methodname">entry_ref</code>(<span class="type">dev_t</span> <code class="parameter">device</code>, <span class="type">ino_t</span> <code class="parameter">dir</code>, const <span class="type">char*</span> <code class="parameter">name</code>);
<code class="methodname">entry_ref</code>(const <span class="type">entry_ref&amp;</span> <code class="parameter">ref</code>);
<code class="methodname">~entry_ref</code>();
<span class="type">status_t</span> <code class="methodname">set_name</code>(const <span class="type">char*</span> <code class="parameter">name</code>);
<span class="type">bool</span> <code class="methodname">operator==</code>(const <span class="type">entry_ref&amp;</span> <code class="parameter">ref</code>) const;
<span class="type">bool</span> <code class="methodname">operator!=</code>(const <span class="type">entry_ref&amp;</span> <code class="parameter">ref</code>) const;
<span class="type">entry_ref&amp;</span> <code class="methodname">operator=</code>(const <span class="type">entry_ref&amp;</span> <code class="parameter">ref</code>);
<span class="type">dev_t</span> <code class="varname">device</code>;
<span class="type">ino_t</span> <code class="varname">directory</code>;
<span class="type">char*</span> <code class="varname">name</code>;
}</pre><p>
The <span class="type">entry_ref</span> structure describes a single entry in a directory.
</p><ul class="itemizedlist"><li><p>
<code class="varname">device</code> contains the device number on which the entry's target is located.
</p></li><li><p>
<code class="varname">directory</code> contains the inode of the directory that contains the entry's
target.
</p></li><li><p>
<code class="varname">name</code> contains the name of the entry.
</p></li></ul><code class="constructorsynopsis cpp"><span class="methodname">entry_ref</span>();</code><code class="constructorsynopsis cpp"><span class="methodname">entry_ref</span>(<span class="methodparam"><span class="modifier">const </span><span class="type">entry_ref&amp; </span><span class="parameter">ref</span></span>);</code><code class="constructorsynopsis cpp"><span class="methodname">entry_ref</span>(<span class="methodparam"><span class="type">dev_t </span><span class="parameter">device</span></span>,<br />          <span class="methodparam"><span class="type">ino_t </span><span class="parameter">dir</span></span>,<br />          <span class="methodparam"><span class="modifier">const </span><span class="type">char* </span><span class="parameter">name</span></span>);</code><p>
The constructor for the <span class="type">entry_ref</span> structure. The first of these
creates an empty <span class="type">entry_ref</span>, the second duplicates an existing <span class="type">entry_ref</span>,
and the last version of the constructor accepts a device number,
directory inode number, and a file name and constructs an <span class="type">entry_ref</span>
referring to that entry.
</p><code class="destructorsynopsis cpp"><span class="methodname">~entry_ref</span>();</code><p>
The destructor for <span class="type">entry_ref</span>.
</p><code class="methodsynopsis cpp"><span class="type">status_t </span><span class="methodname">set_name</span>(<span class="methodparam"><span class="modifier">const </span><span class="type">char* </span><span class="parameter">name</span></span>);</code><p>
Lets you change the name of the file referred to by the <span class="type">entry_ref</span>
structure.
</p><p>
<code class="methodname">operator ==</code>
</p><p>
Lets you perform comparisons of <span class="type">entry_ref</span> structures to see if they
refer to the same entry.
</p><p>
<code class="methodname">operator !=</code>
</p><p>
Lets you test to see if two <span class="type">entry_ref</span> structures refer to different
entries.
</p></div></div></div><div id="footer"><hr /><div id="footerT">Prev: <a href="BDirectory.html">BDirectory</a>  Up: <a href="TheStorageKit.html">The Storage Kit</a>  Next: <a href="BEntryList.html">BEntryList</a> </div><div id="footerB"><div id="footerBL"><a href="BDirectory.html" title="BDirectory"><img src="./images/navigation/prev.png" alt="Prev" /></a> <a href="TheStorageKit.html" title="The Storage Kit"><img src="./images/navigation/up.png" alt="Up" /></a> <a href="BEntryList.html" title="BEntryList"><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