gd_get_sarray(3)

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

NAME

14       gd_get_sarray,  gd_get_sarray_slice  —  retrieve  STRING or SARRAY data
15       from a dirfile database
16
17

SYNOPSIS

19       #include <getdata.h>
20
21       int gd_get_sarray_slice(DIRFILE *dirfile, const char *field_code,
22              unsigned int start, size_t len, const char **data_out);
23
24       int gd_get_sarray(DIRFILE *dirfile, const char *field_code, const char
25              **data_out);
26
27

DESCRIPTION

29       The gd_get_sarray_slice() function queries a dirfile(5) database speci‐
30       fied  by  dirfile for the STRING or SARRAY scalar field_code.  Pointers
31       to read-only string elements of the specified field are stored  in  the
32       user-supplied  data_out  buffer, which must be large enough to hold len
33       pointers.  The first element of the field stored is given by start, and
34       the number of elements stored is given by len.
35
36       The  gd_get_sarray()  function behaves similarly, except it returns the
37       entire field, as if gd_get_sarray_slice() were called with start  equal
38       to zero and len equal to the value returned by gd_array_len(3).
39
40       The  dirfile  argument  must point to a valid DIRFILE object previously
41       created by a call to gd_open(3).  The number of  elements  returned  by
42       gd_get_sarray()  may  be  obtained  by calling gd_array_len(3).  Unlike
43       gd_getdata(3), calling gd_get_sarray_slice() never results in  a  short
44       read;  attempting  to  read past the end of the field will result in an
45       error, and no data will be returned.
46
47       If field_code refers to a STRING field, it is treated as if it  were  a
48       SARRAY  field  with  only one element.  See the gd_get_string(3) manual
49       page for an example of  how  to  replace  gd_get_string(3)  calls  with
50       gd_get_sarray().
51
52

RETURN VALUE

54       On  success,  gd_get_sarray()  and  gd_get_sarray_slice(), return zero.
55       Storage for the strings returned by this function are managed by GetDa‐
56       ta  and should not be deallocated by the caller.  On error, these func‐
57       tions return a negative-valued error code.  Possible error codes are:
58
59       GD_E_ALLOC
60               The library was unable to allocate memory.
61
62       GD_E_BAD_CODE
63               The field specified by field_code was not found  in  the  data‐
64               base.
65
66       GD_E_BAD_DIRFILE
67               An invalid dirfile was supplied.
68
69       GD_E_BAD_FIELD_TYPE
70               The supplied field_code was not a STRING nor SARRAY.
71
72       GD_E_BOUNDS
73               A request for data beyond the end of the field was made.
74
75       GD_E_INTERNAL_ERROR
76               An  internal error occurred in the library while trying to per‐
77               form the task.  This indicates a bug in  the  library.   Please
78               report the incident to the maintainer.
79
80       The  error  code  is  also  stored in the DIRFILE object and may be re‐
81       trieved after this function returns by calling gd_error(3).  A descrip‐
82       tive   error   string   for  the  error  may  be  obtained  by  calling
83       gd_error_string(3).
84
85

HISTORY

87       The gd_get_sarray() and  gd_get_sarray_slice()  functions  appeared  in
88       GetData-0.10.0.
89
90

NAME

SYNOPSIS

DESCRIPTION

RETURN VALUE

HISTORY

SEE ALSO