1odbx_escape(3) OpenDBX odbx_escape(3)
2
6 odbx_escape - Prepare strings for inclusion in statements
7
9 #include <opendbx/api.h>
10 int odbx_escape (odbx_t* handle, const char* from, unsigned long
13 fromlen, char* to, unsigned long* tolen);
14
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 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 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 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 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 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 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
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
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 -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 -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
80 odbx_error(), odbx_error_type(), odbx_query()
81 22 August 2021 odbx_escape(3)