---
name: "odbx_init"
section: "3"
platform: "linux"
package: "opendbx"
version: "1.4.6-13"
release: "Arch Linux 2026-11-01"
platforms: ["linux"]
url: "https://new.carta.tech/odbx_init"
---

# odbx\_init(3)

Allocate per connection data structures

## NAME

odbx\_init - Allocate per connection data structures

## SYNOPSIS

```
FC#include <opendbx/api.h>F[0]
```

FCint **odbx\_init**F\[0\]  FC(odbx\_t\*\* *handle*, const char\* *backend*, const char\* *host*, const char\* *port*);F\[0\]

## DESCRIPTION

FC**odbx\_init**F\[0\]() allocates and initializes an opaque object required for all further operations within the OpenDBX library which is used to identify the connection and to maintain per connection information. Depending on the backend it can open a connection to the database server but often this is done not until performing authentication through FC**odbx\_bind**F\[0\]().

The pointer of the newly allocated connection object is stored in FChandleF\[0\] if FC**odbx\_init**F\[0\]() completes successfully. Otherwise, the value of the FChandleF\[0\] variable will be undefined and must not be used as input for other functions of the library. The returned connection object must be freed by FC**odbx\_finish**F\[0\]() to avoid memory leaks if it will be no longer used by the application.

The OpenDBX library provides access to several different database implementations through a single interface and therefore has to know which one of the available backend modules it should use for the operations. The FCbackendF\[0\] parameter will be used to perform the lookup of the requested module. It has to be a zero-terminated ASCII string with all characters in in lower case. 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)

Connecting to a database server requires at least an identifier to know where the database is located. There are several kinds of identifiers like host names, IP addresses, named pipes, etc. which could be used. One of them can be provided via the FChostF\[0\] parameter and it is up to the native database library what it will accept. Most native libraries accept at least host names and IP addresses and also use the provided FCportF\[0\] in this case. The available methods for FChostF\[0\] 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 FChostF\[0\] and FCportF\[0\] parameters by supplying empty, zero-terminated strings or a NULL value.

## RETURN VALUE

FC**odbx\_init**F\[0\]() returns FCODBX\_ERR\_SUCCESSF\[0\], 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 feed to FC**odbx\_error**F\[0\]() and FC**odbx\_error\_type**F\[0\]() to get further details.

## ERRORS

- \-FCODBX\_ERR\_BACKENDF\[0\]

  The backend module returned an error because it couldn't setup the necessary structures

- \-FCODBX\_ERR\_PARAMF\[0\]

  FChandleF\[0\] is NULL and the allocated connection object can't be stored

- \-FCODBX\_ERR\_NOMEMF\[0\]

  Allocating new memory for the connection object failed

- \-FCODBX\_ERR\_SIZEF\[0\]

  The length of a string exceeded the available buffer size

- \-FCODBX\_ERR\_NOTEXISTF\[0\]

  A backend module with this name wasn't found. Either the module isn't installed, the given name was wrong or not in the correct character case

- \-FCODBX\_ERR\_NOOPF\[0\]

  The backend module doesn't provide the required function

## SEE ALSO

FC**odbx\_bind**F\[0\](), FC**odbx\_capabilities**F\[0\](), FC**odbx\_error**F\[0\](), FC**odbx\_finish**F\[0\](), FC**odbx\_get\_option**F\[0\](), FC**odbx\_set\_option**F\[0\]()