111 lines
13 KiB
HTML
111 lines
13 KiB
HTML
<?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="BResources_Overview.html" title="BResources" /><link rel="next" href="BSymLink_Overview.html" title="BSymLink" /></head><body><div id="header"><div id="headerT"><div id="headerTL"><a accesskey="p" href="BResources_Overview.html" title="BResources"><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="BSymLink_Overview.html" title="BSymLink"><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="BResources_Overview.html">BResources</a> Up: <a href="TheStorageKit_Overview.html">The Storage Kit</a> Next: <a href="BSymLink_Overview.html">BSymLink</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="BStatable_Overview"></a>BStatable</h2></div></div></div><a id="id614272" class="indexterm"></a><p>
|
||
<code class="classname">BStatable</code> is a pure abstract class that provides functionality for its
|
||
two derived class, <a class="link" href="BEntry.html" title="BEntry"><code class="classname">BEntry</code></a> and
|
||
<a class="link" href="BNode.html" title="BNode"><code class="classname">BNode</code></a>. The <code class="classname">BStatable</code> functions let you get
|
||
and set "statistical" information about a node in the file system. You
|
||
can…
|
||
</p><ul class="itemizedlist"><li><p>
|
||
Determine whether the node is a file, directory, or symbolic link.
|
||
</p></li><li><p>
|
||
Get and set an node's owner, group, and permissions.
|
||
</p></li><li><p>
|
||
Get and set the node's creation, modification, and access times.
|
||
</p></li><li><p>
|
||
Get the size of the node's data (not counting attributes).
|
||
</p></li><li><p>
|
||
Get a <a class="link" href="BVolume.html" title="BVolume"><code class="classname">BVolume</code></a> object for the node's volume.
|
||
</p></li><li><p>
|
||
Get the <span class="type">node_ref</span> of the node (and pass it to
|
||
<a class="link" href="The_Node_Monitor.html#watch_node" title="watch_node()"><code class="function">watch_node()</code></a>, most
|
||
likely).
|
||
</p></li></ul><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="BStatable_Nodes_And_Entries"></a>Nodes and Entries</h3></div></div></div><p>
|
||
Technically, <code class="classname">BStatable</code> information pertains to nodes, not entries. The
|
||
fact that <a class="link" href="BEntry.html" title="BEntry"><code class="classname">BEntry</code></a> implements the
|
||
<code class="classname">BStatable</code> functions is a (slightly
|
||
confusing) convenience: When you invoke a <code class="classname">BStatable</code> function on a
|
||
<a class="link" href="BEntry.html" title="BEntry"><code class="classname">BEntry</code></a>
|
||
object, what you're really doing is asking for information about the node
|
||
that corresponds to the object.
|
||
</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="BStatable_Abstract_Entries"></a>Abstract Entries</h3></div></div></div><p>
|
||
As explained in <a class="link" href="BEntry.html" title="BEntry"><code class="classname">BEntry</code></a>,
|
||
it's possible to create "abstract"
|
||
<a class="link" href="BEntry.html" title="BEntry"><code class="classname">BEntry</code></a>
|
||
objects; in other words, objects that don't correspond to actual files
|
||
(nodes) on the disk. You can't get (or set) <code class="classname">BStatable</code> information for
|
||
abstract entries. The <code class="classname">BStatable</code> functions return
|
||
<code class="constant">B_BAD_VALUE</code> if the
|
||
invoked-upon entry is abstract.
|
||
</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="BStatable_Relationship_To_stat"></a>Relationship to stat()</h3></div></div></div><p>
|
||
The <code class="classname">BStatable</code> functions are covers for the POSIX
|
||
<a class="link" href="TheStorageKit_DefinedTypes.html#stat" title="stat"><code class="function">stat()</code></a> call. <code class="function">stat()</code>
|
||
retrieves a file-specific <span class="type">stat</span> structure, which records the statistics
|
||
listed above (and then some). Although <code class="classname">BStatable</code> was designed to hide
|
||
stat details, you can get the
|
||
<a class="link" href="TheStorageKit_DefinedTypes.html#stat" title="stat"><code class="function">stat()</code></a> structure through the
|
||
<a class="link" href="BStatable.html#BStatable_GetStat" title="GetStat()"><code class="methodname">GetStat()</code></a>
|
||
function.
|
||
</p><p>
|
||
<code class="function">stat()</code> is notorious for being expensive. Furthermore, the <span class="type">stat</span> structure
|
||
is stale as soon as it gets back from the <code class="function">stat()</code> call. If you're
|
||
concerned with efficiency, be aware that every <code class="classname">BStatable</code> function (the
|
||
"setters" as well as the "getters") performs a <code class="function">stat()</code>. For example,
|
||
calling
|
||
<a class="link" href="BStatable.html#BStatable_GetOwner" title="GetOwner(), SetOwner(), GetGroup(), SetGroup(), GetPermissions(), SetPermissions()"><code class="methodname">GetOwner()</code></a>
|
||
and then
|
||
<a class="link" href="BStatable.html#BStatable_GetGroup"><code class="methodname">GetGroup()</code></a>
|
||
results in two <code class="function">stat()</code> calls. If
|
||
you want to look at lot of fields (within the same <span class="type">stat</span> structure) all at
|
||
once, you might consider using <code class="classname">BStatable</code>'s
|
||
<a class="link" href="BStatable.html#BStatable_GetStat" title="GetStat()"><code class="methodname">GetStat()</code></a> function.
|
||
</p><p>
|
||
As for integrity, <code class="classname">BStatable</code> info-getting functions are obviously in the
|
||
same boat as the <code class="function">stat()</code> call itself: The retrieved data isn't guaranteed
|
||
to be in sync with the actual state of the <code class="function">stat()</code>'d item.
|
||
</p><p>
|
||
The <a class="link" href="BDirectory.html" title="BDirectory"><code class="classname">BDirectory</code></a>
|
||
class also defines a stat-retrieving function that, in
|
||
some cases, can be more efficient than the
|
||
<a class="link" href="BStatable.html#BStatable_GetStat" title="GetStat()"><code class="methodname">GetStat()</code></a> function defined
|
||
here:
|
||
</p><ul class="itemizedlist"><li><p>
|
||
The <a class="link" href="BDirectory.html#BDirectory_GetStatFor" title="GetStatFor()"><code class="methodname">BDirectory::GetStatFor()</code></a>
|
||
function retrieves the <span class="type">stat</span> structure
|
||
for the node of a named entry within a directory. If you're interested
|
||
in getting stat information for a series of nodes within the same
|
||
directory, you should use this function. You have to call it
|
||
iteratively (once for each named entry), but the accumulation of the
|
||
iterated calls will be faster than the
|
||
<a class="link" href="BStatable.html#BStatable_GetStat" title="GetStat()"><code class="methodname">GetStat()</code></a> calls made on the
|
||
analogous <a class="link" href="BEntry.html" title="BEntry"><code class="classname">BEntry</code></a> objects.
|
||
</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="BStatable_Accessing_Unreadable_And_Unwritable_Entries"></a>Accessing Unreadable and Unwritable Entries</h3></div></div></div><p>
|
||
<code class="classname">BStatable</code> isn't thwarted by file permissions: If you can construct a
|
||
valid <a class="link" href="BEntry.html" title="BEntry"><code class="classname">BEntry</code></a> or
|
||
<a class="link" href="BNode.html" title="BNode"><code class="classname">BNode</code></a> to an item, then you can invoke any of the
|
||
info-getting <code class="classname">BStatable</code> functions on that object:
|
||
</p><ul class="itemizedlist"><li><p>
|
||
The <code class="classname">BStatable</code> functions aren't denied even if the node that you're
|
||
looking at is read-protected. However, you can only invoke the
|
||
info-setting functions if the node allows writing.
|
||
</p></li><li><p>
|
||
Similarly, you can get stat info for a locked node, but you won't be
|
||
able to write the info (through functions such as
|
||
<a class="link" href="BStatable.html#BStatable_SetOwner"><code class="methodname">SetOwner()</code></a>) unless
|
||
your object holds the lock. See
|
||
<a class="link" href="BNode.html" title="BNode"><code class="classname">BNode</code></a> for more on locking.
|
||
</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="BStatable_Other_Details"></a>Other Details</h3></div></div></div><p>
|
||
You rarely set stat information. In practice, you rarely use <code class="classname">BStatable</code>'s
|
||
info-setting functions. Setting information such as when a file was
|
||
created, who owns it, or how big it is, is the responsibility of the
|
||
system and the privilege of the user. For example, when you
|
||
<a class="link" href="BFile.html#BFile_Write"><code class="methodname">Write()</code></a> to a
|
||
<a class="link" href="BFile.html" title="BFile"><code class="classname">BFile</code></a>
|
||
object, the system automatically updates the size and modification
|
||
date for the file.
|
||
</p></div></div><div id="footer"><hr /><div id="footerT">Prev: <a href="BResources_Overview.html">BResources</a> Up: <a href="TheStorageKit_Overview.html">The Storage Kit</a> Next: <a href="BSymLink_Overview.html">BSymLink</a> </div><div id="footerB"><div id="footerBL"><a href="BResources_Overview.html" title="BResources"><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="BSymLink_Overview.html" title="BSymLink"><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>
|