# Disk File Base

Topics

:

Overview
Conditional Directives
Constants
Type Definitions
Enumerations
Functions

Overview

The disk file class is a general-purpose base class used to perform various file and directory functions.

Conditional Directives

__DJGPP2721__

- Conditional directive required to compile with the DJGPP compiler.

__DOS__

- Conditional directive required to compile under DOS or WIN32 file systems.

__DOS_INCLUDES__

- Conditional directive required by 16-bit DOS compilers.

__MSVC_FILE_SHARING__

- Open the file in binary mode using MSVC file sharing.

__UNIX__

- Conditional directive required to compile under UNIX file systems.

__WIN32__

- Conditional directive required to compile under WIN32 file systems.

Constants

    const unsigned df_MAX_LINE_LENGTH = 1024; // Maximum line length
    const unsigned df_MAX_NAME_LENGTH = 255;  // Maximum length of a file name
    const unsigned df_MAX_DIR_LENGTH = 1024;  // Maximum length of a directory name
    const df_StreamPos df_CurrPosition = -1;  // Indicates current file position

Type Definitions

df_StreamPos

- Type definition used to indicate the current stream position.

Enumerations

    enum { // DiskFileB error codes
        DiskFileB::df_NO_ERROR = 0,       // No errors reported
        DiskFileB::df_INVALID_ERROR_CODE, // Invalid file error code

        // File error exception codes
        DiskFileB::df_CLOSE_ERROR,  // Error closing the file
        DiskFileB::df_COPY_ERROR,   // Error copying file
        DiskFileB::df_CREATE_ERROR, // Could not create the file
        DiskFileB::df_EOF_ERROR,    // End of file error
        DiskFileB::df_EXIST_ERROR,  // The file does not exist
        DiskFileB::df_FLUSH_ERROR,  // Error flushing the disk buffers
        DiskFileB::df_MODE_ERROR,   // An invalid access/open mode specified
        DiskFileB::df_OPEN_ERROR,   // Could not open the file
        DiskFileB::df_READ_ERROR,   // An error occurred during a read operation
        DiskFileB::df_REMOVE_ERROR, // Could remove the specified file
        DiskFileB::df_RENAME_ERROR, // Could not rename the specified file
        DiskFileB::df_REWIND_ERROR, // Error rewinding the file
        DiskFileB::df_SEEK_ERROR,   // An error occurred during a seek operation
        DiskFileB::df_WRITE_ERROR,  // An error occurred during a write operation

        // Directory error exception codes
        DiskFileB::df_CHDIR_ERROR,  // Could not change directory
        DiskFileB::df_MKDIR_ERROR,  // Could not create directory
        DiskFileB::df_RMDIR_ERROR   // Could not remove directory
      };

      enum { // DiskFileB access/open mode enumeration
        DiskFileB::df_READONLY,   // Open file with read access only
        DiskFileB::df_WRITEONLY,  // Open file with write access only
        DiskFileB::df_READWRITE,  // Open file with read and write access
        DiskFileB::df_CREATE,     // Create the file if it does not exist
        DiskFileB::df_NO_CREATE,  // Do not create the file if it does not exist
        DiskFileB::df_TRUNCATE,   // Truncate the file
        DiskFileB::df_APPEND,     // Append to the file
        DiskFileB::df_SHARE,      // Enable file sharing (DOS and WIN32 only)
        DiskFileB::df_EXCLUSIVE   // No file sharing (DOS and WIN32 only)
      };

      enum { // DiskFileB seek modes
        DiskFileB::df_SEEK_BEG, // Seek starting from the beginning of the file
        DiskFileB::df_SEEK_CUR, // Seek starting from the current location
        DiskFileB::df_SEEK_END  // Seek starting from the end of the file
      };

      enum { // DiskFileB I/O operation codes
        DiskFileB::df_READ,         // A read was performed
        DiskFileB::df_WRITE,        // A write operation was performed
        DiskFileB::df_REWIND,       // A rewind operation was performed
        DiskFileB::df_NO_OPERATION  // No operation was performed
      };

Functions

DiskFileB::DiskFileB()
DiskFileB::~DiskFileB()
DiskFileB::DiskFileExceptionMessage()
DiskFileB::df_ClearErr()
DiskFileB::df_ClearNameBuffer()
DiskFileB::df_Close()
DiskFileB::df_Copy()
DiskFileB::df_CreateFile()
DiskFileB::df_EOF()
DiskFileB::df_Exists()
DiskFileB::df_FileLength()
DiskFileB::df_FilePosition()
DiskFileB::df_FileSize()
DiskFileB::df_FileStream()
DiskFileB::df_Flush()
DiskFileB::df_GenOutputFileName()
DiskFileB::df_Get()
DiskFileB::df_GetFileError()
DiskFileB::df_GetLine()
DiskFileB::df_HasDriveLetter()
DiskFileB::df_IsDirectory()
DiskFileB::df_IsFile()
DiskFileB::df_IsOK()
DiskFileB::df_IsOpen()
DiskFileB::df_LastError()
DiskFileB::df_LastOperation()
DiskFileB::df_LoadNameBuffer()
DiskFileB::df_MakeDOSPath()
DiskFileB::df_MakeUNIXPath()
DiskFileB::df_Open()
DiskFileB::df_OpenFileName()
DiskFileB::df_PathSimplify()
DiskFileB::df_Put()
DiskFileB::df_ReOpen()
DiskFileB::df_Read()
DiskFileB::df_ReadOnly()
DiskFileB::df_ReadyForReading()
DiskFileB::df_ReadyForWriting()
DiskFileB::df_Rewind()
DiskFileB::df_Seek()
DiskFileB::df_SeekTo()
DiskFileB::df_Write()
DiskFileB::df_chdir()
DiskFileB::df_chmod()
DiskFileB::df_copy()
DiskFileB::df_mkdir()
DiskFileB::df_pwd()
DiskFileB::df_remove()
DiskFileB::df_rename()
DiskFileB::df_rmdir()
DiskFileB::operator!()
DiskFileB::operator=()

DiskFileB::DiskFileB()

- Default class constructor

DiskFileB::DiskFileB(const char *fname, int mode=DiskFileB::df_READONLY, int create=DiskFileB::df_NO_CREATE, int truncate=DiskFileB::df_APPEND,int sharing=DiskFileB::df_SHARE)

- Class constructor used to open a specified file. The "mode", "create", "truncate", and "sharing" variables must correspond to one of the integer constant defined in the DiskFileB access/open mode enumeration.

DiskFileB::DiskFileB(const DiskFileB &ob)

- Protected copy constructor used by a derived class to copy DiskFileB objects.

virtual DiskFileB::~DiskFileB()

- Class destructor responsible for closing any open files.

const char *DiskFileB::DiskFileExceptionMessage()

- Public member function used to retrieve the last reported file error in the form of a null terminated string that can be used to log or print a disk file exception.

void DiskFileB::df_ClearErr()

- Public member function used to clear the last reported file error.

void DiskFileB::df_ClearNameBuffer()

- Protected member function used to clear the open file name.

virtual int DiskFileB::df_Close()

- Public member function used to close a previously opened file. Returns a DiskFileB::df_CLOSE_ERROR error code if an error was encountered or zero to indicate success.

void DiskFileB::df_Copy(const DiskFileB &ob)

- Protected member function member function used to copy DiskFileB objects. NOTE: A derived class should never allow copying or assignment unless each copy is accounted for by reference counting or some other method.

virtual int DiskFileB::df_CreateFile(const char *fname)

- Public member function used to create the specified file. Returns zero if the file was created with no errors or a non-zero value to indicate a failure.

int DiskFileB::df_EOF()

- Public member function that returns true if the end of file has been reached.

int DiskFileB::df_Exists(const char *name)

- Public member function that returns true if the specified file exists.

df_StreamPos DiskFileB::df_FileLength()

- Public member function that returns the length of the open file.

virtual df_StreamPos DiskFileB::df_FilePosition(int operation=DiskFileB::df_NO_OPERATION)

- Public member function that returns the current file position after a read, write, or rewind operation. Returns -1 if an error occurred or an invalid operation was performed. If no operation is specified the last operation performed will be used to determine the current get or put pointer position in the file stream. The "operation" variable must correspond to one of the integer constants defined in the DiskFileB I/O operation enumeration.

df_StreamPos DiskFileB::df_FileSize(const char *fname)

- Public member function that returns the file size of the specified file.

fstream *DiskFileB::df_FileStream()

- Public member function that returns a pointer to current fstream object.

virtual int DiskFileB::df_Flush()

- Public member function used to flush any open disk buffers. Returns a DiskFileB::df_FLUSH_ERROR error code if an error was encountered or zero to indicate success.

int DiskFileB::df_GenOutputFileName(const char *current_file, char *out_file, const char *extension)

- Public member function used to generate a name for the output file using the "current_file" name with the specified dot extension. NOTE: This function assumes that the necessary memory has already been allocated for the "out_file" variable by the calling function. Returns a non-zero value if any errors occur.

virtual int DiskFileB::df_Get(char &c)

- Public member function used to get a single character from the open file. Returns zero if no errors occur or a non-zero value to indicate a failure during a get call.

char *DiskFileB::df_GetFileError(int error_code)

- Public member function that returns a null terminated string that represents the specified error code.

char *DiskFileB::df_GetFileError()

- Public member function that returns a null terminated string that represents the last reported file error.

virtual int DiskFileB::df_GetLine(void *buf, unsigned bytes=df_MAX_LINE_LENGTH)

- Public member function used to get a line of text from the open file. Returns zero if no errors occur or a non-zero value to indicate a failure during a getline call. NOTE: This function assumes that a buffer equal to the size of the "bytes" variable has already been allocated.

int DiskFileB::df_HasDriveLetter(const char *dir_name, char &letter)

- Public member function used under DOS and WIN32 file systems to parse the drive letter from the specified directory. Returns false if the path does not contain a drive letter. If a drive letter is found it will be passed back in the "letter" variable.

int DiskFileB::df_IsDirectory(const char *dir_name)

- Public member function that returns true if the specified name is a directory.

int DiskFileB::df_IsFile(const char *fname)

- Public member function that returns true if the specified name is any kind of file or false if this is a directory.

int DiskFileB::df_IsOK()

- Public member function that returns true if the file status is ok.

int DiskFileB::df_IsOpen()

- Public member function that returns true if the file is open.

int DiskFileB::df_LastError()

- Public member function that returns the last reported file error. The return value will correspond to one of the integer constants defined in the DiskFileB error code enumeration.

int DiskFileB::df_LastOperation()

- Public member function that returns the last operation performed. The return value will correspond to one of the integer constants defined in the DiskFileB I/O operation enumeration.

void DiskFileB::df_LoadNameBuffer(const char *s)

- Protected member function used to set the open file name.

void DiskFileB::df_MakeDOSPath(char *path)

- Public member function used to make a DOS directory path by replacing all forward slash path separators with back slashes.

void DiskFileB::df_MakeUNIXPath(char *path)

- Public member function used to make a UNIX directory path by replacing all back slash path separators with forward slashes.

virtual int DiskFileB::df_Open(const char *fname, int mode=DiskFileB::df_READONLY, int create=DiskFileB::df_NO_CREATE, int truncate=DiskFileB::df_APPEND, int sharing=DiskFileB::df_SHARE,fstream *f=0)

- Public member function used to open the specified file. The "mode", "create", "truncate", and "share" values must correspond to one of the integer constants defined in the DiskFileB access/open mode enumeration. If no fstream pointer is specified an internal fstream object will be used. Returns zero if no errors occur or a non-zero value if an error is encountered during an open call.

char *DiskFileB::df_OpenFileName()

- Public member function that returns the open file name in the form of a null-terminated string.

void DiskFileB::df_PathSimplify(const char *path, char *new_path, char path_sep = '/')

- Public member function used to simplify a path and return a new path. The path separator should either be a forward slash for UNIX file systems or a backslash for DOS/WIN32 file systems. If no path separator is specified a forward slash will be used by default. Multiple path separators will be collapsed to a single path separator. Leading `./' paths and trailing `/.' paths will be removed. Trailing path separators will be removed. All non-leading `../' paths and trailing `..' paths are handled by removing portions of the path. NOTE: This function assumes that the necessary memory has already been allocated for the "new_path" variable by the calling function.

virtual int DiskFileB::df_Put(const char &c)

- Public member function used to put a single character into the open file. Returns zero if no errors occur or a non-zero value if an error is encountered during a put call.

virtual int DiskFileB::df_ReOpen(fstream *f, int mode=DiskFileB::df_READONLY)

- Public member function used to connect the file object pointer to another pointer. This function assumes the file has been opened by the calling function. The calling function must tell this function if the file was opened for read, write, or read/write access.

virtual int DiskFileB::df_Read(void *buf, unsigned bytes, df_StreamPos position=df_CurrPosition)

- Public member function used to read a specified number of bytes into a buffer. Returns zero if no errors occur or a non-zero value if an error is encountered during a read call.

int DiskFileB::df_ReadOnly()

- Public member function that returns true if this is a read only file.

int DiskFileB::df_ReadyForReading()

- Public member function that returns true if the file is ready for reading.

int DiskFileB::df_ReadyForWriting()

- Public member function that returns true if the file is ready for writing.

virtual int DiskFileB::df_Rewind()

- Public member function used to rewind the file get and put pointers to zero and flush any open disk buffers. Returns a DiskFileB::df_REWIND_ERROR error code if an error was encountered or zero to indicate success.

virtual int DiskFileB::df_Seek(df_StreamPos position, int seek_mode=df_SEEK_BEG, int operation=df_NO_OPERATION)

- Public member function used to move the file offset to the specified file position. Returns a DiskFileB::df_SEEK_ERROR if an error occurred during a file seek. If no operation is specified both the get and put offsets will be moved to the specified position. The "seek_mode" variable must correspond to one of the integer constants defined in the DiskFileB seek mode enumeration. The "operation" variable must correspond to one of the integer constants defined in the DiskFileB I/O operation enumeration.

virtual df_StreamPos DiskFileB::df_SeekTo(df_StreamPos position, int operation=df_NO_OPERATION)

-Public member function used to seek to the specified position, optimizing the seek operation by moving the file position indicator based on the current stream position. Returns the current file position after performing the "seek to" operation. The "operation" variable must correspond to one of the integer constants defined in the DiskFileB I/O operation enumeration.

virtual int DiskFileB::df_Write(const void *buf, unsigned bytes, df_StreamPos position=df_CurrPosition)

- Public member function used to write a specified number of bytes from a buffer to the open file. Returns zero if no errors occur or a non-zero value if an error is encountered during a write call.

int DiskFileB::df_chdir(const char *dir_name)

- Public member function use to change the current working directory. Returns zero if successful.

int DiskFileB::df_chmod(const char *fname, int pmode)

- Public member function used to change the file-permission settings. The "pmode" variable should be equal to DiskFileB::df_READONLY, DiskFileB::df_WRITEONLY, or DiskFileB::df_READWRITE. Returns a non-zero value if an error occurs or zero to indicate success.

int DiskFileB::df_copy(const char *from, const char *to)

- Public member function used to copy a file. Returns a non-zero value if an error occurs or zero to indicate success.

int DiskFileB::df_mkdir(const char *dir_name)

- Public member function used to make the specified directory if it does not exist. Returns a non-zero value if an error occurs. NOTE: UNIX file systems will use 755 permissions when new directories are created.

int DiskFileB::df_pwd(char *dir, unsigned max_len = df_MAX_DIR_LENGTH)

- Public member function that passes back the present working directory in the "dir" variable. Returns false if an error occurs. NOTE: This function assumes that the required amount of memory has already been allocated for the "dir" pointer. The "max_len" value must be at least one byte greater than the length of the pathname to be returned.

int DiskFileB::df_remove(const char *fname)

- Public member function used to delete a file. Returns a non-zero value if an error occurs or zero to indicate success.

int DiskFileB::df_rename(const char *oldname, const char *newname)

- Public member function used to rename a file. Returns a non-zero value if an error occurs or zero to indicate success.

int DiskFileB::df_rmdir(const char *dir_name)

- Public member function used to remove the specified directory. Returns zero if successful or a non-zero value to indicate a failure. NOTE: The directory must be empty and not be the current working directory or the root directory.

End Of Document