grib_api: grib_api.h File Reference

- Main Page
- Modules
- Files
- Related Pages
- Examples

# grib_api.h File Reference

Copyright 2005-2015 ECMWF. More...

## Defines
#define | GRIB_KEYS_ITERATOR_ALL_KEYS 0
#define | GRIB_KEYS_ITERATOR_SKIP_READ_ONLY (1<<0)
#define | GRIB_KEYS_ITERATOR_SKIP_OPTIONAL (1<<1)
#define | GRIB_KEYS_ITERATOR_SKIP_EDITION_SPECIFIC (1<<2)
#define | GRIB_KEYS_ITERATOR_SKIP_CODED (1<<3)
#define | GRIB_KEYS_ITERATOR_SKIP_COMPUTED (1<<4)
#define | GRIB_KEYS_ITERATOR_SKIP_DUPLICATES (1<<5)
#define | GRIB_KEYS_ITERATOR_SKIP_FUNCTION (1<<6)
#define | GRIB_SUCCESS 0
| No error.
#define | GRIB_END_OF_FILE -1
| End of ressource reached.
#define | GRIB_INTERNAL_ERROR -2
| Internal error.
#define | GRIB_BUFFER_TOO_SMALL -3
| Passed buffer is too small.
#define | GRIB_NOT_IMPLEMENTED -4
| Function not yet implemented.
#define | GRIB_7777_NOT_FOUND -5
| Missing 7777 at end of message.
#define | GRIB_ARRAY_TOO_SMALL -6
| Passed array is too small.
#define | GRIB_FILE_NOT_FOUND -7
| File not found.
#define | GRIB_CODE_NOT_FOUND_IN_TABLE -8
| Code not found in code table.
#define | GRIB_STRING_TOO_SMALL_FOR_CODE_NAME -9
| Code cannot unpack because of string too small.
#define | GRIB_WRONG_ARRAY_SIZE -10
| Array size mismatch.
#define | GRIB_NOT_FOUND -11
| Key/value not found.
#define | GRIB_IO_PROBLEM -12
| Input output problem.
#define | GRIB_INVALID_MESSAGE -13
| Message invalid.
#define | GRIB_DECODING_ERROR -14
| Decoding invalid.
#define | GRIB_ENCODING_ERROR -15
| Encoding invalid.
#define | GRIB_NO_MORE_IN_SET -16
| Code cannot unpack because of string too small.
#define | GRIB_GEOCALCULUS_PROBLEM -17
| Problem with calculation of geographic attributes.
#define | GRIB_OUT_OF_MEMORY -18
| Out of memory.
#define | GRIB_READ_ONLY -19
| Value is read only.
#define | GRIB_INVALID_ARGUMENT -20
| Invalid argument.
#define | GRIB_NULL_HANDLE -21
| Null handle.
#define | GRIB_INVALID_SECTION_NUMBER -22
| Invalid section number.
#define | GRIB_VALUE_CANNOT_BE_MISSING -23
| Value cannot be missing.
#define | GRIB_WRONG_LENGTH -24
| Wrong message length.
#define | GRIB_INVALID_TYPE -25
| Invalid key type.
#define | GRIB_WRONG_STEP -26
| Unable to set step.
#define | GRIB_WRONG_STEP_UNIT -27
| Wrong units for step (step must be integer).
#define | GRIB_INVALID_FILE -28
| Invalid file id.
#define | GRIB_INVALID_GRIB -29
| Invalid grib id.
#define | GRIB_INVALID_INDEX -30
| Invalid index id.
#define | GRIB_INVALID_ITERATOR -31
| Invalid iterator id.
#define | GRIB_INVALID_KEYS_ITERATOR -32
| Invalid keys iterator id.
#define | GRIB_INVALID_NEAREST -33
| Invalid nearest id.
#define | GRIB_INVALID_ORDERBY -34
| Invalid order by.
#define | GRIB_MISSING_KEY -35
| Missing a key from the fieldset.
#define | GRIB_OUT_OF_AREA -36
| The point is out of the grid area.
#define | GRIB_CONCEPT_NO_MATCH -37
| Concept no match.
#define | GRIB_NO_DEFINITIONS -38
| Definitions files not found.
#define | GRIB_WRONG_TYPE -39
| Wrong type while packing.
#define | GRIB_END -40
| End of resource.
#define | GRIB_NO_VALUES -41
| Unable to code a field without values.
#define | GRIB_WRONG_GRID -42
| Grid description is wrong or inconsistent.
#define | GRIB_END_OF_INDEX -43
| End of index reached.
#define | GRIB_NULL_INDEX -44
| Null index.
#define | GRIB_PREMATURE_END_OF_FILE -45
| End of ressource reached when reading message.
#define | GRIB_INTERNAL_ARRAY_TOO_SMALL -46
| An internal array is too small.
#define | GRIB_MESSAGE_TOO_LARGE -47
| Message is too large for the current architecture.
#define | GRIB_CONSTANT_FIELD -48
| Constant field.
#define | GRIB_SWITCH_NO_MATCH -49
| Switch unable to find a matching case.
## Typedefs
typedef struct grib_handle | grib_handle
typedef struct grib_multi_handle | grib_multi_handle
typedef struct grib_context | grib_context
typedef struct grib_iterator | grib_iterator
typedef struct grib_nearest | grib_nearest
typedef struct grib_keys_iterator | grib_keys_iterator
typedef struct grib_index | grib_index
typedef void(* | grib_free_proc )(const grib_context *c, void *data)
| Grib free procedure, format of a procedure referenced in the context that is used to free memory.
typedef void *(* | grib_malloc_proc )(const grib_context *c, size_t length)
| Grib malloc procedure, format of a procedure referenced in the context that is used to allocate memory.
typedef void *(* | grib_realloc_proc )(const grib_context *c, void *data, size_t length)
| Grib realloc procedure, format of a procedure referenced in the context that is used to reallocate memory.
typedef void(* | grib_log_proc )(const grib_context *c, int level, const char *mesg)
| Grib loc proc, format of a procedure referenced in the context that is used to log internal messages.
typedef void(* | grib_print_proc )(const grib_context *c, void *descriptor, const char *mesg)
| Grib print proc, format of a procedure referenced in the context that is used to print external messages.
typedef size_t(* | grib_data_read_proc )(const grib_context *c, void *ptr, size_t size, void *stream)
| Grib data read proc, format of a procedure referenced in the context that is used to read from a stream in a resource.
typedef size_t(* | grib_data_write_proc )(const grib_context *c, const void *ptr, size_t size, void *stream)
| Grib data read write, format of a procedure referenced in the context that is used to write to a stream from a resource.
typedef off_t(* | grib_data_tell_proc )(const grib_context *c, void *stream)
| Grib data tell, format of a procedure referenced in the context that is used to tell the current position in a stream.
typedef off_t(* | grib_data_seek_proc )(const grib_context *c, off_t offset, int whence, void *stream)
| Grib data seek, format of a procedure referenced in the context that is used to seek the current position in a stream.
typedef int(* | grib_data_eof_proc )(const grib_context *c, void *stream)
| Grib data eof, format of a procedure referenced in the context that is used to test end of file.
## Functions
grib_index * | grib_index_new_from_file (grib_context *c, char *filename, const char *keys, int *err)
| Create a new index form a file.
int | grib_index_get_size (grib_index *index, const char *key, size_t *size)
| Get the number of distinct values of the key in argument contained in the index.
int | grib_index_get_long (grib_index *index, const char *key, long *values, size_t *size)
| Get the distinct values of the key in argument contained in the index.
int | grib_index_get_double (grib_index *index, const char *key, double *values, size_t *size)
| Get the distinct values of the key in argument contained in the index.
int | grib_index_get_string (grib_index *index, const char *key, char **values, size_t *size)
| Get the distinct values of the key in argument contained in the index.
int | grib_index_select_long (grib_index *index, const char *key, long value)
| Select the message subset with key==value.
int | grib_index_select_double (grib_index *index, const char *key, double value)
| Select the message subset with key==value.
int | grib_index_select_string (grib_index *index, const char *key, char *value)
| Select the message subset with key==value.
grib_handle * | grib_handle_new_from_index (grib_index *index, int *err)
| Create a new handle from an index after having selected the key values.
void | grib_index_delete (grib_index *index)
| Delete the index.
int | grib_count_in_file (grib_context *c, FILE *f, int *n)
| Counts the messages contained in a file resource.
grib_handle * | grib_handle_new_from_file (grib_context *c, FILE *f, int *error)
| Create a handle from a file resource.
grib_handle * | grib_handle_new_from_message (grib_context *c, void *data, size_t data_len)
| Create a handle from a user message in memory.
grib_handle * | grib_handle_new_from_multi_message (grib_context *c, void **data, size_t *data_len, int *error)
| Create a handle from a user message in memory.
grib_handle * | grib_handle_new_from_message_copy (grib_context *c, const void *data, size_t data_len)
| Create a handle from a user message.
grib_handle * | grib_handle_new_from_template (grib_context *c, const char *res_name)
| Create a handle from a read_only template resource.
grib_handle * | grib_handle_new_from_samples (grib_context *c, const char *res_name)
| Create a handle from a message contained in a samples directory.
grib_handle * | grib_handle_clone (grib_handle *h)
| Clone an existing handle using the context of the original handle, The message is copied and reparsed.
int | grib_handle_delete (grib_handle *h)
| Frees a handle, also frees the message if it is not a user message.
grib_multi_handle * | grib_multi_handle_new (grib_context *c)
| Create an empty multi field handle.
int | grib_multi_handle_append (grib_handle *h, int start_section, grib_multi_handle *mh)
| Append the sections starting with start_section of the message pointed by h at the end of the multi field handle mh.
int | grib_multi_handle_delete (grib_multi_handle *mh)
| Delete multi field handle.
int | grib_multi_handle_write (grib_multi_handle *mh, FILE *f)
| Write a multi field handle in a file.
int | grib_get_message (grib_handle *h, const void **message, size_t *message_length)
| getting the message attached to a handle
int | grib_get_message_copy (grib_handle *h, void *message, size_t *message_length)
| getting a copy of the message attached to a handle
grib_iterator * | grib_iterator_new (grib_handle *h, unsigned long flags, int *error)
| Create a new iterator from a handle, using current geometry and values.
int | grib_iterator_next (grib_iterator *i, double *lat, double *lon, double *value)
| Get the next value from an iterator.
int | grib_iterator_previous (grib_iterator *i, double *lat, double *lon, double *value)
| Get the previous value from an iterator.
int | grib_iterator_has_next (grib_iterator *i)
| Test procedure for values in an iterator.
int | grib_iterator_reset (grib_iterator *i)
| Test procedure for values in an iterator.
int | grib_iterator_delete (grib_iterator *i)
| Frees an iterator from memory.
grib_nearest * | grib_nearest_new (grib_handle *h, int *error)
| Create a new nearest from a handle, using current geometry .
int | grib_nearest_find (grib_nearest *nearest, grib_handle *h, double inlat, double inlon, unsigned long flags, double *outlats, double *outlons, double *values, double *distances, int *indexes, size_t *len)
| Find the 4 nearest points of a latitude longitude point.
int | grib_nearest_delete (grib_nearest *nearest)
| Frees an nearest from memory.
int | grib_nearest_find_multiple (grib_handle *h, int is_lsm, double *inlats, double *inlons, long npoints, double *outlats, double *outlons, double *values, double *distances, int *indexes)
| Find the nearest point of a set of points whose latitudes and longitudes are given in the inlats, inlons arrays respectively.
int | grib_get_offset (grib_handle *h, const char *key, size_t *offset)
| Get the number offset of a key, in a message if several keys of the same name are present, the offset of the last one is returned.
int | grib_get_size (grib_handle *h, const char *key, size_t *size)
| Get the number of coded value from a key, if several keys of the same name are present, the total sum is returned.
int | grib_get_long (grib_handle *h, const char *key, long *value)
| Get a long value from a key, if several keys of the same name are present, the last one is returned.
int | grib_get_double (grib_handle *h, const char *key, double *value)
| Get a double value from a key, if several keys of the same name are present, the last one is returned.
int | grib_get_double_element (grib_handle *h, const char *key, int i, double *value)
| Get as double the i-th element of the "key" array.
int | grib_get_double_elements (grib_handle *h, const char *key, int *i, long size, double *value)
| Get as double array the elements of the "key" array whose indexes are listed in the input array i.
int | grib_get_string (grib_handle *h, const char *key, char *mesg, size_t *length)
| Get a string value from a key, if several keys of the same name are present, the last one is returned.
int | grib_get_bytes (grib_handle *h, const char *key, unsigned char *bytes, size_t *length)
| Get raw bytes values from a key.
int | grib_get_double_array (grib_handle *h, const char *key, double *vals, size_t *length)
| Get double array values from a key.
int | grib_get_long_array (grib_handle *h, const char *key, long *vals, size_t *length)
| Get long array values from a key.
int | grib_copy_namespace (grib_handle *dest, const char *name, grib_handle *src)
| Copy the keys belonging to a given namespace from a source handle to a destination handle.
int | grib_set_long (grib_handle *h, const char *key, long val)
| Set a long value from a key.
int | grib_set_double (grib_handle *h, const char *key, double val)
| Set a double value from a key.
int | grib_set_string (grib_handle *h, const char *key, const char *mesg, size_t *length)
| Set a string value from a key.
int | grib_set_bytes (grib_handle *h, const char *key, const unsigned char *bytes, size_t *length)
| Set a bytes array from a key.
int | grib_set_double_array (grib_handle *h, const char *key, const double *vals, size_t length)
| Set a double array from a key.
int | grib_set_long_array (grib_handle *h, const char *key, const long *vals, size_t length)
| Set a long array from a key.
void | grib_dump_content (grib_handle *h, FILE *out, const char *mode, unsigned long option_flags, void *arg)
| Print all keys, with the context print procedure and dump mode to a resource.
void | grib_get_all_names (grib_handle *h, char *names)
| Gather all names available in a handle to a string, using a space as separator.
void | grib_dump_action_tree (grib_context *c, FILE *f)
| Print all keys from the parsed definition files available in a context.
grib_context * | grib_get_context (grib_handle *h)
| Retreive the context from a handle.
grib_context * | grib_context_get_default (void)
| Get the static default context.
grib_context * | grib_context_new (grib_context *c)
| Create and allocate a new context from a parent context.
void | grib_context_delete (grib_context *c)
| Frees the cached definition files of the context.
void | grib_gts_header_on (grib_context *c)
| Set the gts header mode on.
void | grib_gts_header_off (grib_context *c)
| Set the gts header mode off.
void | grib_gribex_mode_on (grib_context *c)
| Set the gribex mode on.
void | grib_gribex_mode_off (grib_context *c)
| Set the gribex mode off.
void | grib_context_set_user_data (grib_context *c, void *udata)
| Sets user data in a context.
void * | grib_context_get_user_data (grib_context *c)
| get userData from a context
void | grib_context_set_memory_proc (grib_context *c, grib_malloc_proc griballoc, grib_free_proc gribfree, grib_realloc_proc gribrealloc)
| Sets memory procedures of the context.
void | grib_context_set_persistent_memory_proc (grib_context *c, grib_malloc_proc griballoc, grib_free_proc gribfree)
| Sets memory procedures of the context for persistent data.
void | grib_context_set_buffer_memory_proc (grib_context *c, grib_malloc_proc griballoc, grib_free_proc gribfree, grib_realloc_proc gribrealloc)
| Sets memory procedures of the context for large buffers.
void | grib_context_set_path (grib_context *c, const char *path)
| Sets the context search path for definition files.
void | grib_context_set_dump_mode (grib_context *c, int mode)
| Sets context dump mode.
void | grib_context_set_print_proc (grib_context *c, grib_print_proc printp)
| Sets the context printing procedure used for user interaction.
void | grib_context_set_logging_proc (grib_context *c, grib_log_proc logp)
| Sets the context logging procedure used for system (warning, errors, infos .
void | grib_multi_support_on (grib_context *c)
| Turn on support for multiple fields in single grib messages.
void | grib_multi_support_off (grib_context *c)
| Turn off support for multiple fields in single grib messages.
long | grib_get_api_version (void)
| Get the api version.
void | grib_print_api_version (FILE *out)
| Prints the api version.
grib_keys_iterator * | grib_keys_iterator_new (grib_handle *h, unsigned long filter_flags, char *name_space)
int | grib_keys_iterator_next (grib_keys_iterator *kiter)
const char * | grib_keys_iterator_get_name (grib_keys_iterator *kiter)
int | grib_keys_iterator_delete (grib_keys_iterator *kiter)
int | grib_keys_iterator_rewind (grib_keys_iterator *kiter)
const char * | grib_get_error_message (int code)
| Convert an error code into a string.

## Detailed Description

Copyright 2005-2015 ECMWF.

This software is licensed under the terms of the Apache Licence Version 2.0 which can be obtained at http://www.apache.org/licenses/LICENSE-2.0.
In applying this licence, ECMWF does not waive the privileges and immunities granted to it by virtue of its status as an intergovernmental organisation nor does it submit to any jurisdiction.

grib_api C header file

This is the only file that must be included to use the grib_api library from C.

## Define Documentation

#define GRIB_7777_NOT_FOUND -5

Missing 7777 at end of message.

#define GRIB_ARRAY_TOO_SMALL -6

Passed array is too small.

#define GRIB_BUFFER_TOO_SMALL -3

Passed buffer is too small.

#define GRIB_CODE_NOT_FOUND_IN_TABLE -8

Code not found in code table.

#define GRIB_CONCEPT_NO_MATCH -37

Concept no match.

#define GRIB_CONSTANT_FIELD -48

Constant field.

#define GRIB_DECODING_ERROR -14

Decoding invalid.

#define GRIB_ENCODING_ERROR -15

Encoding invalid.

#define GRIB_END -40

End of resource.

#define GRIB_END_OF_FILE -1

End of ressource reached.

Examples:
  get.f90, get_data.f90, keys_iterator.f90, multi.f90, and samples.f90.

#define GRIB_END_OF_INDEX -43

End of index reached.

Examples:
  index.f90.

#define GRIB_FILE_NOT_FOUND -7

File not found.

#define GRIB_GEOCALCULUS_PROBLEM -17

Problem with calculation of geographic attributes.

#define GRIB_INTERNAL_ARRAY_TOO_SMALL -46

An internal array is too small.

#define GRIB_INTERNAL_ERROR -2

Internal error.

#define GRIB_INVALID_ARGUMENT -20

Invalid argument.

#define GRIB_INVALID_FILE -28

Invalid file id.

#define GRIB_INVALID_GRIB -29

Invalid grib id.

#define GRIB_INVALID_INDEX -30

Invalid index id.

#define GRIB_INVALID_ITERATOR -31

Invalid iterator id.

#define GRIB_INVALID_KEYS_ITERATOR -32

Invalid keys iterator id.

#define GRIB_INVALID_MESSAGE -13

Message invalid.

#define GRIB_INVALID_NEAREST -33

Invalid nearest id.

#define GRIB_INVALID_ORDERBY -34

Invalid order by.

#define GRIB_INVALID_SECTION_NUMBER -22

Invalid section number.

#define GRIB_INVALID_TYPE -25

Invalid key type.

#define GRIB_IO_PROBLEM -12

Input output problem.

#define GRIB_MESSAGE_TOO_LARGE -47

Message is too large for the current architecture.

#define GRIB_MISSING_KEY -35

Missing a key from the fieldset.

#define GRIB_NO_DEFINITIONS -38

Definitions files not found.

#define GRIB_NO_MORE_IN_SET -16

Code cannot unpack because of string too small.

#define GRIB_NO_VALUES -41

Unable to code a field without values.

#define GRIB_NOT_FOUND -11

Key/value not found.

#define GRIB_NOT_IMPLEMENTED -4

Function not yet implemented.

#define GRIB_NULL_HANDLE -21

Null handle.

#define GRIB_NULL_INDEX -44

Null index.

#define GRIB_OUT_OF_AREA -36

The point is out of the grid area.

#define GRIB_OUT_OF_MEMORY -18

Out of memory.

#define GRIB_PREMATURE_END_OF_FILE -45

End of ressource reached when reading message.

#define GRIB_READ_ONLY -19

Value is read only.

#define GRIB_STRING_TOO_SMALL_FOR_CODE_NAME -9

Code cannot unpack because of string too small.

#define GRIB_SUCCESS 0

No error.

Examples:
  iterator.c.

#define GRIB_SWITCH_NO_MATCH -49

Switch unable to find a matching case.

#define GRIB_VALUE_CANNOT_BE_MISSING -23

Value cannot be missing.

#define GRIB_WRONG_ARRAY_SIZE -10

Array size mismatch.

#define GRIB_WRONG_GRID -42

Grid description is wrong or inconsistent.

#define GRIB_WRONG_LENGTH -24

Wrong message length.

#define GRIB_WRONG_STEP -26

Unable to set step.

#define GRIB_WRONG_STEP_UNIT -27

Wrong units for step (step must be integer).

#define GRIB_WRONG_TYPE -39

Wrong type while packing.

## Typedef Documentation

typedef struct grib_context grib_context

Grib context, structure containing the memory methods, the parsers and the formats.

typedef struct grib_iterator grib_iterator

Grib iterator, structure supporting a geographic iteration of values on a grib message.

Examples:
  iterator.c.

typedef struct grib_nearest grib_nearest

Grib nearest, structure used to find the nearest points of a latitude longitude point.

Examples:
  nearest.c.

## Function Documentation

void grib_dump_action_tree | ( | grib_context * | c,
|  | FILE * | f |
| ) |  |  |

Print all keys from the parsed definition files available in a context.

Parameters:

  | f | : the File used to print the keys on
  | c | : the context that containd the cached definition files to be printed

void grib_dump_content | ( | grib_handle * | h,
|  | FILE * | out,
|  | const char * | mode,
|  | unsigned long | option_flags,
|  | void * | arg |
| ) |  |  |

Print all keys, with the context print procedure and dump mode to a resource.

Parameters:

  | h | : the handle to be printed
  | out | : output file handle
  | mode | : available dump modes are: debug wmo c_code
  | option_flags | : all the GRIB_DUMP_FLAG_x flags can be used
  | arg | : used to provide a format to output data (experimental)

void grib_get_all_names | ( | grib_handle * | h,
|  | char * | names |
| ) |  |  |

Gather all names available in a handle to a string, using a space as separator.

Parameters:

  | h | : the handle used to gather the keys
  | names | : the sting to be filled with the names

long grib_get_api_version | ( | void |  | ) |

Get the api version.

Returns:
  api version

const char* grib_get_error_message | ( | int | code | ) |

Convert an error code into a string.

Parameters:

  | code | : the error code

Returns:
  the error message

void grib_print_api_version | ( | FILE * | out | ) |

Prints the api version.