BFile Class Reference

#include <File.h>

Inheritance diagram for BFile:

Detailed Description

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 class.

and Opening InitializingAndOpening

: 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. (You are asked if you want the creation to fail if the named file already exists.)

Access to Directories and Symbolic Links

: 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 need to look at a symbolic link. (If yours is one of the few that does want to, you should go visit the BSymLink class.)

openMode Flags

: open_mode 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:

Constant	Meaning
B_READ_ONLY	This object can read, but not write, the file.
B_WRITE_ONLY	This object can write, but not read, the file.
B_READ_WRITE	This object can read and write the file.

: You can also pass any number of the following (these are optional):

Constant	Meaning
B_CREATE_FILE	Create the file if it doesn't already exist.
B_FAIL_IF_EXISTS	If the file already exists, the initialization (of the BFile object) fails.
B_ERASE_FILE	If the file already exists, erase all its data and attributes.
B_OPEN_AT_END	Sets the data pointer to point to the end of the file.

SetTo() Examples

: 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);

Public Member Functions

BFile ()

BFile (const entry_ref *ref, uint32 open_mode)

BFile (const BEntry *entry, uint32 open_mode)

BFile (const char *path, uint32 open_mode)

BFile (const BDirectory *dir, const char *path, uint32 open_mode)

BFile (const BFile &file)

virtual ~BFile ()

status_t SetTo (const entry_ref *ref, uint32 open_mode)

status_t SetTo (const BEntry *entry, uint32 open_mode)

status_t SetTo (const char *path, uint32 open_mode)

status_t SetTo (const BDirectory *dir, const char *path, uint32 open_mode)

bool IsReadable () const

bool IsWritable () const

virtual ssize_t Read (void *buffer, size_t size)

virtual ssize_t ReadAt (off_t pos, void *buffer, size_t size)

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

virtual ssize_t WriteAt (off_t pos, const void *buffer, size_t size)

virtual off_t Seek (off_t position, uint32 seek_mode)

virtual off_t Position () const

virtual status_t SetSize (off_t size)

virtual ssize_t MetaWrite (const char *in_name, type_code in_type, int32 in_index, off_t in_offset, const void *in_buf, size_t in_size)

virtual ssize_t MetaRead (const char *in_name, type_code in_type, int32 in_index, off_t in_offset, void *out_buf, size_t in_size) const

virtual status_t MetaRemove (const char *in_name, int32 in_index)

virtual status_t MetaGetInfo (const char *in_name, int32 in_index, meta_info *out_info, BString *out_name, void **inout_cookie) const

BFile & operator= (const BFile &file)

Constructor & Destructor Documentation

BFile ( )

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().

BFile ( const entry_ref * ref,

uint32 open_mode

)

Creates a new BFile object, initializes it according to the arguments, and sets InitCheck() to return the status of the initialization.

See also:
the analogous SetTo() functions.

BFile ( const BEntry * entry,

uint32 open_mode

)

Creates a new BFile object, initializes it according to the arguments, and sets InitCheck() to return the status of the initialization.

See also:
the analogous SetTo() functions.

BFile ( const char * path,

uint32 open_mode

)

Creates a new BFile object, initializes it according to the arguments, and sets InitCheck() to return the status of the initialization.

See also:
the analogous SetTo() functions.

BFile ( const BDirectory * dir,

const char * path,

uint32 open_mode

)

Creates a new BFile object, initializes it according to the arguments, and sets InitCheck() to return the status of the initialization.

See also:
the analogous SetTo() functions.

BFile ( const BFile & file )

Creates a new BFile object, initializes it according to the arguments, and sets InitCheck() to return the status of the initialization.
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: Reading 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.

~BFile ( ) [virtual]

Closes the object's file, frees its file descriptor, and destroys the object.

Member Function Documentation

bool IsReadable ( ) const

This function tell you whether the BFile was initialized to read its file. If the object isn't (properly) initialized, they both return false.
Note that this function don't query the actual file to check permissions, they only tell you what the access request was when the BFile object was initialized.

bool IsWritable ( ) const

These functions tell you whether the BFile was initialized to write its file. If the object isn't (properly) initialized, they both return false.
Note that this function don't query the actual file to check permissions, they only tell you what the access request was when the BFile object was initialized.

status_t MetaGetInfo ( const char * in_name,

int32 in_index,

meta_info * out_info,

BString * out_name,

void ** inout_cookie

) const [virtual]

Reimplemented from BDataIO.

ssize_t MetaRead ( const char * in_name,

type_code in_type,

int32 in_index,

off_t in_offset,

void * out_buf,

size_t in_size

) const [virtual]

Reimplemented from BDataIO.

status_t MetaRemove ( const char * in_name,

int32 in_index

) [virtual]

Reimplemented from BDataIO.

ssize_t MetaWrite ( const char * in_name,

type_code in_type,

int32 in_index,

off_t in_offset,

const void * in_buf,

size_t in_size

) [virtual]

Reimplemented from BDataIO.

BFile & operator= ( const BFile & file )

Assignment operator
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 uninitialized BFile is "successful": The assigned-to BFile will also be uninitialized (B_NO_INIT).

off_t Position ( void ) const [virtual]

Returns:
The current position as measured (in bytes) from the beginning of the file. It doesn't move the pointer.
B_ERROR. You called Position() after such a Seek().
B_BAD_FILE. Position() called on an uninitialized file.

Implements BPositionIO.

ssize_t Read ( void * buf,

size_t numBytes

) [virtual]

This function, which are inherited from BPositionIO, read the file's data; note that they don't touch the file's attributes.
The Read() function read param_ref numBytes bytes of data from the file and place this data in buf. The buffer that buf 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.
Read() reads the data starting at the current location of the file's data pointer, and increments the file pointer as it reads.

Returns:
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.

Note:
Error codes returned by these functions can vary depending on the file system handling the operation. For this reason, specific error codes aren't listed here.

Reimplemented from BPositionIO.

ssize_t ReadAt ( off_t pos,

void * buf,

size_t numBytes

) [virtual]

This function, which are inherited from BPositionIO, read the file's data; note that they don't touch the file's attributes.
The Read() function read param_ref numBytes bytes of data from the file and place this data in buf. The buffer that buf 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.
ReadAt() reads the data from the location specified by the pos argument, which is taken as a measure in bytes from the beginning of the file. ReadAt() does not bump the file's data pointer.

Returns:
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.

Note:
Error codes returned by these functions can vary depending on the file system handling the operation. For this reason, specific error codes aren't listed here.

Implements BPositionIO.

off_t Seek ( off_t pos,

uint32 seek_mode

) [virtual]

Sets the location of the file's data pointer. The new location is reckoned as pos bytes from the position given by the seek_mode constant:

Constant Meaning

SEEK_SET Seek from the beginning of the file.

SEEK_CUR Seek from the pointer's current position.

SEEK_END Seek from 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.

Returns:
The new position as measured (in bytes) from the beginning of the file.
B_ERROR. Attempted to Seek() "before" the beginning of the file.
B_ERROR If you call Seek() on an uninitialized file.

Attention:
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.

Implements BPositionIO.

status_t SetSize ( off_t size ) [virtual]

This function set the size, in bytes, of the object's file.
SetSize() sets the size of the data portion to the size given by the argument:

Enlarging a file adds (uninitialized) bytes to its end.

Shrinking a file removes bytes from the end.

Parameters:

size File size

Returns:
B_OK. The file's size was successfully gotten or set.
B_NOT_ALLOWED. The file lives on a read-only volume.
B_DEVICE_FULL. No more room on the file's device.

Reimplemented from BPositionIO.

status_t SetTo ( const BDirectory * dir,

const char * path,

uint32 open_mode

)

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.
In the path function, path can be absolute or relative, and can contain "." and ".." elements. If path is relative, it's reckoned off of the current working directory.

Parameters:

path Path string

open_mode Is a combination of flags that determines how the file is opened and what this object can do with it once it is open. openMode Flags

SetTo() Examples

Returns:
B_OK. The file was successfully opened.
B_BAD_VALUE.NULL path in dir/path, or some other argument is uninitialized.
B_ENTRY_NOT_FOUND. File not found, or couldn't create the file.
B_FILE_EXISTS. File exists (and you set B_FAIL_IF_EXISTS).
B_PERMISSION_DENIED. Read or write permission request denied.
B_NO_MEMORY. Couldn't allocate necessary memory to complete the operation.

status_t SetTo ( const char * path,

uint32 open_mode

)

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.
In the path function, path can be absolute or relative, and can contain "." and ".." elements. If path is relative, it's reckoned off of the current working directory.

Parameters:

path Path string

open_mode Is a combination of flags that determines how the file is opened and what this object can do with it once it is open. openMode Flags

See SetTo() Examples

Returns:
B_OK. The file was successfully opened.
B_BAD_VALUE.NULL path in path, or some other argument is uninitialized.
B_ENTRY_NOT_FOUND. File not found, or couldn't create the file.
B_FILE_EXISTS. File exists (and you set B_FAIL_IF_EXISTS).
B_PERMISSION_DENIED. Read or write permission request denied.
B_NO_MEMORY. Couldn't allocate necessary memory to complete the operation.

status_t SetTo ( const BEntry * entry,

uint32 open_mode

)

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.

Parameters:

entry BEntry object

open_mode Is a combination of flags that determines how the file is opened and what this object can do with it once it is open. openMode Flags

See SetTo() Examples

Returns:
B_OK. The file was successfully opened.
B_BAD_VALUE.some other argument is uninitialized.
B_ENTRY_NOT_FOUND. File not found, or couldn't create the file.
B_FILE_EXISTS. File exists (and you set B_FAIL_IF_EXISTS).
B_PERMISSION_DENIED. Read or write permission request denied.
B_NO_MEMORY. Couldn't allocate necessary memory to complete the operation.

status_t SetTo ( const entry_ref * ref,

uint32 open_mode

)

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.

Parameters:

ref entry_ref structure

open_mode Is a combination of flags that determines how the file is opened and what this object can do with it once it is open. openMode Flags

See SetTo() Examples

Returns:
B_OK. The file was successfully opened.
B_BAD_VALUE.some other argument is uninitialized.
B_ENTRY_NOT_FOUND. File not found, or couldn't create the file.
B_FILE_EXISTS. File exists (and you set B_FAIL_IF_EXISTS).
B_PERMISSION_DENIED. Read or write permission request denied.
B_NO_MEMORY. Couldn't allocate necessary memory to complete the operation.

ssize_t Write ( const void * buf,

size_t numBytes

) [virtual]

These functions, which are inherited from BPositionIO, write the file's data; note that they don't touch the file's attributes.
Write() write numBytes bytes of data into the file; the data is taken from the buf argument. The two functions differ in their use (or non-use) of the file's data pointer in the same manner as Read().

Returns:
The number of bytes that were actually read or written; negative return values indicate an error.
A successful Write(), on the other hand, will always write exactly the number of bytes you requested. In other words, Write() returns either the numBytes value that you passed to it, or else it returns a negative (error) value.

Note:
Error codes returned by these functions can vary depending on the file system handling the operation. For this reason, specific error codes aren't listed here.

Reimplemented from BPositionIO.

ssize_t WriteAt ( off_t pos,

const void * buf,

size_t numBytes

) [virtual]

These functions, which are inherited from BPositionIO, write the file's data; note that they don't touch the file's attributes.
WriteAt() write numBytes bytes of data into the file; the data is taken from the buf argument. The two functions differ in their use (or non-use) of the file's data pointer in the same manner as ReadAt().

Returns:
The number of bytes that were actually read or written; negative return values indicate an error.
A successful Write(), on the other hand, will always write exactly the number of bytes you requested. In other words, Write() returns either the numBytes value that you passed to it, or else it returns a negative (error) value.

Note:
Error codes returned by these functions can vary depending on the file system handling the operation. For this reason, specific error codes aren't listed here.

Implements BPositionIO.


Public Member Functions
	BFile ()
	BFile (const entry_ref *ref, uint32 open_mode)
	BFile (const BEntry *entry, uint32 open_mode)
	BFile (const char *path, uint32 open_mode)
	BFile (const BDirectory dir, const char path, uint32 open_mode)
	BFile (const BFile &file)
virtual	~BFile ()
status_t	SetTo (const entry_ref *ref, uint32 open_mode)
status_t	SetTo (const BEntry *entry, uint32 open_mode)
status_t	SetTo (const char *path, uint32 open_mode)
status_t	SetTo (const BDirectory dir, const char path, uint32 open_mode)
bool	IsReadable () const
bool	IsWritable () const
virtual ssize_t	Read (void *buffer, size_t size)
virtual ssize_t	ReadAt (off_t pos, void *buffer, size_t size)
virtual ssize_t	Write (const void *buffer, size_t size)
virtual ssize_t	WriteAt (off_t pos, const void *buffer, size_t size)
virtual off_t	Seek (off_t position, uint32 seek_mode)
virtual off_t	Position () const
virtual status_t	SetSize (off_t size)
virtual ssize_t	MetaWrite (const char in_name, type_code in_type, int32 in_index, off_t in_offset, const void in_buf, size_t in_size)
virtual ssize_t	MetaRead (const char in_name, type_code in_type, int32 in_index, off_t in_offset, void out_buf, size_t in_size) const
virtual status_t	MetaRemove (const char *in_name, int32 in_index)
virtual status_t	MetaGetInfo (const char in_name, int32 in_index, meta_info out_info, BString out_name, void *inout_cookie) const
BFile &	operator= (const BFile &file)