C API Functions
From; https://mariadb.com/kb/en/mariadb-connectorc-api-functions/

Mariadb Function Code Examples

MariaDB Connector/C API Functions
See also MariaDB Connector/C API Prepared Statement Functions for functions

relating to prepared statements.

Using the non-blocking API is documented here, and the API reference for 
non-blocking api calls here.



mariadb_change_user my_bool mysql_change_user(MYSQL *mysql, const char *user, const char *passwd , const char * db); Description Changes the user and default database of the current connection. In order to successfully change users a valid username and password parameters must be provided and that user must have sufficient permissions to access the desired database. If for any reason authorization fails, the current user authentication will remain. Returns zero on success, nonzero if an error occured. mysql_change_user will always cause the current database connection to behave as if was a completely new database connection, regardless of if the operation was completed successfully. This reset includes performing a rollback on any active transactions, closing all temporary tables, and unlocking all locked tables. Code Example
mariadb_cancel Immediately aborts connection
mariadb_get_infov Retrieves generic or connection specific information Code Example
mysql_affected_rows my_ulonglong mysql_affected_rows( MYSQL *mysql); Returns the number of affected rows by the last operation associated with Returns the number of affected rows in previous server operation
mysql_autocommit Toggles autocommit mode on or off for the current database connection
mysql_change_user Changes the user and default database of the current connection
mysql_character_set_name Returns the default client character set for the specified connection
mysql_close void mysql_close( MYSQL *mysql); Closes a previously opened connection Code Examples
mysql_commit my_bool mysql_commit( MYSQL *mysql); Commits the current transaction for the specified database connection. Returns zero on success, nonzero if an error occurred. This function can only be used with buffered result sets obtained from the use of the mysql_store_result function.
mysql_create_db int mysql_create_db( MYSQL *mysql, const char *db) Description Creates the database named by the db parameter. This function is deprecated. Use mysql_real_query() or mysql_query() to issue an SQL CREATE DATABASE statement instead. Return Values Zero for success. Nonzero if an error occurred. Errors Code Examples
mysql_create_db
mysql_data_seek void mysql_data_seek( MYSQL_RES *result, my_ulonglong offset); The mysql_data_seek() function seeks to an arbitrary function result pointer specified by the offset in the result set. Returns zero on success, nonzero if an error occurred. Example
mysql_debug Enables debug logging void mysql_debug(const char * debug); Description Enables debug output for development and debug purposes by using Fred Fish's DBUG library. For using this function the mariadb-client library must be compiled with debug support. Almost all MariaDB binaries use the DBUG library and one can get a trace of the program execution by using the --debug command line option with the binary. This will only work if the binary is compiled for debugging (compiler option -DDBUG_ON). Returns void. The debug control string is a sequence of colon separated fields as follows: field_1:field_2:field_n Each field consists of a mandatory flag character followed by an optional "," and comma separated list of modifiers: flag[,modifier,modifier,...,modifier] The currently recognized flag characters are:
OptionDescription
dEnable output from DBUG_ macros for the current state. May be followed by a list of keywords which selects output only for the DBUG macros with that keyword. A null list of keywords implies output for all macros.
DDelay after each debugger output line. The argument is the number of tenths of seconds to delay, subject to machine capabilities. I.E. -#D,20 is delay two seconds.
fLimit debugging and/or tracing, and profiling to the list of named functions. Note that a null list will disable all functions. The appropriate "d" or "t" flags must still be given, this flag only limits their actions if they are enabled.
FIdentify the source file name for each line of debug or trace output.
iIdentify the process with the pid for each line of debug or trace output.
gEnable profiling. Create a file called 'dbugmon.out' containing information that can be used to profile the program. May be followed by a list of keywords that select profiling only for the functions in that list. A null list implies that all functions are considered.
LIdentify the source file line number for each line of debug or trace output.
nPrint the current function nesting depth for each line of debug or trace output.
NNumber each line of dbug output.
oRedirect the debugger output stream to the specified file. The default output is stderr.
OAs o but the file is really flushed between each write. When needed the file is closed and reopened between each write.
aLike o, but opens for append.
ALike O, but opens for append.
pLimit debugger actions to specified processes. A process must be identified with the DBUG_PROCESS macro and match one in the list for debugger actions to occur.
PPrint the current process name for each line of debug or trace output.
rWhen pushing a new state, do not inherit the previous state's function nesting level. Useful when the output is to start at the left margin.
SDo function _sanity(_file_,_line_) at each debugged function until _sanity() returns something that differs from 0. (Mostly used with safemalloc)
tEnable function call/exit trace lines. May be followed by a list (containing only one modifier) giving a numeric maximum trace level, beyond which no output will occur for either debugging or tracing macros. The default is a compile time option.
Instead of using the mysql_debug() function you also can set the environment variable MYSQL_DEBUG Enabling generation of debug information slows down the overall performance and generates huge files. In case you need debug information only for special places you can disable the generation of debug information by using mysql_debug_end(). See also Code Examples
mysql_dump_debug_info Dump server status information int mysql_dump_debug_info(MYSQL * mysql); Description This function is designed to be executed by an user with the SUPER privilege and is used to dump server status information into the log for the MariaDB Server relating to the connection. Returns zero on success, nonzero if an error occurred. The server status information will be dumped into the error log file, which can usually be found in the data directory of your server installation. Code Examples
mysql_errno unsigned int mysql_errno( MYSQL *mysql); Returns the last error code for the most recent function call that can succeed or fail. Zero means no error occurred.
mysql_error const char *mysql_error( MYSQL *mysql); Returns the last error message for the most recent function call that can succeed or fail. If no error occurred an empty string is returned.
mysql_escape_string Deprecated: escapes a string using the default character set
mysql_fetch_field MYSQL_FIELD *mysql_fetch_field( MYSQL_RES *result); Returns the definition of one column of a result set as a pointer to a MYSQL_FIELD structure. Call this function repeatedly to retrieve information about all columns in the result set. Example
mysql_fetch_fields MYSQL_FIELD *mysql_fetch_fields( MYSQL_RES *res); This function serves an identical purpose to the mysql_fetch_field() function with the single difference that instead of returning one field at a time for each field, the fields are returned as an array. Each field contains the definition for a column of the result set. Code Example Code Example
mysql_fetch_field_direct MYSQL_FIELD *mysql_fetch_field_direct( MYSQL_RES *res, unsigned int fieldnr); Returns a pointer to a MYSQL_FIELD structure which contains field information from the specified result set. Example
mysql_fetch_lengths unsigned long *mysql_fetch_lengths( MYSQL_RES *result); The mysql_fetch_lengths() function returns an array containing the lengths of every column of the current row within the result set (not including terminating zero character) or NULL if an error occurred. Returns the length of the columns of the current row Code Examples
mysql_fetch_row MYSQL_ROW mysql_fetch_row( MYSQL_RES *result); Description Fetches one row of data from the result set and returns it as an array of char pointers (MYSQL_ROW) where each column is stored in an offset starting from 0 (zero). Each subsequent call to this function will return the next row within the result set, or NULL if there are no more rows. If a column contains a NULL value the corresponding char pointer will be set to NULL. Memory associated to MYSQL_ROW will be freed when calling mysql_free_result() function. Get a row from result set Code Examples
mysql_field_count unsigned int mysql_field_count(MYSQL * mysql); Description Returns the number of columns for the most recent query on the connection represented by the link parameter as an unsigned integer. This function can be useful when using the mysql_store_result() function to determine if the query should have produced a non-empty result set or not without knowing the nature of the query. The mysql_field_count() function should be used to determine if there is a result set available. Code Examples
mysql_field_seek MYSQL_FIELD_OFFSET mysql_field_seek( MYSQL_RES *result , MYSQL_FIELD_OFFSET offset ); Description Sets the field cursor to the given offset. The next call to mysql_fetch_field() will retrieve the field definition of the column associated with that offset. Returns the previous value of the field cursor. The number of fields can be obtained from mysql_field_count() . To move the field cursor to the first field offset parameter should be null. Code Examples
mysql_field_tell Get current offset of the field cursor
mysql_free_result void mysql_free_result( MYSQL_RES *result); Description Frees the memory associated with a result set. Returns void. You should always free your result set with mysql_free_result() as soon it's not needed anymore Row values obtained by a prior mysql_fetch_row() call will become invalid after calling mysql_free_result(). Code Examples
mysql_get_character_set_info Returns information about the current active character set
mysql_get_client_info A string representing the version of the client library
mysql_get_client_version Returns a number representing the client library version
mysql_get_host_info Returns host information
mysql_get_optionv int mysql_get_optionv( MYSQL * mysql, enum mysql_option, void * arg, ...); Retrieves the value for a given option previously set by mysql_optionsv() Description Retrieves the value for a given option which was previously set by mysql_optionsv. Returns zero on success, non zero if an error occurred (invalid option). This function was added in MariaDB Connector/C 3.0.0. Options Boolean values (my_bool) Integer values Character values Misc /* get number of connection attributes */ int i, elements= 0; char **key, **value; mysql_get_optionv( mysql, MYSQL_CONNECT_ATTRS, NULL, NULL, (void*)&elements); key= (char **)malloc( sizeof( char* ) * elements); val= (char **)malloc( sizeof( char* ) * elements); mysql_get_optionv(mysql, MYSQL_OPT_CONNECT_ATTRS, &key, &val, &elements); for( i =0; i < elements; i++) printf("key: %s value: %s", key[i], val[i]); const char *ssh_user; mysql_get_optionv( mysql, MARIADB_OPT_USERDATA, "ssh_user", (void *)ssh_user);
mysql_get_proto_info Returns the protocol version number
mysql_get_server_info Get server info
mysql_get_server_version Get numeric server version
mysql_get_ssl_cipher Returns the name of the currently used cipher
mysql_hex_string Converts a string into hexadecimal format
mysql_info Information about the most recently executed query
mysql_init MYSQL *mysql_init( MYSQL *mysql); Prepares and initializes a MYSQL structure to be used with mysql_real_connect(). If mysql_thread_init() was not called before, mysql_init() will also initialize the thread subsystem for the current thread. Members of the MYSQL structure are not intended for application use. Any subsequent calls to any mysql function (except mysql_options()) will fail until mysql_real_connect() was called. Memory allocated by mysql_init() must be freed with mysql_close().
mysql_insert_id my_ulonglong mysql_insert_id(MYSQL * mysql); The mysql_insert_id() function returns the ID generated by a query on a table with a column having the AUTO_INCREMENT attribute or the value for the last usage of LAST_INSERT_ID(expr). If the last query wasn't an INSERT or UPDATE statement or if the modified table does not have a column with the AUTO_INCREMENT attribute and LAST_INSERT_ID was not used, this function will return zero. Returns the auto generated id used in the last query
mysql_kill int mysql_kill(MYSQL * mysql, unsigned long); Asks the server to kill a connection thread This function is used to ask the server to kill a MariaDB thread specified by the processid parameter. This value must be retrieved by SHOW PROCESSLIST If trying to kill the own connection mysql_thread_id() should be used. Returns 0 on success, otherwise nonzero.
mysql_library_end Call when finished using the library
mysql_library_init Initializes the library
mysql_more_results Check if there are any more query results from a multi query
mysql_next_result Prepares next result set from a multi query
mysql_num_fields unsigned int mysql_num_fields( MYSQL_RES * ); Description Returns number of fields in a result set Code Examples See Also mysql_fetch_field()
mysql_num_rows my_ulonglong mysql_num_rows( MYSQL_RES * ); Returns number of rows in a result set Code Example
mysql_options int mysql_options( MYSQL *mysql, enum mysql_option, const void *arg); Used to set extra connect options and affect behavior for a connection. This function may be called multiple times to set several options. mysql_options() should be called after mysql_init() and before mysql_real_connect(). Returns zero on success, non zero if an error occurred (invalid option or value). This function is deprecated as of MariaDB Connector/C 3.0 and will be removed in future releases. It's preferable to use mysql_optionsv. Set extra connect options and affect behavior for a connection
mysql_optionsv int mysql_optionsv( MYSQL *mysql, enum mysql_option, const void *arg, ...); Used to set extra connect options and affect behavior for a connection. This function may be called multiple times to set several options. mysql_optionsv() should be called after mysql_init(). Some of these options can also be set in option files, such as my.cnf Set extra connect options and affect behavior for a connection.
mysql_ping Pings a server connection
mysql_query Performs a query on the database
mysql_real_connect MYSQL *mysql_real_connect( MYSQL *mysql, const char *host , const char *user, const char *passwd, const char *db, unsigned int port , const char *unix_socket, unsigned long flags); Establishes a connection to a database server Description Establishes a connection to a database server. Returns a MYSQL * handle or NULL if an error occurred. The password doesn't need to be encrypted before executing mysql_real_connect(). This will be handled in the client server protocol. The connection handle can't be reused for establishing a new connection. It must be closed and reinitialized before.
mysql_real_escape_string Escapes special characters in a string
mysql_real_query Performs a query on the database int mysql_real_query( MYSQL *mysql, const char *query, unsigned long); mysql_real_query() is the binary safe function for performing a statement on the database server. Returns zero on success, otherwise non-zero. Contrary to the mysql_query() function, mysql_real_query is binary safe. To determine if mysql_real_query returns a result set use the mysql_num_fields() function. Code Examples
mysql_refresh Flush server information
mysql_reset_connection Resets the current connection and clears session state
mysql_rollback Rolls back current transaction
mysql_row_seek Positions row cursor
mysql_row_tell Returns position of result cursor
mysql_select_db Selects a database as default
mysql_send_query Syntax int mysql_send_query(MYSQL * mysql, const char ...
mysql_server_end Alias for mysql_library_end()
mysql_server_init Alias for mysql_library_init()
mysql_session_track_get_first retrieves the first session status change information received from the server
mysql_session_track_get_next Syntax int mysql_session_track_get_next(MYSQL * mysql,enum enum_session_sta...
mysql_set_character_set Sets the default client character set
mysql_set_server_option Enables or disables server option
mysql_shutdown Shuts down the database server
mysql_sqlstate Returns sqlstate error
mysql_ssl_set For setting up a secure TLS connection
mysql_stat const char * mysql_stat(MYSQL * mysql); Description mysql_stat() returns a string with the current server status for uptime, threads, queries, open tables, flush tables and queries per second. For a complete list of other status variables, you have to use the SHOW STATUS SQL command.
mysql_stmt_attr_set() bool mysql_stmt_attr_set( MYSQL_STMT *stmt , enum enum_stmt_attr_type option, const void *arg ) Description Can be used to affect behavior for a prepared statement. This function may be called multiple times to set several options. The option argument is the option that you want to set. The arg argument is the value for the option. arg should point to a variable that is set to the desired attribute value. The variable type is as indicated in the following table. The following table shows the possible option values.
OptionArg TypeFunction
STMT_ATTR_UPDATE_MAX_LENGTH bool * If set to 1, causes mysql_stmt_store_result() to update the metadata MYSQL_FIELD->max_length value.
STMT_ATTR_CURSOR_TYPE unsigned long * Type of cursor to open for statement when mysql_stmt_execute() is invoked. *arg can be CURSOR_TYPE_NO_CURSOR (the default) or CURSOR_TYPE_READ_ONLY.
STMT_ATTR_PREFETCH_ROWS unsigned long * Number of rows to fetch from server at a time when using a cursor. *arg can be in the range from 1 to the maximum value of unsigned long. The default is 1.
If you use the STMT_ATTR_CURSOR_TYPE option with CURSOR_TYPE_READ_ONLY, a cursor is opened for the statement when you invoke mysql_stmt_execute(). If there is already an open cursor from a previous mysql_stmt_execute() call, it closes the cursor before opening a new one. mysql_stmt_reset() also closes any open cursor before preparing the statement for re-execution. mysql_stmt_free_result() closes any open cursor. If you open a cursor for a prepared statement, mysql_stmt_store_result() is unnecessary, because that function causes the result set to be buffered on the client side. Return Values Zero for success. Nonzero if option is unknown. Errors None. Code Example
mysql_store_result MYSQL_RES *mysql_store_result( MYSQL *mysql); Returns a buffered result set from the last executed query MYSQL_RES
mysql_thread_end Release thread specific memory for multi threaded client application
mysql_thread_id Returns the thread id for the current connection
mysql_thread_init Thread initialization for multi threaded clients
mysql_thread_safe Whether or not the client library is compiled as thread safe
mysql_use_result MYSQL_RES *mysql_use_result( MYSQL *mysql ); Used to initiate the retrieval of a result set from the last query executed using the mysql_real_query() function on the database connection. Either this or the mysql_store_result() function must be called before the results of a query can be retrieved, and one or the other must be called to prevent the next query on that database connection from failing. Returns an unbuffered result set or NULL if an error occurred. Initiate an unbuffered result set retrieval
mysql_warning_count Returns the number of warnings from the last executed query
mysql_reconnect Reconnects to server
mysql_read_query_result Syntax int mysql_read_query_result(MYSQL * mysql); mysql - a mysql handle, ...