1gd_carrays(3) GETDATA gd_carrays(3)
10
14 gd_carrays, gd_mcarrays — retrieve a list of CARRAY values from a
15 Dirfile
16
19 #include <getdata.h>
20 const gd_carray_t *gd_carrays(DIRFILE *dirfile, gd_type_t return_type);
22 const gd_carray_t *gd_mcarrays(DIRFILE *dirfile, const char *parent,
24 gd_type_t return_type);
25
28 The gd_carrays() function queries a dirfile(5) database specified by
29 dirfile and generates a read-only list of values of the all top-level
30 CARRAY fields defined in the database, after type conversion to the da‐
31 ta type specified by return_type. For a list of valid symbols to use
32 for return_type, see the gd_get_carray(3) manual page.
33 The gd_mcarrays() function behaves similarly, but creates a list of
35 values of CARRAY subfields under the parent field parent.
36 The dirfile argument must point to a valid DIRFILE object previously
38 created by a call to gd_open(3).
39 A corresponding list of names for these fields may be obtained by call‐
41 ing gd_field_list_by_type(3) or gd_mfield_list_by_type(3).
42
45 Upon successful completion, gd_carrays() and gd_mcarrays(3) return a
46 pointer to an array of gd_carray_t objects containing the values of all
47 the CARRAYs defined in the dirfile database. The gd_carray_t structure
48 is defined as:
49 typedef struct {
51 size_t n; /* array_len */
52 void *d; /* CARRAY data */
53 } gd_carray_t;
54 where n specifies the length of the CARRAY data, and d is an array of
56 the data values themselves. If return_type was GD_NULL, d will be NULL.
57 Otherwise, the caller should cast the void pointer to a type appropri‐
58 ate for the return_type specified. The list is terminated by an end-
59 of-list marker consisting of a gd_carray_t item with n set to zero.
60 If no CARRAYs are defined in the database, a list containing only the
62 end-of-list marker is returned.
63 The array returned will be de-allocated by a call to gd_close(3) and
65 should not be de-allocated by the caller. The list returned should not
66 be assumed to be in any particular order, except that it is guaranteed
67 to be in the same order as the list of CARRAY fields returned by
68 gd_field_list_by_type(3) or gd_mfield_list_by_type(3). The number of
69 values in the array can be obtained from a call to
70 gd_nfields_by_type(3) or gd_nmfields_by_type(3).
71 The caller may not modify any values in the array, nor the array it‐
73 self. Doing so may cause database corruption. The pointer returned is
74 guaranteed to be valid only until the function is called again, or un‐
75 til the dirfile's metadata is modified (by adding, modifying or delet‐
76 ing an entry), or until the array is de-allocated by a call to
77 gd_close(3) or gd_discard(3).
78 On error, gd_carrays() returns NULL and stores 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 GD_E_ALLOC
84 The library was unable to allocate memory.
85 GD_E_BAD_DIRFILE
87 The supplied dirfile was invalid.
88 GD_E_BAD_TYPE
90 The return_type specified was invalid.
91 GD_E_INTERNAL_ERROR
93 An internal error occurred in the library while trying to per‐
94 form the task. This indicates a bug in the library. Please
95 report the incident to the GetData developers.
96 A descriptive error string for the error may be obtained by calling
98 gd_error_string(3).
99
102 The gd_carrays() and gd_mcarrays() functions appeared in GetData-0.7.0.
103
106 dirfile(5), gd_error(3), gd_error_string(3), gd_field_list_by_type(3),
107 gd_get_carray(3), gd_mfield_list_by_type(3), gd_nfields_by_type(3)
108 gd_nmfields_by_type(3) gd_open(3)
109Version 0.10.0 25 December 2016 gd_carrays(3)