haiku-website/static/legacy-docs/bebook/TheStorageKit_Overview_Entr...

<?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 - System Overview - 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_Overview.html" title="The Storage Kit" /><link rel="prev" href="TheStorageKit_Overview_FileSystemArchitecture.html" title="File System Architecture" /><link rel="next" href="TheStorageKit_Overview_Mime_And_File_Types.html" title="Mime And File Types" /></head><body><div id="header"><div id="headerT"><div id="headerTL"><a accesskey="p" href="TheStorageKit_Overview_FileSystemArchitecture.html" title="File System Architecture"><img src="./images/navigation/prev.png" alt="Prev" /></a> <a accesskey="u" href="TheStorageKit_Overview.html" title="The Storage Kit"><img src="./images/navigation/up.png" alt="Up" /></a> <a accesskey="n" href="TheStorageKit_Overview_Mime_And_File_Types.html" title="Mime And File Types"><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 - System Overview - The Storage Kit</div></div><div id="headerB">Prev: <a href="TheStorageKit_Overview_FileSystemArchitecture.html">File System Architecture</a>  Up: <a href="TheStorageKit_Overview.html">The Storage Kit</a>  Next: <a href="TheStorageKit_Overview_Mime_And_File_Types.html">Mime And File Types</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="TheStorageKit_Overview_Entries_And_Nodes"></a>Entries And Nodes</h2></div></div></div><p>
The most important concept that you should keep in mind when you're using
the Storage Kit is that a file is considered both an entry and a node:
</p><ul class="itemizedlist"><li><p>
The entry part of a file is its location in the file hierarchy. An
entry is similar to a pathname: It tells you where a file is (or should
be), but it doesn't let you look at its contents.
</p></li><li><p>
The node part of a file is its data. A node is an actual "thing"
that's separate from the file's entry—when you rename a file, for
example, all you're doing is tagging the node with a different pathname
(or, in our lingo, you move the node from one entry to another). Just
as entries don't know about data, nodes don't know anything about
entries: A node doesn't know where its entry is located.
</p></li></ul><p>
This concept really isn't new: If you're familiar with POSIX, then you've
already dealt with entries and nodes, except you called them pathnames
and file descriptors.
</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="TheStorageKit_Overview_Entries"></a>Entries</h3></div></div></div><p>
In the Storage Kit, entries are represented three ways:
</p><ul class="itemizedlist"><li><p>
As pathnames,
</p></li><li><p>
as <span class="type">entry_ref</span> structures,
</p></li><li><p>
and as <a class="link" href="BEntry.html" title="BEntry"><code class="classname">BEntry</code></a> objects.
</p></li></ul><p>
Any entry can be given by any of these representations. Furthermore, the
representations are fairly easily converted: Given an <span class="type">entry_ref</span>, it's
trivial to get a <a class="link" href="BEntry.html" title="BEntry"><code class="classname">BEntry</code></a>,
from which you can easily get a pathname, which
can be turned into an <span class="type">entry_ref</span>. Which representation you use depends on
what you're doing:
</p><ul class="itemizedlist"><li><p>
You use pathnames or <span class="type">entry_ref</span>s to keep track of the entries you're
interested in.
</p></li><li><p>
You use <a class="link" href="BEntry.html" title="BEntry"><code class="classname">BEntry</code></a> objects to query and manipulate the entries. For
example, if you want to know if an entry is a directory or a file, you
need a <a class="link" href="BEntry.html" title="BEntry"><code class="classname">BEntry</code></a> object.
</p></li></ul><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>An <span class="type">entry_ref</span> or <a class="link" href="BEntry.html" title="BEntry"><code class="classname">BEntry</code></a>
isn't necessarily valid across reboots; don't
archive these and expect them to work when the system is restarted.
Instead, you should save pathnames (either complete or partial, depending
on your specific needs; when possible, you should use the directory
constants used by the
<a class="link" href="BDirectory.html#find_directory" title="find_directory()"><code class="function">find_directory()</code></a> function).</p></div></div></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="TheStorageKit_Overview_Nodes"></a>Nodes</h3></div></div></div><p>
Nodes are represented in two ways:
</p><ul class="itemizedlist"><li><p>
As <span class="type">node_ref</span> structures,
</p></li><li><p>
and as <a class="link" href="BNode.html" title="BNode"><code class="classname">BNode</code></a> objects.
</p></li></ul><p>
Here, again, the representations are easily converted. As for use…
</p><ul class="itemizedlist"><li><p>
<span class="type">node_ref</span>s are used for purposes that we're going to ignore for now
(we're just covering the basics, here).
</p></li><li><p>
The <a class="link" href="BNode.html" title="BNode"><code class="classname">BNode</code></a>
class is where the action is. If you want to read and write
the data in a file, you need a
<a class="link" href="BNode.html" title="BNode"><code class="classname">BNode</code></a>
object—more specifically, you need an instance of the
<a class="link" href="BFile.html" title="BFile"><code class="classname">BFile</code></a>
class, which derives from
<a class="link" href="BNode.html" title="BNode"><code class="classname">BNode</code></a>.
</p></li></ul><p>
Every node has a type, or flavor. There are three node flavors:
</p><ul class="itemizedlist"><li><p>
plain files
</p></li><li><p>
directories
</p></li><li><p>
symbolic links
</p></li></ul><p>
These flavors are represented by subclasses of
<a class="link" href="BNode.html" title="BNode"><code class="classname">BNode</code></a>:
<a class="link" href="BFile.html" title="BFile"><code class="classname">BFile</code></a>,
<a class="link" href="BDirectory.html" title="BDirectory"><code class="classname">BDirectory</code></a>,
and <a class="link" href="BSymLink.html" title="BSymLink"><code class="classname">BSymLink</code></a>.
Note that a <span class="type">node_ref</span> doesn't know its node's flavor.
</p></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="TheStorageKit_Overview_More_Facts"></a>More Facts</h3></div></div></div><p>
Some more facts you should be aware of:
</p><ul class="itemizedlist"><li><p>
Every node has an entry; not every entry has a node.
</p><p>
If you've got your hands on a node, then you can assume that there's an
entry somewhere that "contains" that node. (This isn't entirely
true, but it's true enough for now. For the real story, see
"<a class="xref" href="TheStorageKit_Overview_Entries_And_Nodes.html#TheStorageKit_Overview_Lies" title="Lies">Lies</a>")
</p><p>
The converse isn't true: An entry needn't have any data. Such entry's are
called "abstract". Abstract entries are useful for expressing the
location of a file before it's created (for example). But don't be
misled: Abstract entries do not exist in the file hierarchy, they're
simply placeholders that your app uses to designate a location. This
leads us to our next fact:
</p></li><li><p>
Every file in the file hierarchy has an entry and a node.
</p><p>
This might seem obvious; if it does, then go to the next fact. For the
skeptics, here's the gospel: The files that "normal" apps work with are
real—they actually exist as bytes on a disk. Such files have a
location in the hierarchy, and they contain data.
</p></li><li><p>
You can convert an entry into a node, but not the other way around.
</p><p>
The <a class="link" href="BNode.html" title="BNode"><code class="classname">BNode</code></a>
class accepts any form of entry representation as an argument
to its constructor. In other words, given a pathname, <span class="type">entry_ref</span>, or
<a class="link" href="BEntry.html" title="BEntry"><code class="classname">BEntry</code></a> object, you can create a
<a class="link" href="BNode.html" title="BNode"><code class="classname">BNode</code></a>. But once you've
got your <a class="link" href="BNode.html" title="BNode"><code class="classname">BNode</code></a>,
you can't go back: There's no way to get an entry from a node.
</p><p>
Returning to the <a class="link" href="BNode.html" title="BNode"><code class="classname">BNode</code></a>
constructor: You can only create a <a class="link" href="BNode.html" title="BNode"><code class="classname">BNode</code></a> by
passing the constructor an entry (in one of its representations). This is
an important point that we'll pick up in the next section.
</p></li></ul></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="TheStorageKit_Overview_Lies"></a>Lies</h3></div></div></div><p>
Here are some more facts, slight alterations to the near truths spoken
above:
</p><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="id601137"></a>A Node can Lose its Entry</h4></div></div></div><p>
Consider this scenario: You create a
<a class="link" href="BFile.html" title="BFile"><code class="classname">BFile</code></a> object to some file. While
you're reading and writing the file, the user deletes the file through
the Tracker or from a Terminal. What the user has done is delete the
node's entry, not the node itself. The node isn't destroyed until all
references to the node, including your
<a class="link" href="BFile.html" title="BFile"><code class="classname">BFile</code></a>, are deleted (or, more
accurately, "closed"). The twist is that your
<a class="link" href="BFile.html" title="BFile"><code class="classname">BFile</code></a> by itself has no way
of knowing that the entry is gone.
</p><p>
So what are you supposed to do? In general, whenever you free a
<a class="link" href="BFile.html" title="BFile"><code class="classname">BFile</code></a>
object, you should first check to make sure the entry still exists; of
course, the <a class="link" href="BFile.html" title="BFile"><code class="classname">BFile</code></a>
itself can't tell you (remember: A node doesn't know
about its entry), so you have to save the entry that was used to create
the <a class="link" href="BFile.html" title="BFile"><code class="classname">BFile</code></a>.
You ask the entry if it still exists, and then do whatever you
have to do if it doesn't, such as alert the user, ask for a new entry
name, and so on.
</p><p>
Unfortunately, this problem has another wrinkle: What if the user moves
the entry while you're using the entry's node? In this case, the node
isn't going to be destroyed, but if you ask the generative entry (the
entry that was used to create the
<a class="link" href="BFile.html" title="BFile"><code class="classname">BFile</code></a> object), it looks like the entry
is gone.
</p><p>
There's no generic solution to the entire problem. Not because it's
impossible to implement, but because the "right" solution depends on what
the user meant by deleting or moving the entry. Most applications take
this approach: The user knows files as entries, not as nodes. If a user
opens a file through your app, moves the entry (through some other
vehicle, such as the Tracker), and then asks your app to save the file,
what the user really want is for you to save the node under the same name
that was used to open the node.
</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="id601226"></a>A BDirectory Knows its Entry</h4></div></div></div><p>
<a class="link" href="BDirectory.html" title="BDirectory"><code class="classname">BDirectory</code></a>
is an exception to the "ignorant node" rule: You can ask a
<a class="link" href="BDirectory.html" title="BDirectory"><code class="classname">BDirectory</code></a>
object for its entry (through its
<a class="link" href="BDirectory.html#BDirectory_GetEntry" title="GetEntry()"><code class="methodname">GetEntry()</code></a> function).
</p></div></div></div><div id="footer"><hr /><div id="footerT">Prev: <a href="TheStorageKit_Overview_FileSystemArchitecture.html">File System Architecture</a>  Up: <a href="TheStorageKit_Overview.html">The Storage Kit</a>  Next: <a href="TheStorageKit_Overview_Mime_And_File_Types.html">Mime And File Types</a> </div><div id="footerB"><div id="footerBL"><a href="TheStorageKit_Overview_FileSystemArchitecture.html" title="File System Architecture"><img src="./images/navigation/prev.png" alt="Prev" /></a> <a href="TheStorageKit_Overview.html" title="The Storage Kit"><img src="./images/navigation/up.png" alt="Up" /></a> <a href="TheStorageKit_Overview_Mime_And_File_Types.html" title="Mime And File Types"><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>