next up previous 193
Next: About this document ...
Up: Routine Descriptions
Previous: gsdItem - Get GSD item by number


gsdOpenRead - 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 *file, float *version, char *label, int *no_items, FILE **fptr, void **file_dsc, void **item_dsc, char **data_ptr );

Arguments:

char *file (Given)
The name of the GSD file to be opened.
float *version (Returned)
The GSD file version number.
char *label (Returned)
The GSD file label. This is a null-terminated string. It should be declared by the calling routine with length 41.
int *no_items (Returned)
The number of items in the GSD file.
FILE **fptr (Returned)
The file descriptor for the GSD file opened.
void **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 **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 **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:

int gsdOpenRead();
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"
Copyright
Copyright (C) 1986-1999 Particle Physics and Astronomy Research Council. All Rights Reserved.



next up previous 193
Next: About this document ...
Up: Routine Descriptions
Previous: gsdItem - Get GSD item by number

The Global Section Datafile (GSD) access library
Starlink User Note 229
Tim Jenness, Remo Tilanus,
Horst Meyerdierks, Jon Fairclough
16 December 1999
E-mail:ussc@star.rl.ac.uk