Derived from: BNode, BPositionIO
Declared in: be/StorageKit/File.h
Library: libbe.so
A BFile lets you read and write the data portion of a file. It does this by implementing the Read() /Write() and ReadAt()/ WriteAt() functions that are declared by the BPositionIO (protocol) class.
When you construct (or otherwise initialize) a BFile, the file is automatically opened. The file is closed when you re-initialize or destroy the object.
At each initialization, you're asked to supply an "open mode" value. this is a combination of flags that tells the object whether you want to read and/or write the file, create it if it doesn't exist, truncate it, and so on.
You can also initialize a BFile, and create a new file at the same time, through BDirectory's CreateFile() function. In this case, you don't have to supply an open mode --the BFile that's returned to you will automatically be open for reading and writing.
Although BFiles are meant to be used to access regular files, you aren't prevented from opening and reading a directory (you won't be able to write the directory, however). This isn't exactly a feature--there's not much reason to access a directory this way-- you should simply be aware that it's not an error.
Symbolic links, however, can't be opened by a BFile --not because it's illegal, but because...
![]() |
If you ask to open a symbolic link, the link is automatically traversed. The node that the BFile ends up opening will be the file or directory that the link points to. |
This is a feature; very few applications should ever want to look at a symbolic link. (If yours is one of the few that does want to, you should go visit the BSymLink class.)
BFile(void) BFile(const BFile &file) BFile(const entry_ref *ref, uint32 openMode) BFile(const BEntry *entry, uint32 openMode) BFile(const char *path, uint32 openMode) BFile(BDirectory *dir, const char *path, uint32 openMode)
Creates a new BFile object, initializes it according to the arguments, and sets InitCheck() to return the status of the initialization.
The default constructor does nothing and sets InitCheck() to B_NO_INIT. To initialize the object, call SetTo().
The copy constructor creates a new BFile that's open on the same file as that of the argument. Note that the two objects maintain separate data pointers into the same file:
![]() |
Separate pointers: Read and writing through one object
does not affect the position of the data pointer in the other object.
| |
![]() |
Same file: If one object writes to the file, the other object will see the written data. |
For information on the other constructors, see the analogous SetTo() functions.
virtual ~BFile()
Closes the object's file and destroys the object.
status_t GetSize(off_t size) const status_t SetSize(off_t &size)
These functions, which are inherited from and implemented by BStatable, get and set the size, in bytes, of the object's file.
Enlarging a file adds NULL bytes to its end. Shrinking a file removes bytes from the end.
status_t InitCheck(void) const
Returns the status of the most recent initialization.
bool IsReadable(void) const bool IsWritable(void) const
These functions tell you whether the BFile was initialized to read or write its file. If the object isn't (properly) initialized, they both return false.
Note that these functions don't query the actual file to check permissions, they only tell you what the access request was when the BFile object was last initialized.
ssize_t Read(void *buffer, size_t size) ssize_t ReadAt(off_t location, void *buffer, size_t size) ssize_t Write(const void *buffer, size_t size) ssize_t WriteAt(off_t location, const void *buffer, size_t size)
These functions, which are inherited from BPositionIO, read and write the file's data; note that they don't touch the file's attributes.
The Read() and ReadAt() functions read size bytes of data from the file and place this data in buffer . The buffer that buffer points to must already be allocated, and must be large enough to accommodate the read data. Note that...
![]() |
The read-into buffer is not null-terminated by the reading functions. |
The two functions differ in that...
Write() and WriteAt() write size bytes of data into the file; the data is taken from the buffer argument. The two functions differ in their use (or non-use) of the file's data pointer in the same manner as Read() and ReadAt().
The functions return the number of bytes that were actually read or written; negative return values indicate an error.
Reading fewer-than-size bytes isn't uncommon--consider the case where the file is smaller than the size of your buffer. If you want your buffer to be NULL -terminated, you can use the return value to set the NULL :
char buf[1024]; ssize_t amt_read; if ((amt_read = file.Read((void *)buf, 1024)) < 0) /* handle errors first */ else /* otherwise set null */ buf[amt_read] = '\\0';
A successful Write() or WriteAt() , on the other hand, will always write exactly the number of bytes you requested. In other words, Write() returns either the size value that you passed to it, or else it returns a negative (error) value.
RETURN VALUES
off_t Seek(off_t offset, int32 seekMode) off_t Position(void) const
Seek() sets the location of the file's data pointer. The new location is reckoned as offset bytes from the position given by seekMode :
It's not an error to seek beyond the end of the file:
![]() |
If you Seek() to a position that's past the end of the file and then do a Write(), the file will be extended (padded with garbage) from the old end of file to the Seek()'d position. If you don't follow the Seek() with a Write() , the file isn't extended. |
The function returns the new position as measured (in bytes) from the beginning of the file.
Position() returns the current position as measured (in bytes) from the beginning of the file. It doesn't move the pointer.
RETURN VALUES
![]() |
Note that if you do a "before the beginning" seek, subsequent Read() and Write() calls do not fail. But they almost certainly aren't doing what you want (you shouldn't be "before the file," anyway). The moral: Always check your Seek() return. |
status_t SetTo(const entry_ref *ref, uint32 openMode) status_t SetTo(const BEntry *entry, uint32 openMode) status_t SetTo(const char *path, uint32 openMode) status_t SetTo(BDirectory *dir, const char *path, uint32 openMode) void Unset(void)
Closes the BFile's current file (if any), and opens the file specified by the arguments. If the specified file is a symbolic link, the link is automatically traversed (recursively, if necessary). Note that you're not prevented from opening a directory as a BFile, but you are prevented from writing it.
openMode is a combination of flags that determines how the file is opened and what this object can do with it once it is open. There are two sets of flags; you must pass one (and only one) of the following "read/write" constants:
You can also pass any number of the following (these are optional):
To open a file for reading and writing, for example, you simply pass:
file.SetTo(entry, B_READ_WRITE);
Here we create a new file or erase its data if it already exists:
file.SetTo(entry, B_READ_WRITE | B_CREATE_FILE | B_ERASE_FILE);
And here we create a new file, but only if it doesn't already exist:
file.SetTo(entry, B_READ_WRITE | B_CREATE_FILE | B_FAIL_IF_EXISTS);
Unset() closes the object's file and sets its InitCheck() value to B_NO_INIT .
RETURN VALUES
BFile& operator=(const BFile &File)
In the expression
BFile a = b;
BFile a is initialized to refer to the same file as b. To gauge the success of the assignment, you should call InitCheck() immediately afterwards. You can't assign a BFile to itself (B_BAD_VALUE).
Assigning to an unitinitialized BFile is "successful": The assigned-to BFile will also be uninitialized (B_NO_INIT).
bool operator == (const BFile &file) const bool operator != (const BFile &file) const
Two BFile objects are said to be equal if they refer to the same file, or if they both refer to nothing.
The Be Book, HTML Edition, for Developer Release 9 of the Be OS.
Copyright © 1997 Be, Inc. All rights reserved.
Be, the Be logo, BeBox, BeOS, BeWare, and GeekPort are trademarks of Be, Inc.
Last modified