Public Member Functions | List of all members
BFile Class Reference

Provides the ability to read and write the data of a file. More...

Inherits BNode, and BPositionIO.

Public Member Functions

 BFile ()
 Creates an uninitialized BFile object. More...
 
 BFile (const BFile &file)
 Creates a copy of the supplied BFile. More...
 
 BFile (const entry_ref *ref, uint32 openMode)
 Creates a BFile and initializes it to the file referred to by the supplied entry_ref and according to the specified open mode. More...
 
 BFile (const BEntry *entry, uint32 openMode)
 Creates a BFile and initializes it to the file referred to by the supplied BEntry and according to the specified open mode. More...
 
 BFile (const char *path, uint32 openMode)
 Creates a BFile and initializes it to the file referred to by the supplied path name and according to the specified open mode. More...
 
 BFile (const BDirectory *dir, const char *path, uint32 openMode)
 Creates a BFile and initializes it to the file referred to by the supplied path name relative to the specified BDirectory and according to the specified open mode. More...
 
virtual ~BFile ()
 Destroys the BFile object and frees all allocated resources. More...
 
virtual status_t GetSize (off_t *size) const
 Gets the size of the file. More...
 
bool IsReadable () const
 Reports whether or not the file is readable. More...
 
bool IsWritable () const
 Reports whether or not the file is writable. More...
 
BFileoperator= (const BFile &file)
 Assigns another BFile to this BFile. More...
 
virtual off_t Position () const
 Gets the current read/write position within the file. More...
 
virtual ssize_t Read (void *buffer, size_t size)
 Read data from current position. More...
 
virtual ssize_t ReadAt (off_t location, void *buffer, size_t size)
 Reads a number of bytes from the file into a buffer. More...
 
virtual off_t Seek (off_t offset, uint32 seekMode)
 Seeks to another read/write position within the file. More...
 
virtual status_t SetSize (off_t size)
 Sets the size of the file. More...
 
status_t SetTo (const entry_ref *ref, uint32 openMode)
 Re-initializes the BFile to the file referred to by the supplied entry_ref and according to the specified open mode. More...
 
status_t SetTo (const BEntry *entry, uint32 openMode)
 Re-initializes the BFile to the file referred to by the supplied BEntry and according to the specified open mode. More...
 
status_t SetTo (const char *path, uint32 openMode)
 Re-initializes the BFile to the file referred to by the supplied path name and according to the specified open mode. More...
 
status_t SetTo (const BDirectory *dir, const char *path, uint32 openMode)
 Re-initializes the BFile to the file referred to by the supplied path name relative to the specified BDirectory and according to the specified open mode. More...
 
virtual ssize_t Write (const void *buffer, size_t size)
 Writes a number of bytes from a buffer into the file. More...
 
virtual ssize_t WriteAt (off_t location, const void *buffer, size_t size)
 Writes a number of bytes from a buffer at a certain position into the file. More...
 
- Public Member Functions inherited from BNode
 BNode ()
 Creates an uninitialized BNode object. More...
 
 BNode (const entry_ref *ref)
 Creates a BNode object and initializes it to the specified entry_ref. More...
 
 BNode (const BEntry *entry)
 Creates a BNode object and initializes it to the specified filesystem entry. More...
 
 BNode (const char *path)
 Creates a BNode object and initializes it to the entry referred to by the specified path. More...
 
 BNode (const BDirectory *dir, const char *path)
 Creates a BNode object and initializes it to the entry referred to by the specified path rooted in the specified directory. More...
 
 BNode (const BNode &node)
 Creates a copy of the given BNode. More...
 
virtual ~BNode ()
 Frees all resources associated with the BNode. More...
 
int Dup ()
 Gets the POSIX file descriptor referred to by this node. More...
 
virtual status_t GetStat (struct stat *st) const
 Fills in the given stat structure with the stat() information for this object. More...
 
status_t InitCheck () const
 Checks whether the object has been properly initialized or not. More...
 
status_t SetTo (const entry_ref *ref)
 Initializes the object to the specified entry_ref. More...
 
status_t SetTo (const BEntry *entry)
 Initializes the object to the specified filesystem entry. More...
 
status_t SetTo (const char *path)
 Initializes the object to the specified path. More...
 
status_t SetTo (const BDirectory *dir, const char *path)
 Initializes the object to the entry referred by the specified path relative to the the specified directory. More...
 
void Unset ()
 Returns the object to an uninitialized state. More...
 
status_t Lock ()
 Attains an exclusive lock on the data referred to by this node so that it may not be modified by any other objects or methods. More...
 
status_t Unlock ()
 Unlocks the date referred to by this node. More...
 
status_t Sync ()
 Immediately performs any pending disk actions on the node. More...
 
ssize_t WriteAttr (const char *name, type_code type, off_t offset, const void *buffer, size_t length)
 Writes data from a buffer to an attribute. More...
 
ssize_t ReadAttr (const char *name, type_code type, off_t offset, void *buffer, size_t length) const
 Reads data from an attribute into buffer. More...
 
status_t RemoveAttr (const char *name)
 Deletes the attribute given by name. More...
 
status_t RenameAttr (const char *oldName, const char *newName)
 Moves the attribute given by oldName to newName. More...
 
status_t GetAttrInfo (const char *name, struct attr_info *info) const
 Fills in the pre-allocated attr_info struct pointed to by info with information about the attribute specified by name. More...
 
status_t GetNextAttrName (char *buffer)
 Copies the name of the attribute into buffer and then advances the pointer to the next attribute. More...
 
status_t RewindAttrs ()
 Resets the object's attribute pointer to the first attribute in the list. More...
 
status_t WriteAttrString (const char *name, const BString *data)
 Writes the specified string to the specified attribute, clobbering any previous data. More...
 
status_t ReadAttrString (const char *name, BString *result) const
 Reads the data of the specified attribute into the pre-allocated result. More...
 
BNodeoperator= (const BNode &node)
 Initializes the object as a copy of other. More...
 
bool operator== (const BNode &node) const
 Tests whether this and the supplied BNode object are equal. More...
 
bool operator!= (const BNode &node) const
 Tests whether this and the supplied BNode object are not equal. More...
 
- Public Member Functions inherited from BStatable
status_t GetAccessTime (time_t *atime) const
 Fills out atime with the access time of the node. More...
 
status_t GetCreationTime (time_t *ctime) const
 Fills out ctime with the creation time of the node. More...
 
status_t GetGroup (gid_t *group) const
 Fills out the node's GID into group. More...
 
status_t GetModificationTime (time_t *mtime) const
 Fills out mtime with the last modification time of the node. More...
 
status_t GetNodeRef (node_ref *ref) const
 Fills out ref with the node_ref of the node. More...
 
status_t GetOwner (uid_t *owner) const
 Fills out the node's UID into owner. More...
 
status_t GetPermissions (mode_t *permissions) const
 Fills out perms with the permissions of the node. More...
 
status_t GetSize (off_t *size) const
 Fills out the size of the node's data (not counting attributes) into size. More...
 
status_t GetVolume (BVolume *volume) const
 Fills out vol with the the volume that the node lives on. More...
 
bool IsDirectory () const
 Returns whether or not the node is a directory. More...
 
bool IsFile () const
 Returns whether or not the node is a file. More...
 
bool IsSymLink () const
 Returns whether or not the node is a symbolic link. More...
 
status_t SetAccessTime (time_t atime)
 Sets the node's access time to atime. More...
 
status_t SetCreationTime (time_t ctime)
 Sets the node's creation time to ctime. More...
 
status_t SetGroup (gid_t group)
 Sets the node's GID to group. More...
 
status_t SetModificationTime (time_t mtime)
 Sets the node's last modification time to mtime. More...
 
status_t SetOwner (uid_t owner)
 Sets the node's UID to owner. More...
 
status_t SetPermissions (mode_t permissions)
 Sets the node's permissions to perms. More...
 
- Public Member Functions inherited from BPositionIO
 BPositionIO ()
 This constructor does nothing. More...
 
virtual ~BPositionIO ()
 This destructor does nothing. More...
 
status_t ReadAtExactly (off_t position, void *buffer, size_t size, size_t *_bytesRead=NULL)
 Reads an exact amount of data from the object at the specified position into a buffer. More...
 
status_t WriteAtExactly (off_t position, const void *buffer, size_t size, size_t *_bytesWritten=NULL)
 Writes an exact amount of data from a buffer to the object at the specified position. More...
 
- Public Member Functions inherited from BDataIO
 BDataIO ()
 This constructor does nothing. More...
 
virtual ~BDataIO ()
 This destructor does nothing. More...
 
virtual status_t Flush ()
 Writes pending data to underlying storage. More...
 
status_t ReadExactly (void *buffer, size_t size, size_t *_bytesRead=NULL)
 Reads an exact amount of data from the object into a buffer. More...
 
status_t WriteExactly (const void *buffer, size_t size, size_t *_bytesWritten=NULL)
 Writes an exact amount of data from a buffer to the object. More...
 

Detailed Description

Provides the ability to read and write the data of a file.

The file is automatically opened when you initialize a BFile and is automatically closed when you re-initialize or destroy the object.

Symbolic links are automatically transversed by opening a BFile. The node that the BFile ends up opening will be the file or directory that the link points to, not the symbolic link file itself.

Since
BeOS R3

Constructor & Destructor Documentation

◆ BFile() [1/6]

BFile::BFile ( )

◆ BFile() [2/6]

BFile::BFile ( const BFile file)

Creates a copy of the supplied BFile.

If file is uninitialized, the newly constructed BFile will be too.

Parameters
fileThe BFile object to be copied.
Since
BeOS R3

◆ BFile() [3/6]

BFile::BFile ( const entry_ref ref,
uint32  openMode 
)

Creates a BFile and initializes it to the file referred to by the supplied entry_ref and according to the specified open mode.

Parameters
refThe entry_ref referring to the file.
openModeThe mode in which the file should be opened.
See also
SetTo(const entry_ref* ref, uint32 openMode)
Since
BeOS R3

◆ BFile() [4/6]

BFile::BFile ( const BEntry entry,
uint32  openMode 
)

Creates a BFile and initializes it to the file referred to by the supplied BEntry and according to the specified open mode.

Parameters
entryThe BEntry referring to the file.
openModeThe mode in which the file should be opened.
See also
SetTo(const BEntry* entry, uint32 openMode)
Since
BeOS R3

◆ BFile() [5/6]

BFile::BFile ( const char *  path,
uint32  openMode 
)

Creates a BFile and initializes it to the file referred to by the supplied path name and according to the specified open mode.

Parameters
pathThe file's path name.
openModeThe mode in which the file should be opened.
See also
SetTo(const char* path, uint32 openMode)
Since
BeOS R3

◆ BFile() [6/6]

BFile::BFile ( const BDirectory dir,
const char *  path,
uint32  openMode 
)

Creates a BFile and initializes it to the file referred to by the supplied path name relative to the specified BDirectory and according to the specified open mode.

Parameters
dirThe BDirectory, relative to which the file's path name is given.
pathThe file's path name relative to dir.
openModeThe mode in which the file should be opened.
See also
SetTo(const BDirectory* dir, const char* path, uint32 openMode)
Since
BeOS R3

◆ ~BFile()

BFile::~BFile ( )
virtual

Destroys the BFile object and frees all allocated resources.

If the file is properly initialized, the file descriptor is closed.

Since
BeOS R3

Member Function Documentation

◆ GetSize()

status_t BFile::GetSize ( off_t *  size) const
virtual

Gets the size of the file.

Parameters
sizeThe file size to fill out.
Returns
A status code.
See also
BStatable::GetSize()
Since
BeOS R3

Reimplemented from BPositionIO.

◆ IsReadable()

bool BFile::IsReadable ( ) const

Reports whether or not the file is readable.

Returns
  • true, if the BFile has been initialized properly and the file has been been opened for reading,
  • false, otherwise.
Since
BeOS R3

◆ IsWritable()

bool BFile::IsWritable ( ) const

Reports whether or not the file is writable.

Returns
  • true, if the BFile has been initialized properly and the file has been opened for writing,
  • false, otherwise.
Since
BeOS R3

◆ operator=()

BFile & BFile::operator= ( const BFile file)

Assigns another BFile to this BFile.

If the other BFile is uninitialized, this one will be too. Otherwise it will refer to the same file using the same mode, unless an error occurs.

Parameters
fileThe original BFile to assign from.
Returns
A reference to the assigned BFile.
Since
BeOS R3

◆ Position()

off_t BFile::Position ( ) const
virtual

Gets the current read/write position within the file.

Returns
The current read/write position relative to the beginning of the file or an error code.
Return values
B_ERRORAfter a Seek() before the beginning of the file.
B_FILE_ERRORThe file has not been initialized.
Since
BeOS R3

Implements BPositionIO.

◆ Read()

virtual ssize_t BFile::Read ( void *  buffer,
size_t  size 
)
virtual

Read data from current position.

This method is derived from BDataIO. The default implementation reads data from the current position of the cursor, pointed at by Position(). If you require different behaviour, please look at BDataIO::Read() for what is expected of this method.

Since
BeOS R3

Reimplemented from BPositionIO.

◆ ReadAt()

ssize_t BFile::ReadAt ( off_t  location,
void *  buffer,
size_t  size 
)
virtual

Reads a number of bytes from the file into a buffer.

ssize_t BFile::Read(void* buffer, size_t size)

Parameters
bufferThe buffer the data from the file shall be written to.
sizeThe number of bytes that shall be read.
Returns
The number of bytes read or an error code.
Since
BeOS R3

Reads a number of bytes from a certain position within the file into a buffer.

Parameters
locationThe position (in bytes) within the file from which the data shall be read.
bufferThe buffer the data from the file shall be written to.
sizeThe number of bytes that shall be read.
Returns
The number of bytes read or an error code.
Since
BeOS R3

Implements BPositionIO.

◆ Seek()

off_t BFile::Seek ( off_t  offset,
uint32  seekMode 
)
virtual

Seeks to another read/write position within the file.

It is allowed to seek past the end of the file. A subsequent call to Write() will pad the file with undefined data. Seeking before the beginning of the file will fail and the behavior of subsequent Read() or Write() invocations will be undefined.

Parameters
offsetNew read/write position, depending on seekMode relative to the beginning or the end of the file or the current position.
seekMode
  • SEEK_SET: move relative to the beginning of the file.
  • SEEK_CUR: move relative to the current position.
  • SEEK_END: move relative to the end of the file.
Returns
The new read/write position relative to the beginning of the file or an error code.
Return values
B_ERRORTrying to seek before the beginning of the file.
B_FILE_ERRORThe file is not properly initialized.
Since
BeOS R3

Implements BPositionIO.

◆ SetSize()

status_t BFile::SetSize ( off_t  size)
virtual

Sets the size of the file.

If the file is shorter than size bytes it will be padded with unspecified data to the requested size. If it is larger, it will be truncated.

Note
There's no problem with setting the size of a BFile opened in B_READ_ONLY mode, unless the file resides on a read only volume.
Parameters
sizeThe new file size.
Returns
A status code.
Return values
B_OKEverything went fine.
B_NOT_ALLOWEDTrying to set the size of a file on a read only volume.
B_DEVICE_FULLThere's not enough space left on the volume.
Since
BeOS R3

Reimplemented from BPositionIO.

◆ SetTo() [1/4]

status_t BFile::SetTo ( const entry_ref ref,
uint32  openMode 
)

Re-initializes the BFile to the file referred to by the supplied entry_ref and according to the specified open mode.

Parameters
refThe entry_ref referring to the file.
openModeThe mode in which the file should be opened openMode must be a bitwise or of exactly one of the flags.
  • B_READ_ONLY: The file is opened read only.
  • B_WRITE_ONLY: The file is opened write only.
  • B_READ_WRITE: The file is opened for random read/write access. and any number of the flags
  • B_CREATE_FILE: A new file will be created, if it does not already exist.
  • B_FAIL_IF_EXISTS: If the file does already exist and B_CREATE_FILE is set, SetTo() fails.
  • B_ERASE_FILE: An already existing file is truncated to zero size.
  • B_OPEN_AT_END: Seek() to the end of the file after opening.
Returns
A status code.
Return values
B_OKEverything went fine.
B_BAD_VALUENULL ref or bad openMode.
B_ENTRY_NOT_FOUNDFile not found or failed to create file.
B_FILE_EXISTSFile exists and B_FAIL_IF_EXISTS was passed.
B_PERMISSION_DENIEDFile permissions didn't allow operation.
B_NO_MEMORYInsufficient memory for operation.
B_LINK_LIMITIndicates a cyclic loop within the file system.
B_BUSYA node was busy.
B_FILE_ERRORA general file error.
B_NO_MORE_FDSThe application has run out of file descriptors.
Since
BeOS R3

◆ SetTo() [2/4]

status_t BFile::SetTo ( const BEntry entry,
uint32  openMode 
)

Re-initializes the BFile to the file referred to by the supplied BEntry and according to the specified open mode.

Parameters
entrythe BEntry referring to the file
openModethe mode in which the file should be opened
Returns
A status code.
Return values
B_OKEverything went fine.
B_BAD_VALUENULL entry or bad openMode.
B_ENTRY_NOT_FOUNDFile not found or failed to create file.
B_FILE_EXISTSFile exists and B_FAIL_IF_EXISTS was passed.
B_PERMISSION_DENIEDFile permissions didn't allow operation.
B_NO_MEMORYInsufficient memory for operation.
B_LINK_LIMITIndicates a cyclic loop within the file system.
B_BUSYA node was busy.
B_FILE_ERRORA general file error.
B_NO_MORE_FDSThe application has run out of file descriptors.
Since
BeOS R3

◆ SetTo() [3/4]

status_t BFile::SetTo ( const char *  path,
uint32  openMode 
)

Re-initializes the BFile to the file referred to by the supplied path name and according to the specified open mode.

Parameters
pathThe file's path name.
openModeThe mode in which the file should be opened.
Returns
A status code.
Return values
B_OKEverything went fine.
B_BAD_VALUENULL path or bad openMode.
B_ENTRY_NOT_FOUNDFile not found or failed to create file.
B_FILE_EXISTSFile exists and B_FAIL_IF_EXISTS was passed.
B_PERMISSION_DENIEDFile permissions didn't allow operation.
B_NO_MEMORYInsufficient memory for operation.
B_LINK_LIMITIndicates a cyclic loop within the file system.
B_BUSYA node was busy.
B_FILE_ERRORA general file error.
B_NO_MORE_FDSThe application has run out of file descriptors.
Since
BeOS R3

◆ SetTo() [4/4]

status_t BFile::SetTo ( const BDirectory dir,
const char *  path,
uint32  openMode 
)

Re-initializes the BFile to the file referred to by the supplied path name relative to the specified BDirectory and according to the specified open mode.

Parameters
dirThe BDirectory, relative to which the file's path name is given.
pathThe file's path name relative to dir.
openModeThe mode in which the file should be opened.
Returns
A status code.
Return values
B_OKEverything went fine.
B_BAD_VALUENULL dir or path or bad openMode.
B_ENTRY_NOT_FOUNDFile not found or failed to create file.
B_FILE_EXISTSFile exists and B_FAIL_IF_EXISTS was passed.
B_PERMISSION_DENIEDFile permissions didn't allow operation.
B_NO_MEMORYInsufficient memory for operation.
B_LINK_LIMITIndicates a cyclic loop within the file system.
B_BUSYA node was busy.
B_FILE_ERRORA general file error.
B_NO_MORE_FDSThe application has run out of file descriptors.
Since
BeOS R3

◆ Write()

ssize_t BFile::Write ( const void *  buffer,
size_t  size 
)
virtual

Writes a number of bytes from a buffer into the file.

Parameters
bufferThe buffer containing the data to be written to the file.
sizeThe number of bytes that shall be written.
Returns
The number of bytes actually written or an error code.
Since
BeOS R3

Reimplemented from BPositionIO.

◆ WriteAt()

ssize_t BFile::WriteAt ( off_t  location,
const void *  buffer,
size_t  size 
)
virtual

Writes a number of bytes from a buffer at a certain position into the file.

Parameters
locationThe position (in bytes) within the file at which the data shall be written.
bufferThe buffer containing the data to be written to the file.
sizeThe number of bytes that shall be written.
Returns
The number of bytes actually written or an error code.
Since
BeOS R3

Implements BPositionIO.