file.h File Reference

File base class. More...

#include <stdio.h>

Go to the source code of this file.

Classes
struct	mdio_File_t
	File base class. More...
Typedefs
typedef mdio_File_t	mdio_File
	File base class.
Enumerations
enum	{ MDIO_ERROR = -1, MDIO_LENGTH_ERRMSG = 240 }
enum	{ MDIO_FILE_TEXT = 0x001, MDIO_FILE_BINARY = 0x002, MDIO_FILE_READ = 0x004, MDIO_FILE_WRITE = 0x008 }
	File type flags. More...
enum	{   MDIO_ERROR_NONE, MDIO_ERROR_WARN, MDIO_ERROR_BADVAL, MDIO_ERROR_NOMEM,   MDIO_ERROR_OPEN, MDIO_ERROR_CLOSE, MDIO_ERROR_READ, MDIO_ERROR_WRITE,   MDIO_ERROR_SEEK, MDIO_ERROR_SYNTAX, MDIO_ERROR_UNXEOF, MDIO_LENGTH_ERRORLIST }
	Error numbers. More...
enum	{ MDIO_EOF = 0x001, MDIO_SEEK_SET = SEEK_SET, MDIO_SEEK_CUR = SEEK_CUR, MDIO_SEEK_END = SEEK_END }
Functions
mdio_File *	mdio_createFile (void)
	Constructor.
void	mdio_destroyFile (mdio_File *)
	Destructor.
int	mdio_openFile (mdio_File *, const char *name, int filetype)
	Open file.
int	mdio_closeFile (mdio_File *)
	Close file.
int	mdio_readLineFile (mdio_File *, char **pbuf, int *pbuflen)
	Read entire line from text file.
int	mdio_readTextFile (mdio_File *, char *buf, int buflen)
	Read from text file.
int	mdio_writeTextFile (mdio_File *, const char *buf)
	Write to text file.
int	mdio_readBinaryFile (mdio_File *, void *buffer, int elemsz, int n)
	Read from binary file.
int	mdio_writeBinaryFile (mdio_File *, const void *buffer, int elemsz, int n)
	Write to binary file.
int	mdio_seekFile (mdio_File *, long offset, int whence)
	Seek position within binary file.
int	mdio_isEndOfFile (mdio_File *)
	Return nonzero if end-of-file has been reached, otherwise return 0.
int	mdio_setErrorFile (mdio_File *, int errnum)
	Set error status on file.
int	mdio_setErrorMessageFile (mdio_File *, int errnum, const char *msg)
	Set error status on file with customized message.
void	mdio_setErrorHandlerFile (mdio_File *, int(*errhandler)(mdio_File *))
	Set error handler routine.
const char *	mdio_getNameFile (mdio_File *)
	Returns the name of the file.
int	mdio_getTypeFile (mdio_File *)
	Returns the type of the file.
int	mdio_getErrorFile (mdio_File *)
	Returns the current error number set for the file.
int	mdio_getBytenumFile (mdio_File *)
	Returns the current byte position for the file.
int	mdio_getLinenumFile (mdio_File *)
	Returns the current line number for the file.
const char *	mdio_getErrorMessageFile (mdio_File *)
	Returns the current diagnostic error message for the file.
void	mdio_resetErrorFile (mdio_File *)
	Resets the error status for the file.
int	mdio_initializeFile (mdio_File *)
	Alternative constructor.
void	mdio_cleanupFile (mdio_File *)
	Alternative destructor.

---

Detailed Description

File base class.

Author:

David J. Hardy

Date:

2003-2005

The mdio_File class performs the actual I/O along with diagnostic and error handling capabilities. It is the base class for the specialized reader and writer classes. For accessing supported types of MD files, instead use the higher level "derived" classes.

The file I/O routines are a somewhat simplified version of the C standard I/O library function calls. The fact that the actual I/O calls are hidden behind this layer means that the implementation could depend on the file type, for example, use of mmap() for large trajectory files.

---

Typedef Documentation

typedef struct mdio_File_t mdio_File

File base class. Members should be treated as private.

---

Enumeration Type Documentation

anonymous enum

Enumerator: MDIO_ERROR  Return value from failed function call.

anonymous enum

File type flags. Enumerator: MDIO_FILE_TEXT  Flag indicating text file. MDIO_FILE_BINARY  Flag indicating binary file. MDIO_FILE_READ  Flag indicating reading from a file. MDIO_FILE_WRITE  Flag indicating writing to a file.

anonymous enum

Error numbers. Enumerator: MDIO_ERROR_NONE  No error. MDIO_ERROR_WARN  A warning. MDIO_ERROR_BADVAL  An illegal value pertaining to file. MDIO_ERROR_NOMEM  Memory cannot be allocated. MDIO_ERROR_OPEN  Cannot open a file. MDIO_ERROR_CLOSE  Cannot close a file. MDIO_ERROR_READ  Unable to read from file. MDIO_ERROR_WRITE  Unable to write to file. MDIO_ERROR_SEEK  Unable to perform a byte seek within file. MDIO_ERROR_SYNTAX  Syntax error occurred with file. MDIO_ERROR_UNXEOF  The end-of-file marker occurred unexpectedly.

anonymous enum

Enumerator: MDIO_EOF  End-of-file constant for MDIO. MDIO_SEEK_SET  Byte offset wrt beginning of file. MDIO_SEEK_CUR  Byte offset wrt current position. MDIO_SEEK_END  Byte offset wrt end of file.

---

Function Documentation

void mdio_cleanupFile (  mdio_File *   )

Alternative destructor. Use to destroy a preallocated file object (i.e. one constructed using mdio_initializeFile() ).

int mdio_closeFile (  mdio_File *   )

Close file. Returns: 0 on success or MDIO_ERROR on failure.

mdio_File* mdio_createFile (  void   )

Constructor. Creates dynamically allocated file object. Returns: Pointer to file object or NULL on failure.

void mdio_destroyFile (  mdio_File *   )

Destructor. Frees dynamically allocated file object.

int mdio_initializeFile (  mdio_File *   )

Alternative constructor. Use to construct a preallocated file object. See mdio_createFile() for a description of expected arguments.

int mdio_openFile (  mdio_File *  , const char *  name, int  filetype )

Open file. Parameters: [in]  name  The file name, nil-terminated string. [in]  filetype  Bitwise OR'ed combination of file type flags. The name string is expected to persist until the file is closed with mdio_closeFile(). For filetype, must choose either MDIO_FILE_TEXT or MDIO_FILE_BINARY combined (using bitwise OR operator) with either MDIO_FILE_READ or MDIO_FILE_WRITE. Returns: 0 on success or MDIO_ERROR on failure.

int mdio_readBinaryFile (  mdio_File *  , void *  buffer, int  elemsz, int  n )

Read from binary file. Parameters: [out]  buffer  Points to memory buffer. [in]  elemsz  Size in bytes of each element. [in]  n  The number of elements to be read. Read n elements each of size elemsz bytes into the memory buffer pointed to by buffer. Similar to fread(). Returns: The number of elements read. If it is less than n, then either the end-of-file was reached or and error occurred.

int mdio_readLineFile (  mdio_File *  , char **  pbuf, int *  pbuflen )

Read entire line from text file. Parameters: [in,out]  pbuf  Address of the char buffer pointer. [in,out]  pbuflen  Address of the char buffer length variable. Read text file up to and including the next newline character, storing the characters into the buffer. The char buffer is nil-terminated. The address pbuf needs to point to memory that can be managed using realloc() so that the buffer can be expanded arbitrarily to contain the entire line, with the updated length stored back to pbuflen. The caller is responsible for later freeing the memory allocation. Returns: The number of characters read into the buffer. End-of-file is indicated by returning 0 and storing the empty string into the pbuf buffer. A blank line is indicated by returning 1 and storing "\n" into the pbuf buffer. An error is indicated by returning MDIO_ERROR.

int mdio_readTextFile (  mdio_File *  , char *  buf, int  buflen )

Read from text file. Parameters: [in,out]  buf  Points to the char buffer. [in]  buflen  The length of the char buffer. Read up to and including the next newline character, but no more than buflen - 1 characters. Similar to fgets(). Returns: The number of characters read into the buffer. End-of-file is indicated by returning 0 and storing the empty string into the pbuf buffer. A blank line is indicated by returning 1 and storing "\n" into the pbuf buffer. An error is indicated by returning MDIO_ERROR.

int mdio_seekFile (  mdio_File *  , long  offset, int  whence )

Seek position within binary file. Parameters: [in]  offset  Byte offset relative to some location. [in]  whence  Flag to indicate the byte offset location. The seek offset in a binary file may be measured from one of the following locations: MDIO_SEEK_SET - beginning of file MDIO_SEEK_CUR - current location in file MDIO_SEEK_END - end of file The current file position is then changed to the indicated location. Returns: 0 on success or MDIO_ERROR on failure.

int mdio_setErrorFile (  mdio_File *  , int  errnum )

Set error status on file. Parameters: [in]  errnum  MDIO error number. The error status on the file is set to the indicated error number and a corresponding diagnostic message. The message might include information on the name and location within the file where the error occurred, depending on the type of error. An illegal value for errnum will terminate the program. If the error handler has been set (see mdio_setErrorHandlerFile() ), then that routine will be invoked before returning. Returns: The value from the error handler routine or errnum if the error handler has been set to NULL.

void mdio_setErrorHandlerFile (  mdio_File *  , int(*)(mdio_File *)  errhandler )

Set error handler routine. Parameters: [in]  errhandler  Routine to handle errors. The error handler is invoked whenever an error occurs, as the conclusion of mdio_setErrorFile() or mdio_setErrorMessageFile(). The default error handler prints to stderr the error diagnostic message. It can be replaced by a user-defined error handling routine or resetting to NULL. Any of the following routines are available to the error handler: mdio_getNameFile(), mdio_getTypeFile(), mdio_getErrorFile(), mdio_getBytenumFile(), mdio_getLinenumFile(), mdio_getErrorMessageFile().

int mdio_setErrorMessageFile (  mdio_File *  , int  errnum, const char *  msg )

Set error status on file with customized message. Parameters: [in]  errnum  MDIO error number. [in]  msg  A nil-terminated string. This routine is identical to mdio_setErrorFile() with the addition that the msg string will be appended to the diagnostic message.

int mdio_writeBinaryFile (  mdio_File *  , const void *  buffer, int  elemsz, int  n )

Write to binary file. Parameters: [in]  buffer  Points to memory buffer. [in]  elemsz  Size in bytes of each element. [in]  n  The number of elements to be written. Write the n elemsz bytes stored in buffer to the file. Similar to fwrite(). Returns: The number of elements written. If it is less than n, then an error has occurred.

int mdio_writeTextFile (  mdio_File *  , const char *  buf )

Write to text file. Parameters: [in]  buf  Points to a nil-terminated string. Write the string, not including the nil-terminator, to the file. Newline characters must be explicitly included in the string. Similar to fputs(). Returns: The number of characters written or MDIO_ERROR on error.

---