NAME¶
gd_get_constant — retrieve a scalar constant from a dirfile database
SYNOPSIS¶
#include <getdata.h>
int gd_get_constant(DIRFILE *dirfile, const
char *field_code, gd_type_t return_type,
void *data_out);
DESCRIPTION¶
The
gd_get_constant() function queries a
dirfile(5) database specified by
dirfile for the
CONST scalar
field_code, which may
contain a representation suffix. The constant is converted to the data type
specified by
return_type, and stored in the user-supplied buffer
data_out.
The
dirfile argument must point to a valid DIRFILE object previously
created by a call to
gd_open(3). The argument
data_out must
point to a valid memory location of sufficient size to hold a value of the
return type specified.
The
return_type argument should be one of the following symbols, which
indicates the desired return type of the data:
- GD_UINT8
- unsigned 8-bit integer
- GD_INT8
- signed (two's complement) 8-bit integer
- GD_UINT16
- unsigned 16-bit integer
- GD_INT16
- signed (two's complement) 16-bit integer
- GD_UINT32
- unsigned 32-bit integer
- GD_INT32
- signed (two's complement) 32-bit integer
- GD_UINT64
- unsigned 64-bit integer
- GD_INT64
- signed (two's complement) 64-bit integer
- GD_FLOAT32
- IEEE-754 standard 32-bit single precision floating point number
- GD_FLOAT64
- IEEE-754 standard 64-bit double precision floating point number
- GD_COMPLEX64
- C99-conformant 64-bit single precision complex number
- GD_COMPLEX128
- C99-conformant 128-bit double precision complex number
- GD_NULL
- the null type: the database is queried as usual, but no data is returned.
In this case, data_out is ignored and may be NULL.
The return type of the constant need not be the same as the type of the data
stored in the database. Type conversion will be performed as necessary to
return the requested type. If the
field_code does not indicate a
representation, but conversion from a complex value to a purely real one is
required, only the real portion of the requested vector will be returned.
RETURN VALUE¶
On success,
gd_get_constant() returns zero. On error, it returns -1 and
sets the dirfile error to a non-zero value. Possible error values are:
- GD_E_BAD_CODE
- The field specified by field_code was not found in the
database.
- GD_E_BAD_DIRFILE
- An invalid dirfile was supplied.
- GD_E_BAD_FIELD_TYPE
- The supplied field_code referred to a field of a type other than
CONST. The caller should use gd_getdata(3), or
gd_get_string(3) instead.
- GD_E_BAD_REPR
- The representation suffix specified in fieldcode, or in one
of the field codes it uses for input, was invalid.
- GD_E_BAD_TYPE
- An invalid return_type was specified.
- GD_E_INTERNAL_ERROR
- An internal error occurred in the library while trying to perform the
task. This indicates a bug in the library. Please report the incident to
the maintainer.
The dirfile error may be retrieved by calling
gd_error(3). A descriptive
error string for the last error encountered may be obtained from a call to
gd_error_string(3).
SEE ALSO¶
dirfile(5),
gd_open(3),
gd_error(3),
gd_error_string(3),
gd_get_carray(3),
gd_constants(3),
gd_put_constant(3)