Skip to content

Latest commit

 

History

History
471 lines (300 loc) · 14.2 KB

c-api.rst

File metadata and controls

471 lines (300 loc) · 14.2 KB
Raw

C API

The GSD C API consists of a single header and source file. Developers can drop the implementation into any package that needs it.

Functions

Create an empty gsd file with the given name. Overwrite any existing file at that location. The generated gsd file is not opened. Call :cgsd_open() to open it for writing.

param fname

File name.

param application

Generating application name (truncated to 63 chars).

param schema

Schema name for data to be written in this GSD file (truncated to 63 chars).

param schema_version

Version of the scheme data to be written (make with :cgsd_make_version()).

return
  • GSD_SUCCESS (0) on success. Negative value on failure:
  • GSD_ERROR_IO: IO error (check errno).

Create an empty gsd file with the given name. Overwrite any existing file at that location. Open the generated gsd file in handle.

param handle

Handle to open.

param fname

File name.

param application

Generating application name (truncated to 63 chars).

param schema

Schema name for data to be written in this GSD file (truncated to 63 chars).

param schema_version

Version of the scheme data to be written (make with :cgsd_make_version()).

param flags

Either GSD_OPEN_READWRITE, or GSD_OPEN_APPEND.

param exclusive_create

Set to non-zero to force exclusive creation of the file.

return
  • GSD_SUCCESS (0) on success. Negative value on failure:
  • GSD_ERROR_IO: IO error (check errno).
  • GSD_ERROR_NOT_A_GSD_FILE: Not a GSD file.
  • GSD_ERROR_INVALID_GSD_FILE_VERSION: Invalid GSD file version.
  • GSD_ERROR_FILE_CORRUPT: Corrupt file.
  • GSD_ERROR_MEMORY_ALLOCATION_FAILED: Unable to allocate memory.

Open a GSD file and populates the handle for use by later API calls.

param handle

Handle to open.

param fname

File name to open.

param flags

Either GSD_OPEN_READWRITE, GSD_OPEN_READONLY, or GSD_OPEN_APPEND.

return
  • GSD_SUCCESS (0) on success. Negative value on failure:
  • GSD_ERROR_IO: IO error (check errno).
  • GSD_ERROR_NOT_A_GSD_FILE: Not a GSD file.
  • GSD_ERROR_INVALID_GSD_FILE_VERSION: Invalid GSD file version.
  • GSD_ERROR_FILE_CORRUPT: Corrupt file.
  • GSD_ERROR_MEMORY_ALLOCATION_FAILED: Unable to allocate memory.

Write a data chunk to the current frame. The chunk name must be unique within each frame. The given data chunk is written to the end of the file and its location is updated in the in-memory index. The data pointer must be allocated and contain at least contains at least N * M * gsd_sizeof_type(type) bytes.

param handle

Handle to an open GSD file.

param name

Name of the data chunk.

param type

type ID that identifies the type of data in data.

param N

Number of rows in the data.

param M

Number of columns in the data.

param flags

Unused, set to 0.

param data

Data buffer.

Note

If the GSD file is version 1.0, the chunk name is truncated to 63 bytes. GSD version 2.0 files support arbitrarily long names.

return
  • GSD_SUCCESS (0) on success. Negative value on failure:
  • GSD_ERROR_IO: IO error (check errno).
  • GSD_ERROR_INVALID_ARGUMENT: handle is NULL, N == 0, M == 0, type is invalid, or flags != 0.
  • GSD_ERROR_FILE_MUST_BE_WRITABLE: The file was opened read*only.
  • GSD_ERROR_NAMELIST_FULL: The file cannot store any additional unique chunk names.
  • GSD_ERROR_MEMORY_ALLOCATION_FAILED: failed to allocate memory.

Find a chunk in the GSD file. The found entry contains size and type metadata and can be passed to :cgsd_read_chunk() to read the data.

param handle

Handle to an open GSD file.

param frame

Frame to look for chunk.

param name

Name of the chunk to find.

return

A pointer to the found chunk, or NULL if not found.

Read a chunk from the GSD file. The index entry must first be found by :cgsd_find_chunk(). data must point to an allocated buffer with at least N * M * gsd_sizeof_type(type) bytes.

param handle

Handle to an open GSD file.

param data

Data buffer to read into.

param chunk

Chunk to read.

return

0 on success

  • GSD_SUCCESS (0) on success. Negative value on failure:
  • GSD_ERROR_IO: IO error (check errno).
  • GSD_ERROR_INVALID_ARGUMENT: handle is NULL, data is NULL, or chunk is NULL.
  • GSD_ERROR_FILE_MUST_BE_READABLE: The file was opened in append mode.
  • GSD_ERROR_FILE_CORRUPT: The GSD file is corrupt.

Specify a version number.

param major

major version.

param minor

minor version.

return

a packed version number aaaa.bbbb suitable for storing in a gsd file version entry.

Search for chunk names in a gsd file.

param handle

Handle to an open GSD file.

param match

String to match.

param prev

Search starting point.

To find the first matching chunk name, pass NULL for prev. Pass in the previous found string to find the next after that, and so on. Chunk names match if they begin with the string in match. Chunk names returned by this function may be present in at least one frame.

return

Pointer to a string, NULL if no more matching chunks are found found, or NULL if prev is invalid.

Constants

Data types

Open flags

Error values

Data structures