1get_string(3)                       GETDATA                      get_string(3)
2
3
4

NAME

6       get_string — retrieve a string from a dirfile database
7

SYNOPSIS

9       #include <getdata.h>
10
11       size_t get_string(DIRFILE *dirfile, const char *field_code, size_t len,
12              char *data_out);
13

DESCRIPTION

15       The get_string() function queries a dirfile(5)  database  specified  by
16       dirfile  for  the  string scalar field_code, which should not contain a
17       representation suffix.  The first len characters of the  string  scalar
18       are stored in the user-supplied buffer data_out.
19
20       The  dirfile  argument  must point to a valid DIRFILE object previously
21       created by a call to dirfile_open(3).
22
23       If len equals zero, or if data_out equals NULL, no data will be  copied
24       to data_out, but the length of the string scalar will still be returned
25       by get_string().  Otherwise, the argument  data_out  must  point  to  a
26       valid  memory  location of sufficient size to hold at least len charac‐
27       ters.  If the length of the string scalar is greater than len, data_out
28       will not be NULL-terminated.
29

RETURN VALUE

31       On  success,  get_string()  returns  the actual length of the specified
32       string scalar, including the trailing NULL character.  A  return  value
33       greater than len indicates that the output string is not null terminat‐
34       ed.
35
36       On error, it returns 0 and sets the dirfile error to a non-zero  value.
37       Possible error values are:
38
39       GD_E_BAD_CODE
40               The  field  specified  by field_code was not found in the data‐
41               base.
42
43       GD_E_BAD_DIRFILE
44               An invalid dirfile was supplied.
45
46       GD_E_BAD_FIELD_TYPE
47               The supplied field_code referred to a field of type other  than
48               STRING.   The  caller should use getdata(3), or get_constant(3)
49               instead.
50
51       GD_E_BAD_TYPE
52               An invalid return_type was specified.
53
54       GD_E_INTERNAL_ERROR
55               An internal error occurred in the library while trying to  per‐
56               form  the  task.   This indicates a bug in the library.  Please
57               report the incident to the maintainer.
58
59       The dirfile error may be retrieved by calling get_error(3).  A descrip‐
60       tive error string for the last error encountered may be obtained from a
61       call to get_error_string(3).
62

SEE ALSO

64       dirfile(5),   dirfile_open(3),    get_error(3),    get_error_string(3),
65       put_string(3)
66
67
68
69Version 0.6.0                   19 October 2009                  get_string(3)
Impressum