Open a GSD file for reading and map it

Description:

This routine opens the named GSD file and reads its contents into memory. It returns a standard C file descriptor, a GSD file descriptor, a pointer to the array of GSD item descriptors, and a pointer to the collective data.

This routine allocates memory to accommodate the GSD file descriptor, the GSD item descriptors, and the data from the GSD file. It also leaves the GSD file open. Any call to this routine must be matched with a call to gsdClose with the information returned by this routine. gsdClose will close the file and release the memory allocated by this routine.

Invocation

int gsdOpenRead( char $\ast$file, float $\ast$version, char $\ast$label, int $\ast$no_items, FILE $\ast$$\ast$fptr, void $\ast$$\ast$file_dsc, void $\ast$$\ast$item_dsc, char $\ast$$\ast$data_ptr );

Arguments

char $\ast$file (Given)
The name of the GSD file to be opened.
float $\ast$version (Returned)
The GSD file version number.
char $\ast$label (Returned)
The GSD file label. This is a null-terminated string. It should be declared by the calling routine with length 41.
int $\ast$no_items (Returned)
The number of items in the GSD file.
FILE $\ast$$\ast$fptr (Returned)
The file descriptor for the GSD file opened.
void $\ast$$\ast$file_dsc (Returned)
The GSD file descriptor. This routine allocates the memory necessary and fills it with the relevant information from the GSD file. A call to gsdClose will release this memory (given the pointer).
void $\ast$$\ast$item_dsc (Returned)
The array of GSD item descriptors. This routine allocates the memory necessary and fills it with the relevant information from the GSD file. A call to gsdClose will release this memory (given the pointer). The number of array elements is returned in no_items.
char $\ast$$\ast$data_ptr (Returned)
The buffer with all the data from the GSD file. This routine allocates the memory necessary and reads the data into it. A call to gsdClose will release this memory (given the pointer). The size of this buffer does not matter, but it can be calculated in bytes as file_dsc-$>$end_data - file_dsc-$>$str_data $+$ 1 if you know what a struct file_descriptor looks like.

Returned Value

Status. Status is set to
• [1:] Failure to open named file,

• [2:] Failure to read file_dsc from file,

• [3:] Failure to allocate memory for item_dsc,

• [4:] Failure to read item_dsc from file,

• [6:] Failure to read data_ptr from file,

• [7:] Failure to allocate memory for data_ptr,

• [0:] Otherwise.

Prototype

available via #include "gsd.h"