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 $ \times $ 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.

Generated on Mon Sep 26 10:55:19 2005 for MDX by doxygen 1.4.4