gd_get_string(3)

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

NAME

14       gd_get_string — retrieve STRING or SARRAY data from a Dirfile database
15
16

SYNOPSIS

18       #include <getdata.h>
19
20       size_t gd_get_string(DIRFILE *dirfile, const char *field_code, size_t
21              len, char *data_out);
22
23

DESCRIPTION

25       The gd_get_string() function queries a dirfile(5) database specified by
26       dirfile  for  the  string scalar field_code, which should not contain a
27       representation suffix.  The first len characters of the  string  scalar
28       are  stored in the user-supplied buffer data_out.  If field_code refers
29       to a SARRAY field, the first element is returned.
30
31       The dirfile argument must point to a valid  DIRFILE  object  previously
32       created by a call to gd_open(3).
33
34       If  len equals zero, or if data_out equals NULL, no data will be copied
35       to data_out, but the length of the string scalar will still be returned
36       by  gd_get_string().   Otherwise, the argument data_out must point to a
37       valid memory location of sufficient size to hold at least  len  charac‐
38       ters.  If the length of the string scalar is greater than len, data_out
39       will not be NUL-terminated.
40
41       The gd_get_sarray(3) function provides another way of retrieving STRING
42       data,  but  without having to know the length of the returned string in
43       advance.  The code:
44
45              size_t len = gd_get_string(dirfile, field_code, 0, NULL);
46              char *string = malloc(len);
47              gd_get_string(dirfile, field_code, len, string);
48
49       which ensures the whole string, including the terminating NUL,  is  re‐
50       turned, can be replaced with, simply:
51
52              const char *string;
53              gd_get_sarray(dirfile, field_code, &string);
54
55       with the added benefit of not having manage the memory for the string.
56
57

RETURN VALUE

59       On  success, gd_get_string() returns the actual length of the specified
60       string scalar, including space for the trailing NUL-character.   A  re‐
61       turn  value  greater  than  len indicates that the output string is not
62       NUL-terminated.
63
64       On error, this function returns 0 and stores  a  negative-valued  error
65       code  in the DIRFILE object which may be retrieved by a subsequent call
66       to gd_error(3).  Possible error codes are:
67
68       GD_E_BAD_CODE
69               The field specified by field_code was not found  in  the  data‐
70               base.
71
72       GD_E_BAD_DIRFILE
73               An invalid dirfile was supplied.
74
75       GD_E_BAD_FIELD_TYPE
76               The  supplied field_code referred to a field of type other than
77               STRING or SARRAY.
78
79       GD_E_INTERNAL_ERROR
80               An internal error occurred in the library while trying to  per‐
81               form  the  task.   This indicates a bug in the library.  Please
82               report the incident to the maintainer.
83
84       A descriptive error string for the error may  be  obtained  by  calling
85       gd_error_string(3).
86
87

HISTORY

89       The get_string() function appeared in GetData-0.4.0.
90
91       In GetData-0.7.0, this function was renamed to gd_get_string().
92
93

NAME

SYNOPSIS

DESCRIPTION

RETURN VALUE

HISTORY

SEE ALSO