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

NAME

14       gd_carrays,  gd_mcarrays  —  retrieve  a  list  of CARRAY values from a
15       Dirfile
16
17

SYNOPSIS

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

DESCRIPTION

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
34       The  gd_mcarrays()  function  behaves  similarly, but creates a list of
35       values of CARRAY subfields under the parent field parent.
36
37       The dirfile argument must point to a valid  DIRFILE  object  previously
38       created by a call to gd_open(3).
39
40       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
43

RETURN VALUE

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
50              typedef struct {
51                size_t       n;              /* array_len */
52                void        *d;              /* CARRAY data */
53              } gd_carray_t;
54
55       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
61       If  no  CARRAYs are defined in the database, a list containing only the
62       end-of-list marker is returned.
63
64       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
72       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
79       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
83       GD_E_ALLOC
84               The library was unable to allocate memory.
85
86       GD_E_BAD_DIRFILE
87               The supplied dirfile was invalid.
88
89       GD_E_BAD_TYPE
90               The return_type specified was invalid.
91
92       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
97       A  descriptive  error  string  for the error may be obtained by calling
98       gd_error_string(3).
99
100

HISTORY

102       The gd_carrays() and gd_mcarrays() functions appeared in GetData-0.7.0.
103
104

SEE ALSO

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)
109
110
111
112Version 0.10.0                 25 December 2016                  gd_carrays(3)
Impressum