gd_constants(3)

1
2
3
4
5
6
7
8
9gd_constants(3)                     GETDATA                    gd_constants(3)
10
11
12

NAME

14       gd_constants, gd_mconstants — retrieve a list of constant values from a
15       Dirfile
16
17

SYNOPSIS

19       #include <getdata.h>
20
21       const void *gd_constants(DIRFILE *dirfile, gd_type_t return_type);
22
23       const void *gd_mconstants(DIRFILE *dirfile, const char *parent,
24              gd_type_t return_type);
25
26

DESCRIPTION

28       The  gd_constants() function queries a dirfile(5) database specified by
29       dirfile and compiles a list of values of the all CONST  fields  defined
30       in  the  database,  excluding  meta subfields.  The values returned are
31       converted to the data type specified by return_type.   The  return_type
32       should be one of the following symbols:
33
34              GD_UINT8, GD_INT8, GD_UINT16, GD_INT16, GD_UINT32, GD_INT32,
35              GD_UINT64, GD_INT64, GD_FLOAT32, GD_FLOAT64, GD_COMPLEX64,
36              GD_COMPLEX128.
37
38       See  gd_get_constant(3)  for the meaning of these symbols.  The dirfile
39       argument must point to a valid DIRFILE object previously created  by  a
40       call to gd_open(3).
41
42       The  gd_mconstants() function returns the same list for CONST meta sub‐
43       fields of the parent field specified by parent.
44
45       A corresponding list of names for these fields may be obtained by call‐
46       ing gd_field_list_by_type(3) or gd_mfield_list_by_type(3).
47
48

RETURN VALUE

50       Upon  successful completion, gd_constants() returns a pointer to an ar‐
51       ray containing the values of all the constants defined in  the  dirfile
52       database.   Similarly,  gd_mconstants()  returns  a pointer to an array
53       containing the values of the all the meta  subfield  constants  of  the
54       specified parent field.
55
56       The  list returned should not be assumed to be in any particular order,
57       although it is guaranteed to be in the same order as the list of  CONST
58       fields        returned       by       gd_field_list_by_type(3)       or
59       gd_mfield_list_by_type(3).  The array is unterminated.  The  number  of
60       values    in   the   array   can   be   obtained   from   a   call   to
61       gd_nfields_by_type(3) or gd_nmfields_by_type(3), as appropriate.
62
63       Memory for the returned array is managed by GetData and should  not  be
64       de-allocated  by  the  caller.  The caller may not modify any values in
65       the array.  Doing so may cause database corruption.   The  pointer  re‐
66       turned  is  guaranteed  to  be  valid only until the function is called
67       again, with the exception that, since each  top-level  field  maintains
68       its own arrays, calling gd_mconstants() for a one parent field does not
69       invalidate the pointer returned for a any other parent.
70
71       Modifying the dirfile's metadata invalidates any  pointer  returned  by
72       these functions.  And no pointers remain valid after the dirfile is de-
73       allocated by a call to gd_close(3) or gd_discard(3).  Once a pointer is
74       invalidated, the caller should not dereference it.
75
76       If  no  constants of the appropriate class are defined in the database,
77       NULL is returned.  This is not considered an error.
78
79       On error, these functions return NULL and store a negative-valued error
80       code  in the DIRFILE object which may be retrieved by a subsequent call
81       to gd_error(3).  Possible error codes are:
82
83       GD_E_ALLOC
84               The library was unable to allocate memory.
85
86       GD_E_BAD_CODE
87               The specified parent field code was not found, or referred to a
88               metafield (gd_mconstants() only).
89
90       GD_E_BAD_DIRFILE
91               The supplied dirfile was invalid.
92
93       GD_E_BAD_TYPE
94               The  return_type  specified  was  not one of the symbols listed
95               above.
96
97       GD_E_INTERNAL_ERROR
98               An internal error occurred in the library while trying to  per‐
99               form  the  task.   This indicates a bug in the library.  Please
100               report the incident to the GetData developers.
101
102       A descriptive error string for the error may  be  obtained  by  calling
103       gd_error_string(3).
104
105

HISTORY

107       The  functions  get_constants() and get_mconstants() appeared in GetDa‐
108       ta-0.4.0.
109
110       In GetData-0.7.0, these functions were renamed  to  gd_constants()  and
111       gd_mconstants().
112
113

NAME

SYNOPSIS

DESCRIPTION

RETURN VALUE

HISTORY

SEE ALSO