odbx_init(3)

✨ odbx_init(3) — OpenDBX ✨

okay bestie, welcome to the odbx_init page from the OpenDBX manual, section 3 💅 this is the very first thing you call, the literal main character of getting connected 🫶

---

🌸 NAME 🌸

odbx_init — allocate per connection data structures ✨ (yes, that's the whole name section, it's short and iconic)

---

🎀 SYNOPSIS 🎀

#include <opendbx/api.h>

int odbx_init (odbx_t** handle, const char* backend, const char* host,
              const char* port);

---

💖 DESCRIPTION 💖

so odbx_init() allocates and initializes an opaque object, right? and you literally need this object for all further operations in the OpenDBX library — it's the thing that identifies the connection and holds all the per-connection info 🧚 think of it as your connection's little passport.

depending on the backend, it can open a connection to the database server — but ngl, a lot of the time that doesn't happen until you actually authenticate through odbx_bind(). so don't assume you're connected yet, okay? 😌

the pointer to the newly allocated connection object gets stored in handle if odbx_init() completes successfully 💫 otherwise the value of the handle variable is undefined and you must not use it as input for any other functions in the library. like, fr fr, don't touch it 🙈 the returned connection object must be freed by odbx_finish() so you don't get memory leaks if the application isn't using it anymore — clean up after yourself, queen 👑

---

🦋 the backends, AKA "which database are we even talking to" 🦋

the OpenDBX library gives you access to several different database implementations through a single interface, so it has to know which of the available backend modules it should use for the operations. the backend parameter is what performs the lookup of the requested module 🔍

it has to be a zero-terminated ASCII string with all characters in lower case — lowercase only, bestie, this is not a drill 💀

currently, these backend modules are available:

• firebird (Firebird/Interbase)
• mssql (MS SQL Server via FreeTDS)
• mysql (MySQL)
• oracle (Oracle 8i/9i/10g)
• pgsql (PostgreSQL)
• sqlite (SQLite v2)
• sqlite3 (SQLite v3)
• sybase (Sybase ASE)

---

🌈 the host parameter, or "where even is this database" 🌈

connecting to a database server requires at least an identifier so you know where the database is located. there are several kinds of identifiers — host names, IP addresses, named pipes, etc. — and any one of them can be provided via the host parameter ✨ it's up to the native database library what it will actually accept. most native libraries accept at least host names and IP addresses, and they also use the provided port in that case.

the available methods for host are:

• host name string — supported by Firebird/Interbase, MySQL, Oracle and PostgreSQL backends
• IP address string — supported by Firebird/Interbase, MySQL, Oracle and PostgreSQL backends
• absolute path to Unix domain socket — currently supported by the PostgreSQL backend only
• (relative) directory path with trailing slash/backslash — required by SQLite and SQLite3 backends
• section name in configuration file — required by MS SQL Server and Sybase ASE backends

depending on the native database library, it's also possible to use database specific default values for the host and port parameters by supplying empty, zero-terminated strings or a NULL value 🌸 (yes, NULL is allowed, go off default values 👑)

---

⭐ RETURN VALUE ⭐

odbx_init() returns ODBX_ERR_SUCCESS, or an error code whose value is less than zero if one of the operations couldn't be completed successfully 😭

possible error codes are listed in the ERROR section, and they can be fed to odbx_error() and odbx_error_type() to get further details 🔍

---

💀 ERRORS 💀

• -ODBX_ERR_BACKEND — the backend module returned an error because it couldn't setup the necessary structures
• -ODBX_ERR_PARAM — handle is NULL and the allocated connection object can't be stored
• -ODBX_ERR_NOMEM — allocating new memory for the connection object failed
• -ODBX_ERR_SIZE — the length of a string exceeded the available buffer size
• -ODBX_ERR_NOTEXIST — a backend module with this name wasn't found. either the module isn't installed, the given name was wrong, or it wasn't in the correct character case (lowercase, bestie!! 💅)
• -ODBX_ERR_NOOP — the backend module doesn't provide the required function

---

🫶 SEE ALSO 🫶

odbx_bind(), odbx_capabilities(), odbx_error(), odbx_finish(), odbx_get_option(), odbx_set_option()

---

ok that's the whole page! go forth and initialize, you've got this 🍓

---

mwah 💋 this page is from OpenDBX, dated 6 February 2026 — that's the version/source and date sign-off, periodt ✨