BEntry Class Reference

A location in the filesystem. More...

Inherits BStatable.

Public Member Functions
	BEntry ()
	Creates an uninitialized BEntry object.
	BEntry (const BDirectory *dir, const char *path, bool traverse=false)
	Creates a BEntry initialized to the given directory and path combination.
	BEntry (const BEntry &entry)
	Creates a copy of the given BEntry.
	BEntry (const char *path, bool traverse=false)
	Creates a BEntry initialized to the given path.
	BEntry (const entry_ref *ref, bool traverse=false)
	Creates a BEntry for the file referred to by the passed in entry_ref.
virtual	~BEntry ()
	Frees all of the allocated resources of the BEntry.
bool	Exists () const
	Returns whether or not the entry exists in the filesystem.
status_t	GetName (char *buffer) const
	Gets the name of the leaf of the BEntry object.
status_t	GetParent (BDirectory *dir) const
	Gets the parent of the BEntry as a BDirectory.
status_t	GetParent (BEntry *entry) const
	Gets the parent of the BEntry as a BEntry.
status_t	GetPath (BPath *path) const
	Gets the path for the BEntry.
status_t	GetRef (entry_ref *ref) const
	Gets an entry_ref structure for the BEntry.
virtual status_t	GetStat (struct stat *stat) const
	Fills in a stat structure for the entry.
status_t	InitCheck () const
	Returns the result of the most recent construction or SetTo() call.
status_t	MoveTo (BDirectory *dir, const char *path=NULL, bool clobber=false)
	Moves the BEntry to directory or directory and path combination, replacing an existing entry if clobber is true.
bool	operator!= (const BEntry &item) const
	Returns false if the BEntry and item refer to the same entry or if they are both uninitialized.
BEntry &	operator= (const BEntry &item)
	Reinitializes the BEntry to be a copy of item.
bool	operator== (const BEntry &item) const
	Returns true if the BEntry and item refer to the same entry or if they are both uninitialized.
status_t	Remove ()
	Removes the entry from the file system.
status_t	Rename (const char *path, bool clobber=false)
	Renames the BEntry to path replacing an existing entry if clobber is true.
status_t	SetTo (const BDirectory *dir, const char *path, bool traverse=false)
	Reinitializes the BEntry to the path or directory path combination, resolving symlinks if traverse is true.
status_t	SetTo (const char *path, bool traverse=false)
	Reinitializes the BEntry object to the path, resolving symlinks if traverse is true.
status_t	SetTo (const entry_ref *ref, bool traverse=false)
	Reinitializes the BEntry to the passed in entry_ref object resolving symlinks if traverse is true.
void	Unset ()
	Reset the BEntry to the uninitialized state.
Public Member Functions inherited from BStatable
status_t	GetAccessTime (time_t *atime) const
	Fills out atime with the access time of the node.
status_t	GetCreationTime (time_t *ctime) const
	Fills out ctime with the creation time of the node.
status_t	GetGroup (gid_t *group) const
	Fills out the node's GID into group.
status_t	GetModificationTime (time_t *mtime) const
	Fills out mtime with the last modification time of the node.
status_t	GetNodeRef (node_ref *ref) const
	Fills out ref with the node_ref of the node.
status_t	GetOwner (uid_t *owner) const
	Fills out the node's UID into owner.
status_t	GetPermissions (mode_t *permissions) const
	Fills out perms with the permissions of the node.
status_t	GetSize (off_t *size) const
	Fills out the size of the node's data (not counting attributes) into size.
virtual status_t	GetStat (struct stat *stat) const =0
	Fills out the stat structure for the node.
status_t	GetVolume (BVolume *volume) const
	Fills out vol with the the volume that the node lives on.
bool	IsDirectory () const
	Returns whether or not the node is a directory.
bool	IsFile () const
	Returns whether or not the node is a file.
bool	IsSymLink () const
	Returns whether or not the node is a symbolic link.
status_t	SetAccessTime (time_t atime)
	Sets the node's access time to atime.
status_t	SetCreationTime (time_t ctime)
	Sets the node's creation time to ctime.
status_t	SetGroup (gid_t group)
	Sets the node's GID to group.
status_t	SetModificationTime (time_t mtime)
	Sets the node's last modification time to mtime.
status_t	SetOwner (uid_t owner)
	Sets the node's UID to owner.
status_t	SetPermissions (mode_t permissions)
	Sets the node's permissions to perms.

Detailed Description

A location in the filesystem.

The BEntry class defines objects that represent "locations" in the file system hierarchy. Each location (or entry) is given as a name within a directory. For example, if you create a BEntry like this:

BEntry entry("/boot/home/fido");

the resulting BEntry object represents the location of the file fido within the /boot/home directory.

Constructor & Destructor Documentation

BEntry() [1/5]

BEntry::BEntry

(

)

Creates an uninitialized BEntry object.

Should be followed by a call to one of the SetTo() methods, or an assignment.

See also

SetTo(const BDirectory*, const char*, bool)

SetTo(const entry_ref*, bool)

SetTo(const char*, bool)

operator=(const BEntry&)

Since

BeOS R3

BEntry() [2/5]

BEntry::BEntry	(	const BDirectory *	dir,
		const char *	path,
		bool	traverse = false
	)

Creates a BEntry initialized to the given directory and path combination.

If traverse is true and path refers to a symlink, the BEntry will refer to the linked file; if false, the BEntry will refer to the symlink itself.

Parameters

dir	The base directory in which the path resides.
path	Relative path based off of dir.
traverse	Whether or not to traverse symbolic links.

See also

BEntry::SetTo(const BDirectory*, const char *, bool)

Since

BeOS R3

BEntry() [3/5]

BEntry::BEntry	(	const entry_ref *	ref,
		bool	traverse = false
	)

Creates a BEntry for the file referred to by the passed in entry_ref.

If traverse is true and ref refers to a symlink, the BEntry will refer to the linked file; if false, the BEntry will refer to the symlink itself.

Parameters

ref	The entry_ref referring to the given file.
traverse	Whether or not symlinks are to be traversed.

See also

BEntry::SetTo(const entry_ref*, bool)

Since

BeOS R3

BEntry() [4/5]

BEntry::BEntry	(	const char *	path,
		bool	traverse = false
	)

Creates a BEntry initialized to the given path.

If path is relative, it will be reckoned off the current working directory. If path refers to a symlink and traverse is true, the BEntry will refer to the linked file. If traverse is false, the BEntry will refer to the symlink itself.

Parameters

path	The path of the file.
traverse	Whether or not symlinks are to be traversed.

See also

BEntry::SetTo(const char*, bool)

Since

BeOS R3

BEntry() [5/5]

BEntry::BEntry

(

const BEntry &

entry

)

Creates a copy of the given BEntry.

Parameters

entry

the entry to be copied

See also

operator=(const BEntry&)

Since

BeOS R3

~BEntry()

BEntry::~BEntry ( )

virtual

Frees all of the allocated resources of the BEntry.

See also

Unset()

Since

BeOS R3

Member Function Documentation

Exists()

bool BEntry::Exists

(

)

const

Returns whether or not the entry exists in the filesystem.

Returns

true if the entry exists, false if not.

Since

BeOS R3

GetName()

status_t BEntry::GetName

(

char *

buffer

)

const

Gets the name of the leaf of the BEntry object.

buffer must be pre-allocated and of sufficient length to hold the entire string. A length of B_FILE_NAME_LENGTH is recommended.

Parameters

buffer

A pointer to a pre-allocated string into which the result is copied.

Returns

B_OK on success, or an error code on failure.

Since

BeOS R3

GetParent() [1/2]

status_t BEntry::GetParent

(

BDirectory *

dir

)

const

Gets the parent of the BEntry as a BDirectory.

If the function fails, the argument is Unset().

Parameters

dir	A pointer to a pre-allocated BDirectory object into which the result is copied.

Returns

A status code.

Return values

B_OK	Success
B_ENTRY_NOT_FOUND	Attempted to get the parent of the root directory.

Since

BeOS R3

GetParent() [2/2]

status_t BEntry::GetParent

(

BEntry *

entry

)

const

Gets the parent of the BEntry as a BEntry.

If the function fails, the argument is Unset(). Destructive calls to GetParent() are allowed, i.e.:

BEntry entry("/boot/home/fido");
status_t err;
char name[B_FILE_NAME_LENGTH];
 
// Spit out the path components backwards, one at a time.
do {
    entry.GetName(name);
    printf("> %s\n", name);
} while ((err=entry.GetParent(&entry)) == B_OK);
 
// Complain for reasons other than reaching the top.
if (err != B_ENTRY_NOT_FOUND)
    printf(">> Error: %s\n", strerror(err));

will output:

> fido
> home
> boot
> .

Parameters

entry

A pointer to a pre-allocated BEntry object into which the result is stored.

Returns

A status code.

Return values

B_OK	Success
B_ENTRY_NOT_FOUND	Attempted to get the parent of the root directory.

Since

BeOS R3

GetPath()

status_t BEntry::GetPath

(

BPath *

path

)

const

Gets the path for the BEntry.

Parameters

path	A pointer to a pre-allocated BPath object into which the result is copied.

Returns

B_OK on success, or an error code on failure.

Since

BeOS R3

GetRef()

status_t BEntry::GetRef

(

entry_ref *

ref

)

const

Gets an entry_ref structure for the BEntry.

Parameters

ref	A pointer to a preallocated entry_ref object into which the result is copied.

Returns

B_OK on success, or an error code on failure.

Since

BeOS R3

GetStat()

status_t BEntry::GetStat ( struct stat *  result ) const

virtual

Fills in a stat structure for the entry.

The information is copied into the stat structure pointed to by result.

Note

The BStatable object does not cache the stat structure – each time you call GetStat() fresh stat information is retrieved.

Parameters

result

A pointer to a pre-allocated structure into which the stat information is copied.

Returns

B_OK on success, or an error code on failure.

Since

BeOS R3

Implements BStatable.

InitCheck()

status_t BEntry::InitCheck

(

)

const

Returns the result of the most recent construction or SetTo() call.

Returns

A status code.

Return values

B_OK	Success
B_NO_INIT	The object has been Unset() or is uninitialized.

Since

BeOS R3

MoveTo()

status_t BEntry::MoveTo	(	BDirectory *	dir,
		const char *	path = NULL,
		bool	clobber = false
	)

Moves the BEntry to directory or directory and path combination, replacing an existing entry if clobber is true.

Note

The BEntry object must refer to an existing file, if it is abstract, this method will fail.

Parameters

dir	A pointer to a pre-allocated BDirectory into which the entry should be moved.
path	(optional) new leaf name for the entry. May be a simple leaf or a relative path; either way, path is reckoned off of dir. If NULL, the entry retains its previous leaf name.
clobber	If false and an entry already exists at the specified Spdestination, the method will fail. If true and such an entry exists, it will be overwritten.

Returns

A status code.

Return values

B_OK	Success
B_ENTRY_EXISTS	The new location already exists and clobber is false.
B_ENTRY_NOT_FOUND	Attempted to rename an abstract entry.

Since

BeOS R3

operator!=()

bool BEntry::operator!=

(

const BEntry &

item

)

const

Returns false if the BEntry and item refer to the same entry or if they are both uninitialized.

Returns

Whether or not the items do NOT refer to the same entry.

Return values

true	The BEntry objects refer to different entries.
false	Both BEntry objects refer to the same entry or they are both uninitialized.

Since

BeOS R3

operator=()

BEntry & BEntry::operator=

(

const BEntry &

item

)

Reinitializes the BEntry to be a copy of item.

Returns

A pointer to the copy.

Since

BeOS R3

operator==()

bool BEntry::operator==

(

const BEntry &

item

)

const

Returns true if the BEntry and item refer to the same entry or if they are both uninitialized.

Returns

Whether or not the items refer to the same entry.

Return values

true	Both BEntry objects refer to the same entry or they are both uninitialized.
false	The BEntry objects refer to different entries.

Since

BeOS R3

Remove()

status_t BEntry::Remove

(

)

Removes the entry from the file system.

Note

If any file descriptors are open on the file when Remove() is called the chunk of data they refer to will continue to exist until all such file descriptors are closed. The BEntry object, however, becomes abstract and no longer refers to any actual data in the filesystem.

Returns

B_OK on success, or an error code on failure.

Since

BeOS R3

Rename()

status_t BEntry::Rename	(	const char *	path,
		bool	clobber = false
	)

Renames the BEntry to path replacing an existing entry if clobber is true.

Note

The BEntry object must refer to an existing file, if it is abstract, this method will fail.

Parameters

path	A pointer to a string containing the new name for the entry. It may be an absolute or relative path. If it is a relative path the entry is renamed within its current directory.
clobber	If false and a file with the name given by path already exists, the method will fail. If true and such a file exists, it will be overwritten.

Returns

A status code.

Return values

B_OK	Success
B_ENTRY_EXISTS	The new location already exists and clobber is false.
B_ENTRY_NOT_FOUND	Attempted to rename an abstract entry.

Since

BeOS R3

SetTo() [1/3]

status_t BEntry::SetTo	(	const BDirectory *	dir,
		const char *	path,
		bool	traverse = false
	)

Reinitializes the BEntry to the path or directory path combination, resolving symlinks if traverse is true.

Parameters

dir	The base directory in which the path resides.
path	Relative path based off of dir.
traverse	Whether or not to traverse symbolic links.

Returns

B_OK on success, or an error code on failure.

Since

BeOS R3

SetTo() [2/3]

status_t BEntry::SetTo	(	const char *	path,
		bool	traverse = false
	)

Reinitializes the BEntry object to the path, resolving symlinks if traverse is true.

Parameters

path	The path of the file.
traverse	Whether or not symlinks are to be traversed.

Returns

B_OK on success, or an error code on failure.

See also

BEntry::BEntry(const char* path, bool traverse)

Since

BeOS R3

SetTo() [3/3]

status_t BEntry::SetTo	(	const entry_ref *	ref,
		bool	traverse = false
	)

Reinitializes the BEntry to the passed in entry_ref object resolving symlinks if traverse is true.

Parameters

ref	The entry_ref referring to the given file.
traverse	Whether or not symlinks are to be traversed.

Returns

B_OK on success, or an error code on failure.

See also

BEntry::BEntry(const entry_ref* ref, bool traverse)

Since

BeOS R3

Unset()

void BEntry::Unset

(

)

Reset the BEntry to the uninitialized state.

The BEntry forgets any information about the entry it was referencing. Any attempt to get information from it after this will return B_NO_INIT. The BEntry can later be pointed to another entry using SetTo().

Since

BeOS R3