A BDirectory object gives you access to the contents of a directory. A BDirectory's primary features are:

Unlike the other BNode classes, a BDirectory knows its own entry (GetEntry()), and can be initialized with a node_ref structure.

Retrieving Entries

The BDirectory functions that let you iterate over a directory's entries are inherited from BEntryList:

status_t GetNextEntry(BEntry *entry, bool traverse = true);
status_t GetNextRef(entry_ref *ref);
int32 GetNextDirents(dirent *buf, size_t length,
                     int32 count = INT_MAX)

For the basic story on these functions, see the BEntryList class and the function descriptions below. In addition to the info you'll find there, you should be aware of the following:

Creating New Directories

To create a new directory, you can use BDirectory's CreateDirectory() function. The function creates a single new directory as identified by its argument. The new directory will be a subdirectory of the invoked-upon BDirectory's directory.

You can also create an entire path full of new directories through the global create_directory() function. This convenient function attempts to create all "missing" directories along the path that you pass in.

Finding a Directory

The find_directory() function gives you the pathnames for pre-defined directories. These directories, such as those that store Be-supplied applications and user-defined preferences settings, are represented by directory_which constants. These constants are not strings; you can't use them directly. You have to pass them through find_directory().

Note that the BDirectory class itself doesn't let you find directories on the basis of the directory_which constants—you have to use the find_directory() function (which is documented at the end of this class description).

Node Monitoring a Directory


The following description is a brief, directory-specific view into the Node Monitor. For the full story, see "The Node Monitor" section of this chapter.

You can monitor changes to the contents of a directory by passing a BDirectory's node_ref and the B_WATCH_DIRECTORY flag to the Node Monitor's watch_node() function. As with all invocations of watch_node(), you also have to pass a BMessenger (the "target") that will receive the Node Monitor notifications; here, we use be_app_messenger:

BDirectory dir("/boot/home");
node_ref nref;
status_t err;

if (dir.InitCheck() == B_OK) {
   err = watch_node(&nref, B_WATCH_DIRECTORY, be_app_messenger);
   if (err != B_OK)
      /* handle the error */

The following changes to the monitored directory cause BMessages to be sent to the target. The what field for all Node Monitor messages is B_NODE_MONITOR; the opcode field (an integer code) describes the activity:

The B_WATCH_DIRECTORY flag (by itself) doesn't monitor changes to the directory's own entry. For example, if you change the name of the directory that you're monitoring, the target isn't sent a message. If you want a BDirectory to watch changes to itself, you have to throw in one of the other Node Monitor flags (B_WATCH_NAME, B_WATCH_STAT, or B_WATCH_ATTR).

The other fields in the Node Monitor message describe the entry that changed. The set of fields depends on the opcode (the following is a summary of the list given in "Notification Messages" in the Node Monitor documentation):


deviceB_INT32_TYPEdev_t of the directory's device.
directoryB_INT64_TYPEino_t (node number) of the directory.
nodeB_INT64_TYPEino_t of the new entry's node.
nameB_STRING_TYPEThe name of the new entry.


The device, node, and name fields are the same as for B_ENTRY_CREATED, plus…

from_directoryB_INT64_TYPEThe ino_t number of the old directory.
to_directoryB_INT64_TYPEThe ino_t number of the new directory.


The B_ENTRY_REMOVED message takes the same form as B_ENTRY_CREATED, but without the name field. This, obviously, can be a problem—what good is it if you're told that a file has been removed, but you're not told the file's name? In some cases, simply being told that a file has been removed actually is good enough: You can simply re-read the contents of the directory.

Creative Commons License
Legal Notice
This work is licensed under a Creative Commons Attribution-Non commercial-No Derivative Works 3.0 License.