SourcePro® API Reference Guide

 
List of all members | Public Member Functions | Static Public Member Functions

Represents an abstraction of a filesystem regular file. More...

#include <rw/rwfile.h>

Inheritance diagram for RWFile:
RWFileManager

Public Member Functions

 RWFile (const char *filename, const char *mode=0, bool large_file=false)
 
 ~RWFile ()
 
const char * Access () const
 
void ClearErr ()
 
RWoffset CurOffset () const
 
RWoffset64 CurOffset64 () const
 
bool Eof () const
 
bool eof () const
 
bool Erase ()
 
bool Error () const
 
bool Exists () const
 
bool Flush ()
 
const char * GetName () const
 
FILE * GetStream () const
 
bool good () const
 
bool IsEmpty () const
 
bool isValid () const
 
bool Read (bool &i)
 
bool Read (char &c)
 
bool Read (short &i)
 
bool Read (int &i)
 
bool Read (long &i)
 
bool Read (unsigned char &c)
 
bool Read (wchar_t &w)
 
bool Read (unsigned short &i)
 
bool Read (unsigned int &i)
 
bool Read (unsigned long &i)
 
bool Read (float &f)
 
bool Read (double &s)
 
bool Read (long long &i)
 
bool Read (unsigned long long &i)
 
bool Read (long double &d)
 
bool Read (char *i, size_t n, int delim, size_t *count=0)
 
bool Read (bool *i, size_t n, size_t *count=0)
 
bool Read (char *i, size_t n, size_t *count=0)
 
bool Read (short *i, size_t n, size_t *count=0)
 
bool Read (int *i, size_t n, size_t *count=0)
 
bool Read (long *i, size_t n, size_t *count=0)
 
bool Read (wchar_t *i, size_t n, size_t *count=0)
 
bool Read (unsigned char *c, size_t n, size_t *count=0)
 
bool Read (unsigned short *i, size_t n, size_t *count=0)
 
bool Read (unsigned int *i, size_t n, size_t *count=0)
 
bool Read (unsigned long *i, size_t n, size_t *count=0)
 
bool Read (float *i, size_t n, size_t *count=0)
 
bool Read (double *i, size_t n, size_t *count=0)
 
bool Read (long long *i, size_t n, size_t *count=0)
 
bool Read (unsigned long long *i, size_t n, size_t *count=0)
 
bool Read (long double *i, size_t n, size_t *count=0)
 
bool Read (char *string)
 
bool SeekTo (RWoffset offset)
 
bool SeekTo64 (RWoffset64 offset)
 
bool SeekToBegin ()
 
bool SeekToEnd ()
 
bool Write (bool i)
 
bool Write (char i)
 
bool Write (short i)
 
bool Write (int i)
 
bool Write (long i)
 
bool Write (wchar_t i)
 
bool Write (unsigned char i)
 
bool Write (unsigned short i)
 
bool Write (unsigned int i)
 
bool Write (unsigned long i)
 
bool Write (float f)
 
bool Write (double d)
 
bool Write (long long i)
 
bool Write (unsigned long long i)
 
bool Write (long double d)
 
bool Write (const char *string)
 
bool Write (const bool *i, size_t count)
 
bool Write (const short *i, size_t count)
 
bool Write (const int *i, size_t count)
 
bool Write (const long *i, size_t count)
 
bool Write (const wchar_t *i, size_t count)
 
bool Write (const unsigned char *c, size_t N)
 
bool Write (const unsigned short *i, size_t N)
 
bool Write (const unsigned int *i, size_t N)
 
bool Write (const unsigned long *i, size_t N)
 
bool Write (const float *i, size_t count)
 
bool Write (const double *i, size_t count)
 
bool Write (const char *string, size_t)
 
bool Write (const long long *i, size_t count)
 
bool Write (const unsigned long long *i, size_t count)
 
bool Write (const long double *i, size_t count)
 

Static Public Member Functions

static bool Exists (const char *filename)
 
static bool Exists (const char *filename, int mode)
 

Detailed Description

Class RWFile represents an abstraction of a filesystem regular file. The file is manipulated in binary mode by default. This class' interface is based on class PFile of the Interviews Class Library (1987, Stanford University). The member function names begin with upper case letters in order to maintain compatibility with class PFile.

If a function expects an RWFile to exist, your code should always check isValid() prior to calling that function. Failure to do so may cause a runtime error. For example:

RWFile aFile("filename");
//...
if(aFile.isValid() && ! aFile.Error()){
//...

Note that RWFile cannot anticipate or define the behavior of a program that calls any member function other than isValid() on an invalid RWFile object.

Synopsis
#include <rw/rwfile.h>
RWFile f("filename");
Persistence
None

Constructor & Destructor Documentation

RWFile::RWFile ( const char *  filename,
const char *  mode = 0,
bool  large_file = false 
)

Constructs an RWFile to be used with the file name filename and with mode mode. The mode string conforms to POSIX fopen modes (see http://www.opengroup.org/onlinepubs/009695399/functions/fopen.html).

If mode is zero (the default), then the constructor attempts to open an existing file with the given filename for update (fopen mode "rb+"). If this is not possible, then it attempts to create a new file with the given filename (fopen mode "wb+"). The resulting object should be checked for validity using the function isValid().

The last parameter large_file is used to determine if the file should be opened in large file mode. On systems that are large file enabled, this parameter is ignored, and the file is always opened in large file mode. The default is false for compatibility with older versions of SourcePro, meaning that the file is not opened in large file mode. For newer versions and applications, we recommend that you pass a value of true for the large_file parameter, and that all file positioning calls be done with the large file safe functions SeekToBegin(), SeekToEnd(), SeekTo64(), and CurOffset64().

Note
Because this class is intended to encapsulate binary operations, it is important that it open or create files in binary mode. If a file mode is not specified, or is a NULL pointer, the file is opened in binary mode. Using binary mode is particularly important on systems where text mode file streams and binary streams are different.
RWFile::~RWFile ( )

Performs any pending I/O operations and closes the file.

Member Function Documentation

const char* RWFile::Access ( ) const

Returns the access mode with which the underlying FILE* was opened.

void RWFile::ClearErr ( )

Resets error state so that neither Eof() nor Error() returns true.

RWoffset RWFile::CurOffset ( ) const

Returns the current position, in bytes from the start of the file, as a 32-bit integer. Returns -1 on error or if the file position is beyond the representable range of RWoffset. May be used with both small and very large (more than 2GB) files.

RWoffset64 RWFile::CurOffset64 ( ) const

Returns the current offset, in bytes from the start of the file, as a 64-bit integer. May be used with both small and very large (more than 2GB) files.

bool RWFile::Eof ( ) const

Returns true if an end-of-file has been reached.

bool RWFile::eof ( ) const
inline

Returns the results of the call to Eof().

bool RWFile::Erase ( )

Erases the contents but does not close the file. Returns true if the operation was successful.

bool RWFile::Error ( ) const

Returns true if a file I/O error has occurred. Before calling Error() you should call isValid() to determine if the file was opened/created successfully. Failure to do so could result in runtime errors.

bool RWFile::Exists ( ) const
inline

Returns true if the file exists.

static bool RWFile::Exists ( const char *  filename)
static

Returns true if a file with name filename exists.

static bool RWFile::Exists ( const char *  filename,
int  mode 
)
static

Returns true if a file with name filename exists and may be accessed according to the mode specified. The mode may be ORed together from one or more of:

Mode Meaning
F_OK Exists (Implied by any of the others)
X_OK Executable or searchable
W_OK Writable
R_OK Readable

If your compiler or operating system does not support the POSIX access() function, then mode X_OK always returns false.

bool RWFile::Flush ( )

Performs any pending I/O operations. Returns true if successful.

const char* RWFile::GetName ( ) const
inline

Returns the file name.

FILE* RWFile::GetStream ( ) const

Returns a non-null FILE pointer for a valid file. Provided for users who need to perform implementation-dependent operations on FILE. Any changes in the state of the FILE object may render the behavior of the corresponding RWFile object undefined.

bool RWFile::good ( ) const
inline

Returns true if the file was successfully opened, there are no I/O errors, and the EOF has not been reached.

bool RWFile::IsEmpty ( ) const

Returns true if the file contains no data, otherwise false, or on error.

bool RWFile::isValid ( ) const

Returns true if the file was successfully opened, otherwise false.

bool RWFile::Read ( bool &  i)

Reads the indicated built-in type. Returns true if the read is successful. If you are already at the end of a file, this is interpreted as successfully reading a null string, and returns true.

bool RWFile::Read ( char &  c)

Reads the indicated built-in type. Returns true if the read is successful. If you are already at the end of a file, this is interpreted as successfully reading a null string, and returns true.

bool RWFile::Read ( short &  i)

Reads the indicated built-in type. Returns true if the read is successful. If you are already at the end of a file, this is interpreted as successfully reading a null string, and returns true.

bool RWFile::Read ( int &  i)

Reads the indicated built-in type. Returns true if the read is successful. If you are already at the end of a file, this is interpreted as successfully reading a null string, and returns true.

bool RWFile::Read ( long &  i)

Reads the indicated built-in type. Returns true if the read is successful. If you are already at the end of a file, this is interpreted as successfully reading a null string, and returns true.

bool RWFile::Read ( unsigned char &  c)

Reads the indicated built-in type. Returns true if the read is successful. If you are already at the end of a file, this is interpreted as successfully reading a null string, and returns true.

bool RWFile::Read ( wchar_t &  w)

Reads the indicated built-in type. Returns true if the read is successful. If you are already at the end of a file, this is interpreted as successfully reading a null string, and returns true.

bool RWFile::Read ( unsigned short &  i)

Reads the indicated built-in type. Returns true if the read is successful. If you are already at the end of a file, this is interpreted as successfully reading a null string, and returns true.

bool RWFile::Read ( unsigned int &  i)

Reads the indicated built-in type. Returns true if the read is successful. If you are already at the end of a file, this is interpreted as successfully reading a null string, and returns true.

bool RWFile::Read ( unsigned long &  i)

Reads the indicated built-in type. Returns true if the read is successful. If you are already at the end of a file, this is interpreted as successfully reading a null string, and returns true.

bool RWFile::Read ( float &  f)

Reads the indicated built-in type. Returns true if the read is successful. If you are already at the end of a file, this is interpreted as successfully reading a null string, and returns true.

bool RWFile::Read ( double &  s)

Reads the indicated built-in type. Returns true if the read is successful. If you are already at the end of a file, this is interpreted as successfully reading a null string, and returns true.

bool RWFile::Read ( long long &  i)

Reads the indicated built-in type. Returns true if the read is successful. If you are already at the end of a file, this is interpreted as successfully reading a null string, and returns true.

Note
This function is available only if your compiler supports the long long type.
bool RWFile::Read ( unsigned long long &  i)

Reads the indicated built-in type. Returns true if the read is successful. If you are already at the end of a file, this is interpreted as successfully reading a null string, and returns true.

Note
This function is available only if your compiler supports the unsigned long long type.
bool RWFile::Read ( long double &  d)

Reads the indicated built-in type. Returns true if the read is successful. If you are already at the end of a file, this is interpreted as successfully reading a null string, and returns true.

Note
This function is available only if your compiler supports the long double type.
bool RWFile::Read ( char *  i,
size_t  n,
int  delim,
size_t *  count = 0 
)

Extracts characters from the file, storing each in consecutive elements of the array i until either n characters have been extracted, or if (delim != EOF), the character specified by delim has been extracted.

If the delimiter is reached before n characters are extracted, the delimiter terminates the array i; if the delimiter is EOF and is reached before n characters are extracted, the method null terminates the array i.

The parameter n is the maximum number of characters to read, and must be less than or equal to the size of the array pointed to by i. The delim parameter specifies a delimiter to use as a termination point for extraction. The value of delim must be a valid character converted to int, or EOF.

The optional parameter count is a pointer to the actual number of characters read by the function.

This function returns true if n bytes were read from the file, or the specified delimiter was reached.

Note
The caller is responsible for declaring and allocating the necessary storage for i and count (if used), before calling this function.
bool RWFile::Read ( bool *  i,
size_t  n,
size_t *  count = 0 
)

Reads n instances of the indicated built-in type into a block pointed to by i. Returns true if the read is successful.

The optional parameter count is a pointer to the actual number of characters read by the function.

Note
The caller is responsible for declaring and allocating the necessary storage for i and count (if used), before calling this function.
bool RWFile::Read ( char *  i,
size_t  n,
size_t *  count = 0 
)

Reads n instances of the indicated built-in type into a block pointed to by i. Returns true if the read is successful.

The optional parameter count is a pointer to the actual number of characters read by the function.

Note
The caller is responsible for declaring and allocating the necessary storage for i and count (if used), before calling this function.
If the caller passes 0 for count, the program will compile without any warnings and call Read(char*, size_t, int, size_t*).
bool RWFile::Read ( short *  i,
size_t  n,
size_t *  count = 0 
)

Reads n instances of the indicated built-in type into a block pointed to by i. Returns true if the read is successful.

The optional parameter count is a pointer to the actual number of characters read by the function.

Note
The caller is responsible for declaring and allocating the necessary storage for i and count (if used), before calling this function.
bool RWFile::Read ( int *  i,
size_t  n,
size_t *  count = 0 
)

Reads n instances of the indicated built-in type into a block pointed to by i. Returns true if the read is successful.

The optional parameter count is a pointer to the actual number of characters read by the function.

Note
The caller is responsible for declaring and allocating the necessary storage for i and count (if used), before calling this function.
bool RWFile::Read ( long *  i,
size_t  n,
size_t *  count = 0 
)

Reads n instances of the indicated built-in type into a block pointed to by i. Returns true if the read is successful.

The optional parameter count is a pointer to the actual number of characters read by the function.

Note
The caller is responsible for declaring and allocating the necessary storage for i and count (if used), before calling this function.
bool RWFile::Read ( wchar_t *  i,
size_t  n,
size_t *  count = 0 
)

Reads n instances of the indicated built-in type into a block pointed to by i. Returns true if the read is successful.

The optional parameter count is a pointer to the actual number of characters read by the function.

Note
The caller is responsible for declaring and allocating the necessary storage for i and count (if used), before calling this function.
bool RWFile::Read ( unsigned char *  c,
size_t  n,
size_t *  count = 0 
)
inline

Reads n instances of the indicated built-in type into a block pointed to by i. Returns true if the read is successful.

The optional parameter count is a pointer to the actual number of characters read by the function.

Note
The caller is responsible for declaring and allocating the necessary storage for i and count (if used), before calling this function.
bool RWFile::Read ( unsigned short *  i,
size_t  n,
size_t *  count = 0 
)
inline

Reads n instances of the indicated built-in type into a block pointed to by i. Returns true if the read is successful.

The optional parameter count is a pointer to the actual number of characters read by the function.

Note
The caller is responsible for declaring and allocating the necessary storage for i and count (if used), before calling this function.
bool RWFile::Read ( unsigned int *  i,
size_t  n,
size_t *  count = 0 
)
inline

Reads n instances of the indicated built-in type into a block pointed to by i. Returns true if the read is successful.

The optional parameter count is a pointer to the actual number of characters read by the function.

Note
The caller is responsible for declaring and allocating the necessary storage for i and count (if used), before calling this function.
bool RWFile::Read ( unsigned long *  i,
size_t  n,
size_t *  count = 0 
)
inline

Reads n instances of the indicated built-in type into a block pointed to by i. Returns true if the read is successful.

The optional parameter count is a pointer to the actual number of characters read by the function.

Note
The caller is responsible for declaring and allocating the necessary storage for i and count (if used), before calling this function.
bool RWFile::Read ( float *  i,
size_t  n,
size_t *  count = 0 
)

Reads n instances of the indicated built-in type into a block pointed to by i. Returns true if the read is successful.

The optional parameter count is a pointer to the actual number of characters read by the function.

Note
The caller is responsible for declaring and allocating the necessary storage for i and count (if used), before calling this function.
bool RWFile::Read ( double *  i,
size_t  n,
size_t *  count = 0 
)

Reads n instances of the indicated built-in type into a block pointed to by i. Returns true if the read is successful.

The optional parameter count is a pointer to the actual number of characters read by the function.

Note
The caller is responsible for declaring and allocating the necessary storage for i and count (if used), before calling this function.
bool RWFile::Read ( long long *  i,
size_t  n,
size_t *  count = 0 
)

Reads n instances of the indicated built-in type into a block pointed to by i. Returns true if the read is successful.

The optional parameter count is a pointer to the actual number of characters read by the function.

Note
The caller is responsible for declaring and allocating the necessary storage for i and count (if used), before calling this function.
This function is available only if your compiler supports the long long type.
bool RWFile::Read ( unsigned long long *  i,
size_t  n,
size_t *  count = 0 
)

Reads n instances of the indicated built-in type into a block pointed to by i. Returns true if the read is successful.

The optional parameter count is a pointer to the actual number of characters read by the function.

Note
The caller is responsible for declaring and allocating the necessary storage for i and count (if used), before calling this function.
This function is available only if your compiler supports the unsigned long long type.
bool RWFile::Read ( long double *  i,
size_t  n,
size_t *  count = 0 
)

Reads n instances of the indicated built-in type into a block pointed to by i. Returns true if the read is successful.

The optional parameter count is a pointer to the actual number of characters read by the function.

Note
The caller is responsible for declaring and allocating the necessary storage for i and count (if used), before calling this function.
This function is available only if your compiler supports the long double type.
bool RWFile::Read ( char *  string)
Deprecated:
As of SourcePro 11. Because of the risk of buffer overflow, we strongly recommend against using this function. Use Read(char*, size_t, size_t*) or Read(char*, size_t, int, size_t*) instead.

Reads a character string, including the terminating null character, into a block pointed to by string. Returns true if the read is successful.

Note
The caller is responsible for declaring string and for allocating the necessary storage before calling this function.
bool RWFile::SeekTo ( RWoffset  offset)

Repositions the file pointer to offset bytes from the start of the file. Can be used with both small and very large (more than 2GB) files. Returns true if the operation is successful. Returns -1 on error or if the requested seek offset is outside the range supported by the underlying file.

bool RWFile::SeekTo64 ( RWoffset64  offset)

Repositions the file pointer to offset bytes from the start of the file. Can be used with both small and very large (more than 2GB) files. Returns true if the operation is successful. Returns -1 on error or if the requested seek offset is outside the range supported by the underlying file.

bool RWFile::SeekToBegin ( )

Repositions the file pointer to the start of the file. Returns true if the operation is successful.

bool RWFile::SeekToEnd ( )

Repositions the file pointer to the end of the file. Returns true if the operation is successful.

bool RWFile::Write ( bool  i)

Writes the appropriate built-in type. Returns true if the write is successful.

bool RWFile::Write ( char  i)

Writes the appropriate built-in type. Returns true if the write is successful.

bool RWFile::Write ( short  i)

Writes the appropriate built-in type. Returns true if the write is successful.

bool RWFile::Write ( int  i)

Writes the appropriate built-in type. Returns true if the write is successful.

bool RWFile::Write ( long  i)

Writes the appropriate built-in type. Returns true if the write is successful.

bool RWFile::Write ( wchar_t  i)

Writes the appropriate built-in type. Returns true if the write is successful.

bool RWFile::Write ( unsigned char  i)

Writes the appropriate built-in type. Returns true if the write is successful.

bool RWFile::Write ( unsigned short  i)

Writes the appropriate built-in type. Returns true if the write is successful.

bool RWFile::Write ( unsigned int  i)

Writes the appropriate built-in type. Returns true if the write is successful.

bool RWFile::Write ( unsigned long  i)

Writes the appropriate built-in type. Returns true if the write is successful.

bool RWFile::Write ( float  f)

Writes the appropriate built-in type. Returns true if the write is successful.

bool RWFile::Write ( double  d)

Writes the appropriate built-in type. Returns true if the write is successful.

bool RWFile::Write ( long long  i)

Writes the appropriate built-in type. Returns true if the write is successful.

Note
This function is available only if your compiler supports the long long type.
bool RWFile::Write ( unsigned long long  i)

Writes the appropriate built-in type. Returns true if the write is successful.

Note
This function is available only if your compiler supports the unsigned long long type.
bool RWFile::Write ( long double  d)

Writes the appropriate built-in type. Returns true if the write is successful.

Note
This function is available only if your compiler supports the long double type.
bool RWFile::Write ( const char *  string)

Writes a character string, including the terminating null character, from a block pointed to by string. Returns true if the write is successful. Beware of non-terminated strings when using this function.

bool RWFile::Write ( const bool *  i,
size_t  count 
)

Writes count instances of the indicated built-in type from a block pointed to by i. Returns true if the write is successful.

bool RWFile::Write ( const short *  i,
size_t  count 
)

Writes count instances of the indicated built-in type from a block pointed to by i. Returns true if the write is successful.

bool RWFile::Write ( const int *  i,
size_t  count 
)

Writes count instances of the indicated built-in type from a block pointed to by i. Returns true if the write is successful.

bool RWFile::Write ( const long *  i,
size_t  count 
)

Writes count instances of the indicated built-in type from a block pointed to by i. Returns true if the write is successful.

bool RWFile::Write ( const wchar_t *  i,
size_t  count 
)

Writes count instances of the indicated built-in type from a block pointed to by i. Returns true if the write is successful.

bool RWFile::Write ( const unsigned char *  c,
size_t  N 
)
inline

Writes count instances of the indicated built-in type from a block pointed to by i. Returns true if the write is successful.

bool RWFile::Write ( const unsigned short *  i,
size_t  N 
)
inline

Writes count instances of the indicated built-in type from a block pointed to by i. Returns true if the write is successful.

bool RWFile::Write ( const unsigned int *  i,
size_t  N 
)
inline

Writes count instances of the indicated built-in type from a block pointed to by i. Returns true if the write is successful.

bool RWFile::Write ( const unsigned long *  i,
size_t  N 
)
inline

Writes count instances of the indicated built-in type from a block pointed to by i. Returns true if the write is successful.

bool RWFile::Write ( const float *  i,
size_t  count 
)

Writes count instances of the indicated built-in type from a block pointed to by i. Returns true if the write is successful.

bool RWFile::Write ( const double *  i,
size_t  count 
)

Writes count instances of the indicated built-in type from a block pointed to by i. Returns true if the write is successful.

bool RWFile::Write ( const char *  string,
size_t   
)

Writes count instances of the indicated built-in type from a block pointed to by i. Returns true if the write is successful.

bool RWFile::Write ( const long long *  i,
size_t  count 
)

Writes count instances of the indicated built-in type from a block pointed to by i. Returns true if the write is successful.

Note
This function is available only if your compiler supports the long long type.
bool RWFile::Write ( const unsigned long long *  i,
size_t  count 
)

Writes count instances of the indicated built-in type from a block pointed to by i. Returns true if the write is successful.

Note
This function is available only if your compiler supports the unsigned long long type.
bool RWFile::Write ( const long double *  i,
size_t  count 
)

Writes count instances of the indicated built-in type from a block pointed to by i. Returns true if the write is successful.

Note
This function is available only if your compiler supports the long double type.

Copyright © 2023 Rogue Wave Software, Inc., a Perforce company. All Rights Reserved.