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

NAME

14       gd_sarrays,  gd_msarrays  —  retrieve  a  list  of SARRAY values from a
15       Dirfile
16
17

SYNOPSIS

19       #include <getdata.h>
20
21       const char ***gd_sarrays(DIRFILE *dirfile);
22
23       const char ***gd_msarrays(DIRFILE *dirfile, const char *parent);
24
25

DESCRIPTION

27       The gd_sarrays() function queries a dirfile(5)  database  specified  by
28       dirfile  and  generates a read-only list of values of the all top-level
29       SARRAY fields defined in the database, after type conversion to the da‐
30       ta  type  specified by return_type.  For a list of valid symbols to use
31       for return_type, see the gd_get_sarray(3) manual page.
32
33       The gd_msarrays() function behaves similarly, but  creates  a  list  of
34       values of SARRAY subfields under the parent field parent.
35
36       The  dirfile  argument  must point to a valid DIRFILE object previously
37       created by a call to gd_open(3).
38
39       The array returned will be de-allocated by a call  to  gd_close(3)  and
40       should not be de-allocated by the caller.  The list returned should not
41       be assumed to be in any particular order, except that it is  guaranteed
42       to  be  in  the  same  order  as  the list of SARRAY fields returned by
43       gd_field_list_by_type(3) or gd_mfield_list_by_type(3).  The  number  of
44       values    in   the   array   can   be   obtained   from   a   call   to
45       gd_nfields_by_type(3) or gd_nmfields_by_type(3).
46
47       The caller may not modify any values in the array, nor  the  array  it‐
48       self.  Doing so may cause database corruption.  The pointer returned is
49       guaranteed to be valid only until the function is called again with the
50       same arguments, or until the dirfile's metadata is modified (by adding,
51       modifying or deleting an entry), or until the array is de-allocated  by
52       a call to gd_close(3) or gd_discard(3).
53
54       A corresponding list of names for these fields may be obtained by call‐
55       ing gd_field_list_by_type(3) or gd_mfield_list_by_type(3).
56
57

RETURN VALUE

59       Upon successful completion, gd_sarrays() and  gd_msarrays(3)  return  a
60       pointer to an array of arrays of strings.  For convenience, both levels
61       of the array are terminated by NULL pointers.
62
63       If no SARRAYs are defined in the database, a pointer to  a  single-ele‐
64       ment array containing only the terminating NULL is returned.
65
66       On  error, gd_sarrays() returns NULL and stores a negative-valued error
67       code in the DIRFILE object which may be retrieved by a subsequent  call
68       to gd_error(3).  Possible error codes are:
69
70       GD_E_ALLOC
71               The library was unable to allocate memory.
72
73       GD_E_BAD_DIRFILE
74               The supplied dirfile was invalid.
75
76       GD_E_INTERNAL_ERROR
77               An  internal error occurred in the library while trying to per‐
78               form the task.  This indicates a bug in  the  library.   Please
79               report the incident to the GetData developers.
80
81       A  descriptive  error  string  for the error may be obtained by calling
82       gd_error_string(3).
83
84

HISTORY

86       The gd_sarrays() function appeared in GetData-0.10.0.
87
88

SEE ALSO

90       gd_entry_list(3),  gd_error(3),  gd_error_string(3),  gd_get_sarray(3),
91       gd_nentries(3), gd_open(3), dirfile(5)
92
93
94
95Version 0.10.0                 25 December 2016                  gd_sarrays(3)
Impressum