gd_strings(3)

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

NAME

14       gd_strings — retrieve a list of string values from a Dirfile
15
16

SYNOPSIS

18       #include <getdata.h>
19
20       const char **gd_strings(DIRFILE *dirfile);
21
22       const char **gd_mstrings(DIRFILE *dirfile, const char *parent);
23
24

DESCRIPTION

26       The  gd_strings()  function  queries a dirfile(5) database specified by
27       dirfile and compiles a read-only list of values of the all STRING  type
28       fields defined in the database, excluding /META subfields.
29
30       The  gd_mstrings() function produces the same list, but for STRING meta
31       subfields of the indicated parent field.
32
33       The dirfile argument must point to a valid  DIRFILE  object  previously
34       created by a call to gd_open(3).
35
36

RETURN VALUE

38       Upon  successful completion, gd_strings() returns a pointer to an array
39       of strings containing the values of all the STRING  fields  defined  in
40       the dirfile database.  Similarly, gd_mstrings() returns a pointer to an
41       array of strings containing the values of all the STRING metafields un‐
42       der parent.
43
44       The returned array is terminated by a NULL pointer.  A valid pointer is
45       always returned if this function does not encounter an error.  If there
46       are no string values to return, a pointer to an array consisting of on‐
47       ly the NULL pointer is returned.
48
49       The array returned will be de-allocated by a call  to  gd_close(3)  and
50       should not be de-allocated by the caller.  The list returned should not
51       be assumed to be in any particular order, although it is guaranteed  to
52       be  in  the  same  order  as  the  list  of  STRING  fields returned by
53       gd_field_list_by_type(3).  The array is terminated by a  NULL  pointer.
54       The  number  of  strings  in  the  array can be obtained from a call to
55       gd_nfields_by_type(3).
56
57       The caller may not modify any strings in the array, or  the  array  it‐
58       self.  Doing so may cause database corruption.  The pointer returned is
59       guaranteed to be valid until gd_strings() or  gd_mstrings()  is  called
60       again  with the same arguments, or until the array is de-allocated by a
61       call to gd_close(3) or gd_discard(3).
62
63       On error, these functions return NULL and store a negative-valued error
64       code  in the DIRFILE object which may be retrieved by a subsequent call
65       to gd_error(3).  Possible error codes are:
66
67       GD_E_ALLOC
68               The library was unable to allocate memory.
69
70       GD_E_BAD_CODE
71               (gd_mstrings() only) The supplied parent  field  code  was  not
72               found, or referred to a metafield itself.
73
74       GD_E_BAD_DIRFILE
75               The supplied dirfile was invalid.
76
77       A  descriptive  error  string  for the error may be obtained by calling
78       gd_error_string(3).
79
80

HISTORY

82       The get_strings() function appeared in GetData-0.3.0.
83
84       The get_mstrings() function appeared in GetData-0.4.0.
85
86       In GetData-0.7.0, these functions  were  renamed  to  gd_strings()  and
87       gd_mstrings().
88
89

NAME

SYNOPSIS

DESCRIPTION

RETURN VALUE

HISTORY

SEE ALSO