1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
|
.\" gd_get_string.3. The gd_get_string man page.
.\"
.\" Copyright (C) 2008, 2009, 2010, 2016 D. V. Wiebe
.\"
.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.\"
.\" This file is part of the GetData project.
.\"
.\" Permission is granted to copy, distribute and/or modify this document
.\" under the terms of the GNU Free Documentation License, Version 1.2 or
.\" any later version published by the Free Software Foundation; with no
.\" Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
.\" Texts. A copy of the license is included in the `COPYING.DOC' file
.\" as part of this distribution.
.\"
.TH gd_get_string 3 "25 December 2016" "Version 0.10.0" "GETDATA"
.SH NAME
gd_get_string \(em retrieve STRING or SARRAY data from a Dirfile database
.SH SYNOPSIS
.SC
.B #include <getdata.h>
.HP
.BI "size_t gd_get_string(DIRFILE *" dirfile ", const char *" field_code ,
.BI "size_t " len ", char *" data_out );
.EC
.SH DESCRIPTION
The
.FN gd_get_string
function queries a dirfile(5) database specified by
.ARG dirfile
for the string scalar
.ARG field_code ,
which should not contain a representation suffix. The first
.ARG len
characters of the string scalar are stored in the user-supplied buffer
.ARG data_out .
If
.ARG field_code
refers to a
.B SARRAY
field, the first element is returned.
The
.ARG dirfile
argument must point to a valid DIRFILE object previously created by a call to
.F3 gd_open .
If
.ARG len
equals zero, or if
.ARG data_out
equals NULL, no data will be copied to
.ARG data_out ,
but the length of the string scalar will still be returned by
.FN gd_get_string .
Otherwise, the argument
.ARG data_out
must point to a valid memory location of sufficient size to hold at least
.ARG len
characters. If the length of the string scalar is greater than
.ARG len ,
.ARG data_out
will not be NUL-terminated.
The
.F3 gd_get_sarray
function provides another way of retrieving
.B STRING
data, but without having to know the length of the returned string in advance.
The code:
.RS
.SC
.BI "size_t " len " = gd_get_string(" dirfile ", " field_code ", 0, NULL);"
.br
.BI "char *" string " = malloc(" len );
.br
.BI gd_get_string( dirfile ", " field_code ", " len ", " string );
.EC
.RE
which ensures the whole string, including the terminating NUL, is returned, can
be replaced with, simply:
.RS
.SC
.BI "const char *" string;
.br
.BI gd_get_sarray( dirfile ", " field_code ", &" string );
.EC
.RE
with the added benefit of not having manage the memory for the string.
.SH RETURN VALUE
On success,
.FN gd_get_string
returns the actual length of the specified string scalar, including space for
the trailing NUL-character. A return value greater than
.ARG len
indicates that the output string is not NUL-terminated.
On error, this function returns 0 and stores a negative-valued error code in the
.B DIRFILE
object which may be retrieved by a subsequent call to
.F3 gd_error .
Possible error codes are:
.DD GD_E_BAD_CODE
The field specified by
.ARG field_code
was not found in the database.
.DD GD_E_BAD_DIRFILE
An invalid
.ARG dirfile
was supplied.
.DD GD_E_BAD_FIELD_TYPE
The supplied
.ARG field_code
referred to a field of type other than
.B STRING
or
.BR SARRAY .
.DD GD_E_INTERNAL_ERROR
An internal error occurred in the library while trying to perform the task.
This indicates a bug in the library. Please report the incident to the
maintainer.
.PP
A descriptive error string for the error may be obtained by calling
.F3 gd_error_string .
.SH HISTORY
The
.FN get_string
function appeared in GetData-0.4.0.
In GetData-0.7.0, this function was renamed to
.FN gd_get_string .
.SH SEE ALSO
.F3 gd_get_sarray ,
.F3 gd_error ,
.F3 gd_error_string ,
.F3 gd_open ,
.F3 gd_put_string ,
dirfile(5)
|
