libdbi uses a plugin system that allows various databases to be supported simultaneously, and can dynamically load or unload drivers that are supplied by libdbi or a third party. The library is initiallized by calling and a connection instance is started by calling either or both and . The connection's options (username, password, hostname, etc.) are set with and . Once all options are set, will connect to the database, waiting to handle a . A query is a string containing a valid SQL statement. libdbi provides several functions to automatically quote any characters that might screw up the query string. The preferred functions are and as they take into consideration the character encoding used by the current connection. The legacy functions and are still supported but should be avoided in new code. After a successful query, you can retrieve rows with , , , , and . String data may be sent to and retrieved from a database using character encodings if they contain characters not covered by the ASCII character set. Most database engines support character encodings like ISO-8859-1, suitable for many European languages, or even the multibyte Unicode character sets like UTF-8. The character set used to store your data in your database is usually set by the CREATE DATABASE command, which you have to take care of yourself. libdbi uses the connection option "encoding" to select a particular character encoding for the current connection. If you set the value to "auto", libdbi will automatically use the database character encoding as the connection encoding. If you request a different character encoding, as defined by its IANA name, libdbi will convert the data on the fly. There are two methods for fetching field data, and two ways to perform each method. You can either "pull" the data from DBI using the dbi_result_get_* family of functions, or have DBI automatically "push" the data into predefined variables with the dbi_result_bind_* family of functions. Both families of functions are as strongly typed as most SQL database engines are. That is, you must use the dbi_result_get_* or dbi_result_bind_* function that matches the type of the requested field. shows an overview of these functions sorted by the field type they retrieve. Pulling the data from the database can be done with one of the "get" functions such as or , which simply return the data in the field you asked for. You should run the function immediately after each call to a "get" function to check for errors. You can also get more than one field at a time with , which uses a printf-like syntax. If you want DBI to automatically fill your program's variables with field values whenever a new row is fetched, you can "bind" fields to your variables. Bindings are set up with , , and the rest of the bind family of functions. Like the associated "get" function, you can set up multiple bindings at once with the function. String data can be safely included into query strings by using the and functions. Binary data can be included into query strings by using the function. All of these functions return zero-terminated strings enclosed in the appropriate quoting characters. Binary strings are returned in their binary representation. That is, they may contain null bytes and other non-printable characters. It is mandatory to use the or functions to determine the number of bytes contained in the binary string. Caveats: For fields holding integers (not fractional numbers), DBI differentiates between signed and unsigned variables. By default, DBI returns signed values. If you want an unsigned value, prepend a "u" to the name of the target type. For example, dbi_result_bind_short becomes dbi_result_bind_ushort. You must set up any bindings after a successful query but before you fetch any rows. Even if you are using field bindings, you can still use the dbi_result_get_* functions as usual. (actually, I lied... setting up a binding should theoretically work at any time, but don't plan on this behavior in future versions) All string and binary data returned or bound from DBI is read-only. If you want your own local copy that can be modified at will, use , , , or . You will be responsible for freeing the memory allocated by these functions. and the other row-seeking functions will return zero when there are no more rows available. Before the next database operation is performed, you must call . Before the program terminates, the connection must be disconnected and unloaded with and libdbi must be unloaded with . field type get by name get by field index bind signed char unsigned char short unsigned short int unsigned int long long unsigned long long float double character string , , binary string , , date/time