NAME

       odbx_escape - Prepare strings for inclusion in statements

SYNOPSIS

       #include <opendbx/api.h>

       int odbx_escape (odbx_t* handle, const char* from, unsigned long fromlen, char* to, unsigned long*
                       tolen);

DESCRIPTION

       odbx_escape()  neutralizes  potentially dangerous characters of the string so it can be used as part of a
       statement. For security reasons every user input has to be passed to odbx_escape() to avoid SQL injection
       attacks which can have fatal consequences! It's also a good idea to escape strings returned from database
       fields again if you want to use them in a query because they don't stay escaped once they are returned as
       part of a record.

       Most backends require the buffer to be more than twice as long as the input string. To  be  precise,  the
       output  buffer  must  be  2 * size of input + 1 bytes long. After successfully escaping the characters in
       from, they are written into the memory provided via to and the value/result parameter tolen is updated to
       the new length of to in the end.

       The first parameter handle is the connection object created and returned by odbx_init() which becomes in‐
       valid as soon as it was supplied to odbx_finish().

       from has to point to a character string containing the string which should be used as part  of  a  state‐
       ment. It doesn't have to be zero-terminated because the length of it is also given via fromlen. The back‐
       ends may support variable width character sets like UTF-8 but this function doesn't support the wide char
       type (wchar_t) where each character has a fixed size of two or four bytes.

       The  value  of the parameter fromlen must be the length in bytes of the string which from is pointing to.
       This is also true for variable width character sets like UTF-8 but the wide char type  (wchar_t)  is  not
       supported. The terminating \0 character shouldn't be part of fromlen.

       The  calling  function provides a buffer for storing the escaped string via to. In general, the length of
       the buffer should be more than twice as long as the string passed via from to be able to  store  the  es‐
       caped string even if every character has to be escaped.

       tolen  is  a  value-result parameter which points to an integer variable in the calling function. It must
       contain the original length of the buffer given via to and if  escaping  the  string  in  from  suceeded,
       odbx_escape() will store the new length of the escaped string in this variable.

RETURN VALUE

       odbx_escape()  returns ODBX_ERR_SUCCESS, or an error code whose value is less than zero if one of the op‐
       erations couldn't be completed successfully. Possible error codes are listed in  the  error  section  and
       they can be feed to odbx_error() and odbx_error_type() to get further details.

ERRORS

       -ODBX_ERR_BACKEND
              The native database library returned an error because it wasn't able to escape the given string to
              be suitable for a statement

       -ODBX_ERR_PARAM
              One  of  the  supplied parameters is invalid or is NULL and this isn't allowed in the used backend
              module or in the native database client library

       -ODBX_ERR_SIZE
              The length of the escaped string exceeds or is likely to exeed the available buffer (before  1.1.4
              the name of the label was ODBX_ERR_TOOLONG but the value is still the same)

SEE ALSO

       odbx_error(), odbx_error_type(), odbx_query()

                                                  3 April 2024                                    odbx_escape(3)