ifile.h File Reference

#include <hdf5.h>
#include <sqlite3.h>
#include <string.h>
#include "globals.h"

Go to the source code of this file.

Data Structures
struct	IFILE

Macros
#define	IFILE_CLOSED   0
#define	IFILE_R   1
#define	IFILE_W   2
#define	IFILE_A   3
#define	IFILE_RP   4
#define	IFILE_WP   5
#define	IFILE_AP   6
#define	IFILE_WX   7
#define	IFILE_WXP   8
#define	IFILE_SUCCESS   1
#define	IFILE_FAILURE   2

Functions
IFILE *	IFileOpen (hid_t file_id, const char *ifilename, const char *access)
	IFileOpen is used to open an internal file in a GeoSci File. More...
int	IFileClearError (IFILE *ifilep)
	IFileClearError clears the error condition on an internal file. More...
int	IFileClose (IFILE *ifilep)
	IFileClose closes an internal file in a GeoSci File. More...
int	IFileEOF (IFILE *ifilep)
	IFileEOF returns the End-Of-File condition of the previous internal read. More...
int	IFileError (IFILE *ifilep)
	IFileError returns error condition on an internal file. More...
int	IFileFlush (IFILE *ifilep)
	IFileFlush flushes unwritten buffers to an internal file in a GeoSci File. More...
int	IFileGetc (IFILE *ifilep)
	IFileGetc reads a character from an internal file. More...
char *	IFileGets (IFILE *ifilep, char *str, int num)
	IFileGets reads characters from an internal file in a geosci file, and stores them as a string until the maximum number of characters have been read or either a newline or the end-of-file is reached, whichever happens first. More...
int	IFileSeek (IFILE *ifilep, long int offset, int origin)
	IFileSeek moves to a position in an internal file. More...
long int	IFileTell (IFILE *ifilep)
	IFileTell retrieves the current read/write position in an internal file. More...
int	IFileRewind (IFILE *ifilep)
	IFileRewind moves to the start of an internal file. More...
int	IFilePerror (IFILE *ifilep, const char *str)
	IFilePerror prints latest error for an internal file. More...
int	IFileReadAccess (IFILE *ifilep)
	IFileReadAccess reads access code of an internal file. More...
int	IFileReadAccessHDF (hid_t dataset_id)
	IFileReadAccessHDF reads access code of an internal file. More...
int	IFileWriteAccess (IFILE *ifilep, int code)
	IFileWriteAccess writes a new access code for an internal file. More...
int	IFileAllocate (IFILE *ifilep, long int offset, long int length)
	IFileAllocate is used to allocate more space to an internal file. More...
int	IFilePrintf (IFILE *ifilep, const char *format,...)
	IFilePrintf writes formatted data to an internal file. More...
int	IFilePutc (IFILE *ifilep, char character)
	IFilePutc writes a single character to an internal file. More...
int	IFilePuts (IFILE *ifilep, const char *string)
	IFilePuts writes a string to an internal file. More...
size_t	IFileRead (IFILE *ifilep, void *buf, int size, int count)
	IFileRead reads the requested number of bytes from an internal file in a geosci file. More...
int	IFileReadStatus (IFILE *ifilep, char **message)
	IFileReadStatus reads the status properties of an internal file. More...
int	IFileWriteStatus (IFILE *ifilep, int status, const char *message)
	IFileWriteStatus writes the status properties of an internal file. More...
int	IFileWriteStatusMessage (IFILE *ifilep, const char *message)
	IFileWriteStatusMessage writes the status message of an internal file. More...
int	IFileScanf (IFILE *ifilep, const char *format,...)
	IFileScanf reads formatted data from an internal file. More...
int	IFileSetEOF (IFILE *ifilep, int value)
	IFileSetEOF sets End-Of-File condition on an internal file. More...
int	IFileSetWriteability (hid_t file_id, const char *name, int property)
	IFileSetWriteability sets the read/write property of an internal file. More...
int	IFileGetWrite (IFILE *ifilep)
	IFileGetWrite gets the read/write property of an internal file. More...
int	IFileSetWrite (IFILE *ifilep, int property)
	IFileSetWrite sets the read/write property of an internal file. More...
int	IFileGetWriteDataset (hid_t dataset_id)
	IFileGetWriteDataset gets the read/write property of an internal file. More...
long int	IFileSize (IFILE *ifilep)
	IFileSize gets the #bytes in an internal file. More...
long int	IFileSizeHDF (IFILE *ifilep)
	IFileSizeHDF gets the #bytes in an internal file. More...
int	IFileTruncate (IFILE *ifilep, long int length)
	IFileTruncate changes the size of an internal file. More...
int	IFileWrite (IFILE *ifilep, const void *buf, int size, int count)
	IFileWrite writes bytes to an internal file. More...
int	IFileReadALine (IFILE *ifilep, char *str, int num)
	IFileReadALine reads a string from an internal file. More...

Function Documentation

int IFileAllocate	(	IFILE *	ifilep,
		long int	offset,
		long int	length
	)

IFileAllocate is used to allocate more space to an internal file.

Parameters

[in]	ifilep	The struct of the open internal file.
[in]	offset	The offset, in bytes, from the start of the file where the newly-allocates bytes must start. Should be >= 0.
[in]	length	The length, in bytes, of the region of the newly-allocated bytes. Should be >0.

Returns

TRUE is returned on success, FALSE otherwise. The error_string variable is also set to a system-specific error code on failure.

Example

Let's assume that one already has an GeoSci file, and one wants to add 100 bytes to the end of an internal file named "/somename".

hid_t file_id;
IFILE *ifilep;
long int istart, icount;

ifilep = IFileOpen(file_id,"/somename","w");
if(!ifilep) {
   printf("IFileOpen failed on /somename\n");
}

istart=IFileSize(ifilep);

icount = 100L;
if(!IFileAllocate(ifilep, istart, icount)){
   printf("allocate failed\n");
}

Details

If the size of the file is less than offset+len, then the file is increased to this size; otherwise the file size is left unchanged. This function is meant to emulate as close as possible the standard posix_fallocate() function.

int IFileClearError

(

IFILE *

ifilep

)

IFileClearError clears the error condition on an internal file.

Parameters

[in]

ifilep

The struct of the open internal file.

Returns

TRUE is returned on SUCCESS, FALSE otherwise. The error_string variable is also set to a system-specific error code on failure.

Example

Let's assume that one already has an GeoSci file, and one wants to clear any error related to the previous read from an internal file named "/somename".

hid_t file_id;
IFILE *ifilep;
char c;

ifilep = IFileOpen(file_id,"/somename","w");
....
c = IFileGets(ifilep);

IFileClearError(ifilep);

Details

This function is meant to emulate as close as possible the standard C clearerr() function.

int IFileClose

(

IFILE *

ifilep

)

IFileClose closes an internal file in a GeoSci File.

See also

IFileOpen

Parameters

[in]

ifilep

The struct of the open internal file.

Returns

TRUE is returned on success, FALSE on failure. The error_string variable is also set to a system-specific error code on failure.

Example 1

Let's assume that one already has an GeoSci file, and one wants to close an internal file name "/somename":

hid_t file_id;
IFILE *ifilep;

ifilep = IFileOpen(file_id,"/somename","w");
if(!ifilep) {
   printf("IFileOpen failed on /somename\n");
}
if(!IFileClose(ifilep)){
   printf("IFileClose failed on /somename\n");
}

Example 2

Let's assume that one already has an GeoSci file, and one wants to close an internal file that's inside another group:

hid_t file_id, group_id;
IFILE *ifilep;

group_id = GS_GroupCreate(file_id,"/group1");
if(group_id < 0) {
   printf("GS_GroupCreate failed on /group1\n");
   exit(-1);
}
ifilep = IFileOpen(file_id,"/group1/somename","w");
if(!ifilep) {
   printf("IFileOpen failed on /group1/somename\n");
   exit(-1);
}
if(!IFileClose(ifilep)){
   printf("IFileClose failed on /group1/somename\n");
   exit(-1);
}

Details

This function is meant to emulate as close as possible the standard C fclose() function.

int IFileEOF

(

IFILE *

ifilep

)

IFileEOF returns the End-Of-File condition of the previous internal read.

See also

IFileOpen, IFileClose

Parameters

[in]

ifilep

The struct of the open internal file.

Returns

TRUE is returned if a previous read tried to read past the end-of-file, FALSE if not. ERROR is returned on any kind of error. The error_string variable is also set to a system-specific error code on failure.

Example

Let's assume that one already has an GeoSci file, and one wants to determine if the previous read from an internal file named "/somename" succeeded or not.

hid_t file_id;
IFILE *ifilep;

ifilep = IFileOpen(file_id,"/somename","w");
if(!ifilep) {
   printf("IFileOpen failed on /somename\n");
}
if(!IFileEOF(ifilep)){
   printf("previous read DID NOT read past end-of-file\n");
} else {
   printf("previous read DID read past end-of-file\n");
}

Details

This function is meant to emulate as close as possible the standard C feof() function.

int IFileError

(

IFILE *

ifilep

)

IFileError returns error condition on an internal file.

See also

IFileOpen, IFileClose

Parameters

[in]

ifilep

The struct of the open internal file.

Returns

FALSE is returned if "last_operation_status" metadata for the internal file is "SUCCESS", TRUE otherwise. ERROR is returned on any kind of error. The error_string variable is also set to a system-specific error code on failure.

Example

Let's assume that one already has an GeoSci file, and one wants to determine if the previous read from an internal file named "/somename" succeeded or not.

hid_t file_id;
IFILE *ifilep;

ifilep = IFileOpen(file_id,"/somename","w");
if(!ifilep) {
   printf("IFileOpen failed on /somename\n");
}

if(!IFileError(ifilep)){
   printf("previous read DID NOT cause an error\n");
} else {
   printf("previous read DID cause an error\n");
}

Details

This function is meant to emulate as close as possible the standard C ferror() function.

int IFileFlush

(

IFILE *

ifilep

)

IFileFlush flushes unwritten buffers to an internal file in a GeoSci File.

See also

IFileOpen, IFileClose

Parameters

[in]

ifilep

The struct of the open internal file.

Returns

TRUE is returned on success, FALSE on failure. The error_string variable is also set to a system-specific error code on failure.

Example

Let's assume that one already has an GeoSci file, and one wants to flush an internal file named "/somename":

hid_t file_id;
IFILE *ifilep;

ifilep = IFileOpen(file_id,"/somename","w");
if(!ifilep) {
   printf("IFileOpen failed on /somename\n");
}
if(!IFileFlush(ifilep)){
   printf("IFileFlush failed on /somename\n");
}

Details

This function is meant to emulate as close as possible the standard C fflush() function.

int IFileGetc

(

IFILE *

ifilep

)

IFileGetc reads a character from an internal file.

See also

IFileOpen, IFileClose

Parameters

[in]

ifilep

The struct of the open internal file.

Returns

On success, the character read is returned (promoted to an int value). If the file position indicator was at the end-of-file, the function returns ERROR and sets the end-of-file indicator (IFileEOF). If some other reading error happens, the function also returns ERROR, but sets its error indicator (IFileError) instead.

Example

Let's assume that one already has an GeoSci file, and one wants to read the next character from an internal file named "/somename".

hid_t file_id;
IFILE *ifilep;
int the_int_char;
char the_char;

ifilep = IFileOpen(file_id,"/somename","w");
if(!ifilep) {
   printf("IFileOpen failed on /somename\n");
}

the_int_char = IFileGetc(ifilep);
if(the_int_char < 0) {
   printf("read failed\n");
}

the_char = (char *)the_int_char;

...use the_char here....

Details

This function is meant to emulate as close as possible the standard C fgetc() function.

char* IFileGets	(	IFILE *	ifilep,
		char *	str,
		int	num
	)

IFileGets reads characters from an internal file in a geosci file, and stores them as a string until the maximum number of characters have been read or either a newline or the end-of-file is reached, whichever happens first.

See also

IFileOpen, FileClose

Parameters

[in]	ifilep	The struct of the open internal file.
[in,out]	str	Pointer to an array of chars where the string read is copied.
[in]	num	Maximum number of characters to be copied into str (including the terminating null-character).

Returns

On success, the function returns str.

If the end-of-file is encountered while attempting to read a character, the eof indicator is set (IFileEOF). If this happens before any characters could be read, the pointer returned is a null pointer (and the contents of str remain unchanged).

If a read error occurs, the error indicator (IFileError) is set and a null pointer is also returned (but the contents pointed-to by str may have changed).

Example

Let's assume that one already has an GeoSci file, and one wants to read the next line of characters (up to the next "\n") from an internal file named "/somename".

hid_t file_id;
IFILE *ifilep;
char the_string[1000];

ifilep = IFileOpen(file_id,"/somename","w");
if(!ifielp) {
   printf("IFileOpen failed on /somename\n");
}

the_string = IFileGets(ifilep, the_string, 1000);
if(!the_string) {
   printf("read failed\n");
}

...use the_string here....

Details

This function is meant to emulate as close as possible the standard C fgets() function.

int IFileGetWrite

(

IFILE *

ifilep

)

IFileGetWrite gets the read/write property of an internal file.

See also

IFileOpen, IFileClose

Parameters

[in]

ifilep

The struct of the open internal file.

Returns

TRUE is returned if the internal file is writeable, FALSE if not writeable.

ERROR is returned on any kind of error. The error_string variable is also set to a system-specific error code on failure.

Example

Let's assume that one already has an GeoSci file, and one wants to determine if the internal file named "/somename" is writeable.

hid_t file_id;
IFILE *ifilep;

ifilep = IFileOpen(file_id,"/somename","w");
if(!ifilep) {
   printf("IFileOpen failed on /somename\n");
}

status = IFileGetWrite(ifilep);
if( status ==FALSE){
   printf("Cannot write to internal file\n");
} else if(status == TRUE) {
   printf("Can write to internal file\n");
} else {
   printf("error getting write-status of internal file\n");
}

Details

This function is meant to enable a user to make an internal file have read and write rights like in the standard file system.

int IFileGetWriteDataset

(

hid_t

dataset_id

)

IFileGetWriteDataset gets the read/write property of an internal file.

See also

IFileOpen, IFileClose

Parameters

[in]

id;

The handle of the open dataset.

Returns

TRUE is returned if the dataset is writeable, FALSE if not writeable.

ERROR is returned on any kind of error. The error_string variable is also set to a system-specific error code on failure.

Example

Let's assume that one already has an GeoSci file, and one wants to determine if the internal file named "/somename" is writeable.

hid_t file_id;
hid_t dataset_id;

dataset_id = GS_DatasetOpen(file_id,"/somename");
if(datset_id < 0) {
   printf("GS_DatasetOpen failed on /somename\n");
}

status = IFileGetWriteDataset(ifilep);
if( status ==FALSE){
   printf("Cannot write to internal file\n");
} else if(status == TRUE) {
   printf("Can write to internal file\n");
} else {
   printf("error getting write-status of internal file\n");
}

Detials

This function is meant to enable a user to make an internal file have read and write rights like in the standard file system.

IFILE* IFileOpen	(	hid_t	file_id,
		const char *	ifilename,
		const char *	access
	)

IFileOpen is used to open an internal file in a GeoSci File.

Parameters

[in]	file_id	The handle of the open GeoSci file.
[in]	ifilename	The name of the internal file in an existing GeoSci file to be opened. Use Unix filenaming conventions, giving the full pathname, starting with "/". All but the last component of this name must already exist.
[in]	access	Access mode for the IFile, similar to that used for files: "r" read: Open internal file for input operations. Must already exist. "w" write: Create an empty file for output operations. If an internal file with the same name already exists, its contents are discarded and the file is treated as a new empty internal file. "a" append: Open internal file for output at the end of a the file. Output operations always write data at the end of the file, expanding it. Repositioning operations (IFileSeek, IFileSetpos, IFileRewind) are silently ignored. The internal file is created if it does not exist. "r+" read/update: Open an internal file for update (both for input and output). The file must already exist. "w+" write/update: Create an empty internal file and open it for update (both for input and output). If an internal file with the same name already exists its contents are discarded and the internal file is treated as a new empty file. "a+" append/update: Open an internal file for update (both for input and output) with all output operations writing data at the end of the file. Repositioning operations (IFileSeek, IFileSetpos, IFileRewind) affect the next input operations, but output operations move the position back to the end of internal file. The internal file is created if it does not exist. The letter "x" can be appended to any "w" specifier (to form "wx" or "w+x"). This subspecifier forces the function to fail if the internal file exists, instead of overwriting it. Sometimes a "b" is appended to indicate binary mode for reading and writing, but that is not necessary, so it is ignored.

Returns

If the internal file is successfully opened, the function returns a pointer to a structure, otherwise a NULL pointer is returned.

Example 1

Let's assume that one already has an GeoSci file, and one wants to add an internal file, named "somename", off of the root:

hid_t file_id;
IFILE *ifilep;

ifilep = IFileOpen(file_id,"/somename","w");
if(!ifilep) {
   printf("IFileOpen failed on /somename\n");
}

Example 2

Let's assume that one already has an GeoSci file, and one wants to add an internal file inside another group:

hid_t file_id, group_id;
IFILE *ifilep;
bstring name=bfromcstr("/group1");
group_id = GS_GroupCreate(file_id,name);
bdestroy(name);
if(group_id < 0) {
   printf("GroupCreate failed on /group1\n");
   exit(-1);
}
ifilep = IFileOpen(file_id,"/group1/somename","w");
if(!ifilep) {
   printf("IFileOpen failed on /group1/somename\n");
   exit(-1);
}

Details

This function is meant to emulate as close as possible the standard C fopen() function.

For internal files open for update (those which include a "+" sign), on which both input and output operations are allowed, the file should be flushed (IFileFlush) or repositioned (IFileSeek, IFileSetpos, IFileRewind) between either a writing operation followed by a reading operation or a reading operation which did not reach the end-of-file followed by a writing operation.

When appropriate, this routine creates a single-dimensional unsigned-8-bit dataset with the given name. The components of the pathname above the filename must already exist, and be HDF5 groups in order for this to work.

Note that even if you intend to only read from an IFile, you need to open the GeoSci file for reading AND writing ("r+"). This is because the state of the internal file is written to metadata in the GeoSci file, even if one is only reading from the IFile.

Implementation

For developers, the details of the implementation are presented here.

The complete list of all 34 IFile-related functions is given below:

• GS_ObjectIsIFile (also contains ObjectIsIFileByID)
• GS_ObjectIsMetadataIFile
• DatasetGetType
• DatasetSetType
• IFileAllocate
• IFileClearError
• IFileClose
• IFileEOF
• IFileError
• IFileFlush
• IFileGetc
• IFileGets
• IFileGetWrite
• IFileOpen
• IFilePerror
• IFilePrintf
• IFilePutc
• IFilePuts
• IFileReadAccess
• IFileRead
• IFileReadStatus
• IFileRewind
• IFileScanf
• IFileSeek
• IFileSetEOF
• IFileSetWriteability
• IFileSetWrite
• IFileSize
• IFileTell
• IFileTruncate
• IFileWriteAccess
• IFileWrite
• IFileWriteStatus
• IFileWriteStatusMessage

Some of these are named based on the standard C library functions that they emulate. Others are implementation-specific functions.

The overall idea of a IFile is that of a HDF5 dataset. This dataset is 1-dimensional, with a datatype of unsigned-8-bit. It is infinitely extendable. It has three string attributes:

• writeable: "TRUE" or "FALSE". The user can set this so that don't accidentally over-write it or delete it. All IFiles are created with writeable="TRUE"
• access: an integer betwen 0 and 6, converted to a string. Corresponds to one of the following #define'd parameters:
  • IFILE_CLOSED 0
  • IFILE_R 1
  • IFILE_W 2
  • IFILE_A 3
  • IFILE_RP 4
  • IFILE_WP 5
  • IFILE_AP 6
  These are named based on the access string used during the IFileOpen() function-call, the "P" meaning "+". This keeps track of how the file was opened so only appropriate operations are allowed. Note that a file that is open cannot be opened by another command: the file must be CLOSED in order to be opened. This implements a very simple locking mechanism
• dataset_type: for an IFile this must be "10", which corresponds to the C #define GS_OBJECT_TYPE_IFILE This is needed because image rasters are stored as datasets as well, and we need to distinguish between these.

The returned data structure is defined as:

typedef struct {
  hid_t ifile_id;
  long int file_position;
  int readPastEOF;
  int last_operation_status;
  bstring last_operation_status_message;
  int access;
  long int size;
} IFILE;

The parameters in this structure are defined as follows:

• ifile_id: the HDF5 object-id for this dataset.
• file_position: This is the next byte to read-from or write-to, where file_position=0 means to read/write the first byte in the file.
• readPastEOF: "TRUE"=1 or "FALSE"=0. Whether the previous operation tried to read past the last byte in the file.
• last_operation_status: "SUCCESS"=1 or "FAILURE"=0 Each operation on the IFile sets this.
• last_operation_status_message: a string written by each of the IFile functions, whether they succeed or fail.
• access: A copy of the dataset-metadata entry.
• size: The current file size in bytes. This is obtained when opened using HDF5 function calls. Thereafter it is updated by the the functions as needed.

Functions that deal with these metadata items are given below. Generally the user should never call any of these, except for:

• IFileSetWriteability() for setting the writeability of an IFile when it is closed.
• IFileError() for determining error status
• IFilePerror() for printing the latest error
• IFileEOF() for determining the EOF status of last read
• IFileSeek() for moving the file position
• IFileTell() for determining the file position
• IFileRewind() for setting the file position to 0

• GS_ObjectIsIFile – must be a dataset with dataset_type="1"
• GS_DatasetGetType– returns the dataset_type
• GS_DatasetSetType– sets the dataset_type
• IFileClearError – sets last_operation_status="SUCCESS" and sets last_operation_status_message
• IFileError – returns TRUE if last_operation_status="FAILURE"
• IFilePerror – prints last_operation_status_message
• IFileReadStatus – reads last_operation_status, and last_operation_status_message
• IFileWriteStatus – writes last_operation_status, and last_operation_status_message
• IFileWriteStatusMessage – writes last_operation_status_message
• IFileEOF – returns TRUE if readPastEOF="TRUE"
• IFileSetEOF – writes to readPastEOF
• IFileGetWrite – returns TRUE If writeable="TRUE"
• IFileSetWrite – sets writeability (developer function)
• IFileSetWriteability – sets writeability (user function)
• IFileReadAccess – reads access
• IFileWriteAccess – writes access
• IFileSeek – sets file_position
• IFileTell – reads file_position
• IFileRewind – sets file_position to "0"

Functions to deal with the file size directly:

• IFileTruncate – sets size of file (can shrink or grow)
• IFileAllocate – expands file size if needed
• IFileSize – gets the current file size from the struct
• IFileSizeHDF – gets the current file size from HDF

Other functions that the user can use include:

• IFileOpen – open an IFile
• IFileClose – close an IFile
• IFileFlush – flush any changes to the IFile to disk
• IFileGetc – read a single character
• IFileGets – read a newline-terminated string
• IFileRead – read a set number of bytes
• IFileScanf – formatted-read from next "line"
• IFilePutc – write a single character
• IFilePuts – write a newline-terminated string
• IFileWrite – write a set number of bytes
• IFilePrintf – write a formatted string

Note that there is only ONE COPY of the file state, so there can only be one process that is using it at one time. This is on purpose so that there are no parallel-read-write issues.

int IFilePerror	(	IFILE *	ifilep,
		const char *	str
	)

IFilePerror prints latest error for an internal file.

See also

IFileOpen, IFileClose

Parameters

[in]	ifilep	The struct of the open internal file.
[in]	str	String containing a custom message to be printed before the error message itself. If it is a null pointer, no preceding custom message is printed, but the error message is still printed. By convention, the name of the application itself is generally used as parameter.

Returns

TRUE is returned on success, FALSE otherwise.

This function should be called right after the error was produced, otherwise the error of interest can be overwritten by calls to other functions.

Example

Let's assume that one already has an GeoSci file, and one wants to print the latest error related to an internal file named "/somename".

hid_t file_id;
IFILE *ifilep;

ifilep = IFileOpen(file_id,"/somename","w");
if(!ifilep) {
   printf("IFileOpen failed on /somename\n");
}

if(!IFilePerror(ifilep,NULL)){
   printf("perror failed\n");
}

Details

Prints the latest error message related to the internal file to stdout, optionally preceded by the custom message provided in str. This function is meant to emulate as close as possible the standard C perror() function.

int IFilePrintf	(	IFILE *	ifilep,
		const char *	format,
			...
	)

IFilePrintf writes formatted data to an internal file.

See also

IFileOpen(), IFileClose()

Parameters

[in]	ifilep	The struct of the open internal file.
[in]	format	String that contains the text to be written to the internal file. It can optionally contain embedded format specifiers that are replaced by the values specified in subsequent additional arguments and formatted as requested. See docs for fscanf() in any C book for the complete details.
[in]	...	(additional arguments) Depending on the format string, the function may expect a sequence of additional arguments, each containing a pointer to allocated storage where the interpretation of the extracted characters is stored with the appropriate type. There should be at least as many of these arguments as the number of values stored by the format specifiers. Additional arguments are ignored by the function.

Returns

On success, the function returns the number of characters successfully written.

If a reading error happens or the end-of-file is reached while reading, the proper indicator is set (IFileEOF() or IFileError()). And, if either happens before any data could be successfully written, ERROR is returned.

The error_string variable is also set to a system-specific error code on failure.

Example

Let's assume that one already has an GeoSci file, and one wants to write a string to the next line of the internal file named "/somename".

hid_t file_id;
IFILE *ifilep;
int an_int;
int n;

ifilep = IFileOpen(file_id,"/somename","w");
if(!ifilep) {
   printf("IFileOpen failed on /somename\n");
}
an_int = 5;
n =IFilePrintf(ifilep, "The value is: %d", an_int);
if(n==1){
   printf("successfully wrote the integer: %d\n",an_int);
} else {
   printf("problem writing the integer\n");
}

Details

This function is meant to emulate as close as possible the standard C fprintf() function.

Writes the string pointed by format to the internal file. If format includes format specifiers (subsequences beginning with %), the additional arguments following format are formatted and inserted in the resulting string replacing their respective specifiers.

After the format parameter, the function expects at least as many additional arguments as specified by format.

int IFilePutc	(	IFILE *	ifilep,
		char	character
	)

IFilePutc writes a single character to an internal file.

See also

IFileOpen, IFileClose

Parameters

[in]	ifilep	The struct of the open internal file.
[in]	character	The character to write.

Returns

On success, TRUE is returned.

If some writing error happens, the function returns FALSE, and sets its error indicator (IFileError).

Exmaple

Let's assume that one already has an GeoSci file, and one wants to write the character 'a' to an internal file named "/somename".

hid_t file_id;
IFILE *ifilep;
int the_int_char;
char the_char;

ifilep = IFileOpen(file_id,"/somename","w");
if(!ifilep) {
   printf("IFileOpen failed on /somename\n");
}

the_char = 'a';
if(!IFilePutc(ifilep, the_char)){
   printf("write failed\n");
}

Details

This function is meant to emulate as close as possible the standard C fputc() function.

int IFilePuts	(	IFILE *	ifilep,
		const char *	string
	)

IFilePuts writes a string to an internal file.

See also

IFileOpen, IFileClose

Parameters

[in]	ifilep	The struct of the open internal file.
[in]	string	The character string to write.

Returns

On success, TRUE is returned. If some writing error happens, the function returns FALSE, and sets its error indicator (IFileError).

Example

Let's assume that one already has an GeoSci file, and one wants to write the character string "already" to an internal file named "/somename".

hid_t file_id;
IFILE *ifilep;

ifilep = IFileOpen(file_id,"/somename","w");
if(!ifilep) {
   printf("IFileOpen failed on /somename\n");
}

if(!IFilePuts(ifilep, "already")){
   printf("write failed\n");
}

Details

This function is meant to emulate as close as possible the standard C fputs() function.

size_t IFileRead	(	IFILE *	ifilep,
		void *	buf,
		int	size,
		int	count
	)

IFileRead reads the requested number of bytes from an internal file in a geosci file.

See also

IFileOpen, IFileClose

Parameters

[in]	ifilep	The struct of the open internal file.
[in,out]	buf	Pointer to an array where the bytes read are copied to. This must have at least size*count bytes of storage. Using a void pointer here allows the user to pass a buf variable of any type.
[in]	size	Size in bytes of each element to be read.
[in]	count	Number of elements to read. Each element has a size of "size" bytes.

Returns

The total number of elements successfully read is returned.

If this number differs from the count parameter, either a reading error occurred or the end-of-file was reached while reading. In both cases, the proper indicator is set, which can be checked with IFileError and IFileEOF, respectively.

If either size or count is less than or equal to zero, the function returns zero and both the internal-file state and the content pointed to by buf remain unchanged.

Example

Let's assume that one already has an GeoSci file, and one wants to read the next 10 characters from an internal file named "/somename".

hid_t file_id;
IFILE *ifilep;
char *buf;

buf = (char *)GMalloc(10*sizeof(char));
if(!buf){
   printf("GMalloc error\n");
   exit(-1);
}

ifilep = IFileOpen(file_id,"/somename","w");
if(!ifilep) {
   printf("IFileOpen failed on /somename\n");
}

if(IFileRead(ifilep, buf, sizeof(char),10) != 10){
   printf("read failed\n");
}

...use buf here....

Details

This function is meant to emulate as close as possible the standard C fread() function.

The types of size and count are purposely int and not size_t because if the user accidentally passes a negative value the value becomes a very big number when casted to an unsigned integer, which is what size_t is. In order to detect this error, int is used instead.

int IFileReadAccess

(

IFILE *

ifilep

)

IFileReadAccess reads access code of an internal file.

See also

IFileOpen, IFileClose

Parameters

[in]

ifilep

The struct of the open internal file.

Returns

On success, one of:
IFILE_CLOSED 0
IFILE_R 1
IFILE_W 2
IFILE_A 3
IFILE_RP 4
IFILE_WP 5
IFILE_AP 6
On failure, ERROR is returned.

Example

Let's assume that one already has an GeoSci file, and one wants to determine the access code for an internal file named "/somename".

hid_t file_id;
IFILE *ifilep;
int access_code;

ifilep = IFileOpen(file_id,"/somename","w");
if(!ifilep) {
   printf("IFileOpen failed on /somename\n");
}

access_code = IFileReadAccess(ifilep);
if(access_code<0){
   printf("could not obtain access code for internal file\n");
}

Details

This function is used by the IFile* functions to determine how to implement each function for a specific file access code.

int IFileReadAccessHDF

(

hid_t

dataset_id

)

IFileReadAccessHDF reads access code of an internal file.

See also

IFileOpen, IFileClose

Parameters

[in]

datset_id

The hdf-id of the open internal file dataset-object.

Returns

On success, one of:
IFILE_CLOSED 0
IFILE_R 1
IFILE_W 2
IFILE_A 3
IFILE_RP 4
IFILE_WP 5
IFILE_AP 6
On failure, ERROR is returned.

Example

Let's assume that one already has an GeoSci file, and one wants to determine the access code for an internal file named "/somename".

hid_t file_id;
his_t dataset_id;
int access_code;

dataset_id = GS_DatasetOpen(file_id,"/somename");
if(dataset_id < 0) {
   printf("IFileOpen failed on /somename\n");
}

access_code = IFileReadAccessHDF(dataset_id);
if(access_code<0){
   printf("could not obtain access code for internal file\n");
}

Details

This function is used by the IFile* functions to determine how to implement each function for a specific file access code.

int IFileReadALine	(	IFILE *	ifilep,
		char *	str,
		int	num
	)

IFileReadALine reads a string from an internal file.

IFileReadALine() reads characters from an internal file in a geosci file, and stores them as a string until the maximum number of characters have been read or either a newline or the end-of-file is reached, whichever happens first.

See also

IFileOpen, FileClose, IFileGets

Parameters

[in]	ifilep	The struct of the open internal file.
[in,out]	str	Pointer to an array of chars where the string read is copied.
[in]	num	Maximum number of characters to be copied into str (including the terminating null-character).

Returns

This function uses IFileGets() to read the data, any errors encountered will cause this routine to return ERROR.

If the read succeeds, but the last character read is NOT a newline, then it returns FALSE.

If there are no read errors, and a complete line is read, then TRUE is returned.

Example

Let's assume that one already has an GeoSci file, and one wants to read the next line of characters (up to the next "\n") from an internal file named "/somename".

hid_t file_id;
IFILE *ifilep;
char the_string[1000];

ifilep = IFileOpen(file_id,"/somename","w");
if(!ifielp) {
   printf("IFileOpen failed on /somename\n");
}

status = IFileReadALine(ifilep, the_string, 1000);
if(status==ERROR){
   printf("read failed\n");
} else if (status=FALSE){
   printf("string is incomplete\n");
} else {
   printf('complete string read successfully.\n");

   ...use the_string here....
}

Details

Similar to IFileGets(), but provides clearer return error codes.

int IFileReadStatus	(	IFILE *	ifilep,
		char **	message
	)

IFileReadStatus reads the status properties of an internal file.

See also

IFileOpen, IFileClose

Parameters

[in]	ifilep	The struct of the open internal file.
[in]	message	Returned Message associated with the status. No need to GFree it when done.

Returns

On success, the return value is one of:
IFILE_SUCCESS – the last IFile operation succeeded
IFILE_FAILURE – the last IFile operation failed
On failure, FALSE is returned. The error_string variable is also set to a system-specific error code on failure.

Example

Let's assume that one already has an GeoSci file, and one has created an internal file is named "/somename" and the last write operation may have failed. Let's get the status.

hid_t file_id;
IFILE *ifilep;
int status;
char *status_str;

ifilep = IFileOpen(file_id,"/somename","w");
if(!ifilep) {
   printf("IFileOpen failed on /somename\n");
}

status = IFileReadStatus(ifilep,&status_str);
if(!status){
   printf("IFileReadStatus failed\n");
} else {
   if(status == IFILE_SUCCESS){
      printf("status of last operation is: SUCCESS\n");
   } else {
      printf("status of last operation is: FAILURE\n");
   } // endif 
   printf("status message: %s\n",status_str);
} // endif

Details

This function encapsulates reading the IFile status metadata.

int IFileRewind

(

IFILE *

ifilep

)

IFileRewind moves to the start of an internal file.

See also

IFileOpen, IFileClose

Parameters

[in]

ifilep

The struct of the open internal file.

Returns

TRUE is returned on success, FALSE otherwise. The error_string variable is also set to a system-specific error code on failure.

Example

Let's assume that one already has an GeoSci file, and one wants to rewind an internal file named "/somename".

hid_t file_id;
IFILE *ifilep;

ifilep = IFileOpen(file_id,"/somename","w");
if(!ifilep) {
   printf("IFileOpen failed on /somename\n");
}

if(!IFileRewind(ifilep)){
   printf("rewind failed\n");
}

Details

This function is meant to emulate as close as possible the standard C rewind() function.

int IFileScanf	(	IFILE *	ifilep,
		const char *	format,
			...
	)

IFileScanf reads formatted data from an internal file.

See also

IFileOpen, IFileClose

Parameters

[in]	ifilep	The struct of the open internal file.
[in]	format	String that contains a sequence of characters that control how characters extracted from the stream are treated. See docs for fscanf() in any C book for the complete details.
[in]	...	(additional arguments) Depending on the format string, the function may expect a sequence of additional arguments, each containing a pointer to allocated storage where the interpretation of the extracted characters is stored with the appropriate type. There should be at least as many of these arguments as the number of values stored by the format specifiers. Additional arguments are ignored by the function. These arguments are expected to be pointers: to store the result of a IFileScanf operation on a regular variable, its name should be preceded by the reference operator (&) (see example).

Returns

On success, the function returns the number of items of the argument list successfully filled. This count can match the expected number of items or be less (even zero) due to a matching failure, a reading error, or the reaching of the end-of-file.

If a reading error happens or the end-of-file is reached while reading, the proper indicator is set (IFileEOF() or IFileError()). And, if either happens before any data could be successfully read, ERROR is returned.

The error_string variable is also set to a system-specific error code on failure.

Example

Let's assume that one already has an GeoSci file, and one wants to read an integer from the next line of the internal file named "/somename".

hid_t file_id;
IFILE *ifilep;
int an_int;
int n;

ifilep = IFileOpen(file_id,"/somename","w");
if(!ifilep) {
   printf("IFileOpen failed on /somename\n");
}
n =IFileScanf(ifilep, "%d", &an_int);
if(n==1){
   printf("successfully read the integer: %d\n",an_int);
} else {
   printf("problem reading the integer\n");
}

Details

This function is meant to emulate as close as possible the standard C fscanf() function.

int IFileSeek	(	IFILE *	ifilep,
		long int	offset,
		int	origin
	)

IFileSeek moves to a position in an internal file.

See also

IFileOpen, IFileClose

Parameters

[in]	ifilep	The struct of the open internal file.
[in]	offset	Offset, in bytes, from a reference position where the new file pointer is desired to go. [in] origin Position used as reference for the offset. Specify one of the following constants : Constant Reference Position SEEK_SET Start of file SEEK_CUR Current position in the file SEEK_END End of file

Returns

TRUE is returned on success, FALSE otherwise.

For situations where the new position would be before the first byte, the file pointer position is not changed, and FALSE is returned.

For situations where the new position is beyond the last byte, this is allowed, but a subsequent read will fail. A subsequent write will "fill in" NULL bytes to get to this point before writing.

The error_string variable is also set to a system-specific error code on failure.

Example

Let's assume that one already has an GeoSci file, and one wants to skip to byte 35 in an internal file named "/somename".

hid_t file_id;
IFILE *ifilep;

ifilep = IFileOpen(file_id,"/somename","w");
if(!ifilep) {
   printf("IFileOpen failed on /somename\n");
}

if(!IFileSeek(ifilep, 35L, SEEK_SET)){
   printf("seek failed\n");
}

Details

This function is meant to emulate as close as possible the standard C fseek() function.

int IFileSetEOF	(	IFILE *	ifilep,
		int	value
	)

IFileSetEOF sets End-Of-File condition on an internal file.

See also

IFileOpen, IFileClose

Parameters

[in]	filep	The struct of the open internal file.
[in]	value	The value to set the EOF condition to, one of: TRUE (if there was an EOF ), or: FALSE (there was not an EOF )

Returns

TRUE is returned when the condition is set successfully, FALSE if not. The error_string variable is also set to a system-specific error code on failure.

Example

Let's assume that one already has an GeoSci file, and one wants to set that the previous read hit an EOF on an internal file named "/somename" succeeded or not.

hid_t file_id;
IFILE *ifilep;

ifilep = IFileOpen(file_id,"/somename","w");
if(!ifilep < 0) {
   printf("IFileOpen failed on /somename\n");
}
if(!IFileSetEOF(ifilep, TRUE)){
   printf("could not set EOF condition\n");
} else {
   printf("successfully set EOF condition to TRUE\n");
}

Details

This function is used internally by the IFile* functions, and is not meant for usage by the normal user.

int IFileSetWrite	(	IFILE *	ifilep,
		int	property
	)

IFileSetWrite sets the read/write property of an internal file.

See also

IFileOpen, IFileClose

Parameters

[in]	ifilep	The struct of the open internal file.
[in]	property	The value to set the read/write property to: GS_READ – internal file set to read-only mode GS_WRITE – internal file set to read and write mode

Returns

TRUE is returned on success, FALSE otherwise. The error_string variable is also set to a system-specific error code on failure.

Example

Let's assume that one already has an GeoSci file, and one wants to create an internal file is named "/somename" and make it writeable. This is used by the internal IFileOpen routine when creating a new internal file.

hid_t file_id;
IFILE *ifilep;

ifilep = IFileOpen(file_id,"/somename","w");
if(!ifilep) {
   printf("IFileOpen failed on /somename\n");
}

if(!IFileSetWrite(ifilep,GS_WRITE)){
   printf("IFileSetWrite to read-write failed\n");
}

Details

This function is meant to enable IFileOpen to make an internal file have read and write rights on creation.

int IFileSetWriteability	(	hid_t	file_id,
		const char *	name,
		int	property
	)

IFileSetWriteability sets the read/write property of an internal file.

See also

IFileOpen, IFileClose

Parameters

[in]	file_id	The handle of the open geosci file.
[in]	name	Name of the internal file whose properties need to be altered. The internal file must not be open, otherwise this operation will fail.
[in]	property	The value to set the read/write property to: GS_READ – internal file set to read-only mode GS_WRITE – internal file set to read and write mode

Returns

TRUE is returned on success, FALSE otherwise. The error_string variable is also set to a system-specific error code on failure.

Example

Let's assume that one already has an GeoSci file, and one wants to make sure the file is not writeable accidentally. The internal file is named "/somename".

hid_t file_id;

if(!IFileSetWriteability(file_id,"/somename",GS_READ)){
   printf("IFileSetWriteability to read-only failed\n");
}

Details

This function is meant to enable a user to make an internal file have read and write rights like in the standard file system.

long int IFileSize

(

IFILE *

ifilep

)

IFileSize gets the #bytes in an internal file.

See also

IFileOpen, IFileClose

Parameters

[in]

ifilep

The struct of the open internal file.

Returns

On success, the number of characters in the internal file is returned. -1 is returned on error.

Example

Let's assume that one already has an GeoSci file, and one wants to know the size of an internal file named "/somename".

hid_t file_id;
IFILE *ifilep;
long int numbytes;

ifilep = IFileOpen(file_id,"/somename","w");
if(!ifilep) {
   printf("IFileOpen failed on /somename\n");
}

numbytes = IFileSize(ifilep);
if(numbytes < 0) {
   printf("failed to get file size\n");
}

Details

There is no equivalent standard C function to get the size of an open file.

long int IFileSizeHDF

(

IFILE *

ifilep

)

IFileSizeHDF gets the #bytes in an internal file.

See also

IFileOpen, IFileClose

Parameters

[in]

ifilep

The struct of the open internal file.

Returns

On success, the number of characters in the internal file is returned. -1 is returned on error.

Example

Let's assume that one already has an GeoSci file, and one wants to know the size of an internal file named "/somename".

hid_t file_id;
IFILE *ifilep;
long int numbytes;

ifilep = IFileOpen(file_id,"/somename","w");
if(ifilep < 0) {
   printf("IFileOpen failed on /somename\n");
}

numbytes = IFileSizeHDF(ifilep);
if(numbytes < 0) {
   printf("failed to get file size\n");
}

Details

There is no equivalent C function to get the size of an open file. This is distinct from IFileSize() because this function asks the HDF5 system how big the dataset is. This is useful when we need to initialize the size when we open an existing IFILE.

long int IFileTell

(

IFILE *

ifilep

)

IFileTell retrieves the current read/write position in an internal file.

See also

IFileOpen, IFileClose

Parameters

[in]

ifilep

The struct of the open internal file.

Returns

The position in the file is returned on success, and -1L on failure. The error_string variable is also set to a system-specific error code on failure.

Example

Let's assume that one already has an GeoSci file, and one wants to find the position of the file-pointer in an internal file named "/somename".

hid_t file_id;
IFILE *ifilep;
long int position;

ifilep = IFileOpen(file_id,"/somename","w");
if(!ifilep) {
   printf("IFileOpen failed on /somename\n");
}

position = IFileTell(ifilep);
if(position < 0){
   printf("tell failed\n");
}

Details

This function is meant to emulate as close as possible the standard C ftell() function.

int IFileTruncate	(	IFILE *	ifilep,
		long int	length
	)

IFileTruncate changes the size of an internal file.

See also

IFileOpen, IFileClose

Parameters

[in]	ifilep	The struct of the open internal file.
[in]	length	The desired length, in bytes, of the file. Must be >= 0.

Returns

TRUE is returned on success, FALSE otherwise. The error_string variable is also set to a system-specific error code on failure.

Example

Let's assume that one already has an GeoSci file, and one wants to make the new size be 1000 bytes for an internal file named "/somename".

hid_t file_id;
IFILE *ifilep;
long int icount;

ifilep = IFileOpen(file_id,"/somename","w");
if(!ifilep) {
   printf("IFileOpen failed on /somename\n");
}

icount = 1000L;
if(!IFileTruncate(ifilep, icount)){
   printf("truncate failed\n");
}

Details

If the size of the file is less than length, then the file is increased to this size. If the size of the file is greater than length, then the file is decreased to this size. This function is meant to emulate as close as possible the standard C ftruncate() function.

int IFileWrite	(	IFILE *	ifilep,
		const void *	buf,
		int	size,
		int	count
	)

IFileWrite writes bytes to an internal file.

See also

IFileOpen, IFileClose

Parameters

[in]	ifilep	The struct of the open internal file.
[in,out]	buf	Pointer to an array where the bytes to write are read from. This must have at least size*count bytes of storage. Using a void pointer here allows the user to pass a buf variable of any type.
[in]	size	Size in bytes of each element to be written.
[in]	count	Number of elements to write. Each element has a size of "size" bytes.

Returns

The total number of elements successfully written is returned.

If this number differs from the count parameter, a writing error prevented the function from completing. In this case, the error indicator (IFileError) will be set for the stream.

If either size or count is less than or equal to zero, the function returns zero and both the internal-file state and the content pointed to by buf remain unchanged.

Example

Let's assume that one already has an GeoSci file, and one wants to write 10 ints in an int vector (starting at index 5) to an internal file named "/somename".

hid_t file_id;
IFILE *ifilep;
int intvec[100];

ifilep = IFileOpen(file_id,"/somename","w");
if(!ifilep < 0) {
   printf("IFileOpen failed on /somename\n");
}

if(!IFileWrite(ifilep,intvec+5, sizeof(int),10L )){
   printf("write failed\n");
}

Details

This function is meant to emulate as close as possible the standard C fwrite() function.

int IFileWriteAccess	(	IFILE *	ifilep,
		int	code
	)

IFileWriteAccess writes a new access code for an internal file.

See also

IFileOpen, IFileClose

Parameters

[in]	ifilep	The struct of the open internal file.
[in]	code	The access code one wishes to write to the file, one of: IFILE_CLOSED 0 IFILE_R 1 IFILE_W 2 IFILE_A 3 IFILE_RP 4 IFILE_WP 5 IFILE_AP 6

Returns

TRUE is returned on success, FALSE on failure.

Example

Let's assume that one already has an GeoSci file, and one wants to set the access code to read-only for an internal file named "/somename".

hid_t file_id;
IFILE *ifilep;
int access_code;

ifilep = IFileOpen(file_id,"/somename","w");
if(!ifilep) {
   printf("IFileOpen failed on /somename\n");
}

if(!IFileWriteAccess(ifilep, IFILE_R)){
   printf("could not set access code for internal file\n");
}

Details

This function is used by the IFile* functions to set the internal-file access policy. They can be read, write, append, read-and-update, write-and-update, append-and-update, as well as closed. This routine is for use by the IFile* routines, and not normally for use by ordinary users.

int IFileWriteStatus	(	IFILE *	ifilep,
		int	status,
		const char *	message
	)

IFileWriteStatus writes the status properties of an internal file.

See also

IFileOpen, IFileClose

Parameters

[in]	ifilep	The struct of the open internal file.
[in]	status	The value to set the status property to: IFILE_SUCCESS – the last IFile operation succeeded IFILE_FAILURE – the last IFile operation failed
[in]	message	Message associated with the status.

Returns

TRUE is returned on success, FALSE otherwise. The error_string variable is also set to a system-specific error code on failure.

Example

Let's assume that one already has an GeoSci file, and one has created an internal file is named "/somename" and the last write operation failed (using IFilePutc()).

hid_t file_id;
IFILE *ifilep;

ifilep = IFileOpen(file_id,"/somename","w");

if(!IFileWriteStatus(ifilep,IFILE_FAILURE,"IFilePutc() failed")){
   printf("IFileWriteStatus failed\n");
}

Details.

This function encapsulates writing the IFile status metadata. This function would not be used by the ordinary user.

int IFileWriteStatusMessage	(	IFILE *	ifilep,
		const char *	message
	)

IFileWriteStatusMessage writes the status message of an internal file.

See also

IFileOpen, FileClose, IFileWriteStatus

Parameters

[in]	ifilep	The struct of the open internal file.
[in]	message	Message associated with the status.

Returns

TRUE is returned on success, FALSE otherwise. The error_string variable is also set to a system-specific error code on failure.

Example

Let's assume that one already has an GeoSci file, and one has created an internal file is named "/somename" and one wishes to write a status message that the last operation caused the file to hit the end-of-file.

hid_t file_id;
IFILE *ifilep;

ifilep = IFileOpen(file_id,"/somename","w");
if(!ifilep) {
   printf("IFileOpen failed on /somename\n");
}

if(!IFileWriteStatusMessage(ifilep,"IFilePutc() hit EOF")){
   printf("IFileWriteStatusMessage failed\n");
}

Details

This function encapsulates writing the IFile status metadata. This function would not normally be called by a user.