1odbx_escape(3)                      OpenDBX                     odbx_escape(3)
2
3
4

NAME

6       odbx_escape - Prepare strings for inclusion in statements
7

SYNOPSIS

9       #include <opendbx/api.h>
10
11
12       int odbx_escape (odbx_t* handle, const char* from, unsigned long
13                       fromlen, char* to, unsigned long* tolen);
14

DESCRIPTION

16       odbx_escape()  neutralizes  potentially  dangerous  characters  of  the
17       string  so  it can be used as part of a statement. For security reasons
18       every user input has to be passed to odbx_escape() to avoid SQL  injec‐
19       tion  attacks  which can have fatal consequences! It's also a good idea
20       to escape strings returned from database fields again if  you  want  to
21       use  them  in a query because they don't stay escaped once they are re‐
22       turned as part of a record.
23
24       Most backends require the buffer to be more than twice as long  as  the
25       input  string. To be precise, the output buffer must be 2 * size of in‐
26       put + 1 bytes long. After successfully escaping the characters in from,
27       they  are  written into the memory provided via to and the value/result
28       parameter tolen is updated to the new length of to in the end.
29
30       The first parameter handle is the connection  object  created  and  re‐
31       turned  by odbx_init() which becomes invalid as soon as it was supplied
32       to odbx_finish().
33
34       from has to point to a character string  containing  the  string  which
35       should  be used as part of a statement. It doesn't have to be zero-ter‐
36       minated because the length of it is also given via fromlen.  The  back‐
37       ends  may  support  variable  width  character sets like UTF-8 but this
38       function doesn't support the wide char type (wchar_t) where each  char‐
39       acter has a fixed size of two or four bytes.
40
41       The  value  of the parameter fromlen must be the length in bytes of the
42       string which from is pointing to. This is also true for variable  width
43       character  sets like UTF-8 but the wide char type (wchar_t) is not sup‐
44       ported. The terminating \0 character shouldn't be part of fromlen.
45
46       The calling function provides a buffer for storing the  escaped  string
47       via  to. In general, the length of the buffer should be more than twice
48       as long as the string passed via from to be able to store  the  escaped
49       string even if every character has to be escaped.
50
51       tolen  is  a value-result parameter which points to an integer variable
52       in the calling function. It must contain the  original  length  of  the
53       buffer  given  via  to  and  if  escaping  the string in from suceeded,
54       odbx_escape() will store the new length of the escaped string  in  this
55       variable.
56

RETURN VALUE

58       odbx_escape() returns ODBX_ERR_SUCCESS, or an error code whose value is
59       less than zero if one of the operations couldn't be completed  success‐
60       fully.  Possible  error  codes are listed in the error section and they
61       can be feed to odbx_error() and odbx_error_type() to  get  further  de‐
62       tails.
63

ERRORS

65       -ODBX_ERR_BACKEND
66              The  native database library returned an error because it wasn't
67              able to escape the given string to be suitable for a statement
68
69       -ODBX_ERR_PARAM
70              One of the supplied parameters is invalid or is  NULL  and  this
71              isn't  allowed in the used backend module or in the native data‐
72              base client library
73
74       -ODBX_ERR_SIZE
75              The length of the escaped string exceeds or is likely  to  exeed
76              the  available  buffer  (before  1.1.4 the name of the label was
77              ODBX_ERR_TOOLONG but the value is still the same)
78

SEE ALSO

80       odbx_error(), odbx_error_type(), odbx_query()
81
82
83
84                                22 August 2021                  odbx_escape(3)
Impressum