1 of 92

mariadb_cancel

mariadb_cancel immediately aborts a connection by making all subsequent read/write operations fail, without freeing the MYSQL structure or closing communication channels.

Syntax

int mariadb_cancel(MYSQL * mysql);

Parameter

mysql - mysql handle, which was previously allocated by mysql_init() or mysql_real_connect().

Description

Immediately aborts a connection by making all subsequent read/write operations fail.mariadb_cancel() does not invalidate memory used for mysql structure, nor close any communication channels. To free the memory, mysql_close() must be called.mariadb_cancel() is useful to break long queries in situations where sending KILL is not possible.

Return Value

Returns zero on success or a non-zero value on error.

History

mariadb_cancel() was added in Connector/C 3.0

mariadb_connect

Connect to a database server using a connection string

Syntax

Parameter

mysql - mysql handle, which was previously allocated by mysql_init() and connected by mysql_real_connect().
conn_str- Connection string, containing connection parameters. A connection string contains key/value pairs, separated by a semicolon as used in ODBC. Supported keys are all configuration options which can be used in MariaDB configuration files. For a complete list check the chapter configuration files.

Return Value

Returns a MYSQL * handle or NULL on error.

Note

The connection string must contain at least one semicolon, otherwise it will be interpreted as hostname.
Unknown or invalid keys will be ignored
mariadb_connect is not a function, but a macro which maps to mysql_real_connect: #define mariadb_connect(mysql, conn_str) mysql_real_connect((mysql),(conn_str), NULL, NULL, NULL, 0, NULL, 0)

Example

History

mariadb_connect() was added in Connector/C 3.3.0.

mariadb_connection

Syntax

Parameter

mysql - mysql handle, which was previously allocated by mysql_init() and connected by mysql_real_connect().

Description

Checks if the client is connected to a MariaDB or MySQL database server.

Return Value

Returns a non zero value if connected to a MariaDB database server, otherwise zero.

mariadb_convert_string

Syntax

#include <mysql.h>

size_t mariadb_convert_string(const char *from __attribute__((unused)),
                              size_t *from_len __attribute__((unused)),
                              MARIADB_CHARSET_INFO *from_cs __attribute__((unused)),
                              char *to __attribute__((unused)),
                              size_t *to_len __attribute__((unused)),
                              MARIADB_CHARSET_INFO *to_cs __attribute__((unused)), int *errorcode)

Description

Converts a string in to a different character set

This function is deprecated.

mariadb_field_attr

Syntax

Parameter

attr: A pointer which returns extended metadata information
field: Specifies the field which contains extended metadata information
type: Specifies type of metadata information. Supported types are MARIADB_FIELD_ATTR_DATA_TYPE_NAME and MARIADB_FIELD_ATTR_FORMAT_NAME.

Description

Returns extended metadata information for pluggable field types like JSON and GEOMETRY.

Return Value

Returns zero on success or non zero if the field doesn't provide extended metadata information.

Notes

Pluggable field type support is available in MariaDB server version 10.5.2 and later.
To check if the server supports pluggable field types, check the extended server capabilities which can be obtained by api function mariadb_get_info().

Example

History

mariadb_field_attr was added in MariaDB Connector/C 3.1.8.

mariadb_get_info

Syntax

Description

Retrieves generic or connection related information.

This function is deprecated. Please use mariadb_get_infov() instead.

mariadb_get_infov

mariadb_get_infov retrieves generic or connection-specific information from a MariaDB Connector/C handle, accepting a value-type enum and a pointer to store the result.

Syntax

my_bool mariadb_get_infov(MYSQL * mysql,
                      enum mariadb_value value,
                      void * arg,
                      ...);

Parameter

mysql - a mysql handle, which was previously allocated by mysql_init() or mysql_real_connect(). For general information which is not bound to connection this parameter might be null.
value - the type of value you want to retrieve. See description below.
arg - pointer to a variable for storing value of the specified option.
... - variable argument list

Description

Retrieves generic or connection specific information. Returns zero on success, non-zero if an error occurred (invalid option), This function was added in MariaDB Connector/C 3.0,

Value types

Generic information

For these information types of parameters mysql needs to be set to NULL.

MARIADB_CHARSET_NAME: Retrieves the charset information for a character set by its literal representation.Parameter type: const MARIADB_CHARSET_INFO*.
MARIADB_CLIENT_ERRORS: Retrieve array of client errors. This can be used in plugins to set global error messages (which are not exported by MariaDB Connector/C).Parameter type: const char **.
MARIADB_CLIENT_VERSION: The client version in literal representation.Parameter type: const char *.
MARIADB_CLIENT_VERSION_ID: The client version in numeric format.Parameter type: unsigned int.
MARIADB_MAX_ALLOWED_PACKET: Retrieves value of maximum allowed packet size.Parameter type: size_t
MARIADB_NET_BUFFER_LENGTH: Retrieves the length of net buffer.Parameter type: size_t
MARIADB_TLS_LIBRARY: The TLS library MariaDB Connector/C is compiled against.Parameter type: const char *.

MARIADB_CONNECTION_ASYNC_TIMEOUT: Retrieves the timeout for non-blocking calls in seconds.Parameter type: unsigned int.
MARIADB_CONNECTION_ASYNC_TIMEOUT_MS: Retrieves the timeout for non-blocking calls in milliseconds.Parameter type: unsigned int.
MARIADB_CONNECTION_MARIADB_CHARSET_INFO: Retrieves character set information for given connection. Parameter type: const MY_CHARSET_INFO *.
MARIADB_CONNECTION_CLIENT_CAPABILITIES: Returns the capability flags of the client.Parameter type: unsigned long.
MARIADB_CONNECTION_ERROR: Retrieves error message for last used command. Parameter type: const char *.
MARIADB_CONNECTION_ERROR_ID: Retrieves error number for last used command. Parameter type: unsigned int.
MARIADB_CONNECTION_EXTENDED_SERVER_CAPABILITIES: Returns the extended capability flags of the connected MariaDB server.Parameter type: unsigned long.
MARIADB_CONNECTION_HOST: Retrieves connection's host name. Parameter type: const char *.
MARIADB_CONNECTION_INFO: Retrieves generic info for last used command.Parameter type: const char *.
MARIADB_CONNECTION_PORT: Retrieves the port number of server host.Parameter type: unsigned int.
MARIADB_CONNECTION_PROTOCOL_VERSION_ID: Retrieves the protocol version number.Parameter type: unsigned int.
MARIADB_CONNECTION_PVIO_TYPE: Retrieves the pvio plugin used for specified connection.Parameter type: unsigned int.
MARIADB_CONNECTION_SCHEMA: Retrieves the current schema.Parameter type: const char*.
MARIADB_CONNECTION_SERVER_CAPABILITIES: Returns the capability flags of the connected server.Parameter type: unsigned long.
MARIADB_CONNECTION_SERVER_STATUS: Returns server status after last operation. A list of possible flags can be found in the description OK packet.Parameter type: unsigned int.
MARIADB_CONNECTION_SERVER_TYPE: Retrieves the type of the server.Parameter type: const char*.
MARIADB_CONNECTION_SERVER_VERSION: Retrieves the server version in literal format.Parameter type: const char *.
MARIADB_CONNECTION_SERVER_VERSION_ID: Retrieves the server version in numeric format.Parameter type: unsigned int.
MARIADB_CONNECTION_SOCKET: Retrieves the handle (socket) for given connection.Parameter type: my_socket.
MARIADB_CONNECTION_SQLSTATE: Retrieves current sqlstate information for last used command. Parameter type: const char *.
MARIADB_CONNECTION_SSL_CIPHER: Retrieves the TLS cipher in use.Parameter type: const char *.
MARIADB_CONNECTION_TLS_VERSION: Retrieves the TLS protocol version used in literal format.Parameter type: char *.
MARIADB_CONNECTION_TLS_VERSION_ID: Retrieves the TLS protocol version used in numeric format.Parameter type: unsigned int.
MARIADB_CONNECTION_UNIX_SOCKET: Retrieves the file name of the unix socketParameter type: const char *.
MARIADB_CONNECTION_USER: Retrieves connection's user name.Parameter type: const char *.
MARIADB_TLS_PEER_CERT_INFO Retrieves peer certificate information for TLS connections. The returned pointer to a MARIADB_X509_INFO structure becomes invalid after the connection has been closed. (Added in version 3.4.0)
MARIADB_TLS_VERIFY_STATUS Retrieves the status of a previous peer certificate verification. The status is represented as a combination of TLS verification flags. This option was added in version 3.4.1

Return Value

Returns zero on success, non zero if an error occurred (e.g. if an invalid option was specified),

History

This function was added in MariaDB Connector/C 3.0,

Examples

/* get server port for current connection */
unsigned int port;
mariadb_get_infov(mysql, MARIADB_CONNECTION_PORT, void *)&port);

/* get user name for current connection */
const char *user;
mariadb_get_infov(mysql, MARIADB_CONNECTION_USER, (void *)&user);

mariadb_reconnect

mariadb_reconnect attempts to re-establish a dropped MariaDB Connector/C connection using the original credentials, and requires the MYSQL_OPT_RECONNECT option to be set.

Syntax

my_bool  mariadb_reconnect(MYSQL * mysql)

Parameter

mysql - a mysql handle, which was previously allocated by mysql_init() or mysql_real_connect().

Description

mariadb_reconnect() tries to reconnect to a server in case the connection died due to timeout or other errors. It uses the same credentials which were specified in mysql_real_connect().

Return Value

The function will return 0 on success. The function will return an error, if the option MYSQL_OPT_RECONNECT wasn't specified before.

History

This function was added in Connector/C 3.0.

mysql_affected_rows

mysql_affected_rows returns the number of rows affected by the last INSERT, UPDATE, DELETE, or REPLACE statement executed on a MariaDB Connector/C connection.

Syntax

my_ulonglong mysql_affected_rows(MYSQL * mysql);

Parameter

mysql is a connection identifier, which was previously allocated by mysql_init() or mysql_real_connect().

Description

Returns the number of affected rows by the last operation associated with MySQL, if the operation was an "upsert" (, , or ) statement, or UINT64_MAX (0xffffffffffffffff) if the last query failed.

When using , MariaDB will not update columns where the new value is the same as the old value. This creates the possibility that mysql_affected_rows may not actually equal the number of rows matched, only the number of rows that were literally affected by the query.

The statement first deletes the record with the same primary key and then inserts the new record. This function returns the number of deleted records in addition to the number of inserted records.

Return Value

Returns the number of affected rows or -1 on error.

mysql_autocommit

mysql_autocommit enables or disables autocommit mode for the current database connection, returning zero on success or nonzero on failure.

Syntax

my_bool mysql_autocommit(MYSQL * mysql, my_bool auto_mode);

Parameters

mysql - a mysql handle, identifier, which was previously allocated by mysql_init() or mysql_real_connect().
auto_mode - whether to turn on or not.

Description

Toggles autocommit mode on or off for the current database connection. Autocommit mode will be set if mode=1 or unset if mode=0.

Return Value

Returns zero on success, or nonzero if an error occurred.

mode only affects operations on transactional table types. To determine the current state of autocommit mode use the SQL command SELECT @@autocommit. Be aware: the mysql_rollback() function will not work if autocommit mode is switched on.

Examples

SQL

# Turn off autocommit
SET AUTOCOMMIT=0;

# Retrieve autocommit
SELECT @@autocommit;
+--------------+
| @@autocommit |
+--------------+
|            0 |
+--------------+

MariaDB Connector/C

static int test_autocommit(MYSQL *mysql)
{
  int rc;
  unsigned int server_status;
  
  /* Turn autocommit off */
  rc= mysql_autocommit(mysql, 0);
  if (rc)
    return rc; /* Error */

  /* If autocommit = 0 succeeded, the last OK packet updated the server status */
  rc= mariadb_get_infov(mysql, MARIADB_CONNECTION_SERVER_STATUS, &server_status);
  if (rc)
    return rc; /* Error */

  if (server_status & SERVER_STATUS_AUTOCOMMIT)
  {
    printf("Error: autocommit is on\n");
    return 1;
  }
  printf("OK: autocommit is off\n");
  return 0;
}

mysql_change_user

mysql_change_user changes the authenticated user and default database on an existing connection, resetting session state including transactions, temporary tables, and locks.

Syntax

my_bool mysql_change_user(MYSQL * mysql,
                          const char * user,
                          const char * passwd,
                          const char * db);

mysql - a mysql handle, which was previously allocated by mysql_init() or mysql_real_connect().
user - the user name for server authentication
passwd - the password for server authentication
db - the default database. If desired, the NULL value may be passed resulting in only changing the user and not selecting a database. To select a database in this case use the mysql_select_db() function.

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.

Return Value

Returns zero on success, nonzero if an error occurred.

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.

mysql_character_set_name

mysql_character_set_name returns the name of the default client character set for a specified MariaDB Connector/C connection.

Syntax

const char * mysql_character_set_name(MYSQL * mysql);

Parameter

mysql - a mysql handle, which was previously allocated by mysql_init() or mysql_real_connect().

Description

Returns the default client for the specified connection.

Return value

The character set name used for the specified connection.

This function is deprecated. Instead, use mariadb_get_infov() with option MARIADB_CONNECTION_CHARSET_INFO.

mysql_client_find_plugin

Syntax

Parameters

mysql is a connection identifier, which was previously initialized by mysql_init() and optional connected by mysql_real_connect().
name The name of the plugin.
type The plugin type.

Valid Plugin Types

MYSQL_CLIENT_AUTHENTICATION_PLUGIN
MARIADB_CLIENT_PVIO_PLUGIN
MARIADB_CLIENT_REMOTEIO_PLUGIN
MARIADB_CLIENT_CONNECTION_PLUGIN or MARIADB_CLIENT_COMPRESSION_PLUGIN.

Return Value

A pointer to the plugin handle, or NULL if an error occurred.

If the type of the plugin is not known, -1 needs to be specified for parameter type.

mysql_close

mysql_close terminates an open database connection and releases the memory allocated for the MYSQL handle.

Syntax

void mysql_close(MYSQL * mysql);

Parameter

mysql - a mysql handle, which was previously allocated by mysql_init() or mysql_real_connect().

Description

Closes a previously opened connection and deallocates all memory.

To reuse a connection handle after mysql_close() the handle must be initialized again by mysql_init().

mysql_commit

mysql_commit commits the current transaction on a MariaDB Connector/C connection, returning zero on success without affecting autocommit mode.

Syntax

my_bool mysql_commit(MYSQL * mysql);

Parameter

mysql - a mysql handle, which was previously allocated by mysql_init() or mysql_real_connect().

Description

Commits the current transaction for the specified database connection.

Return Value

Returns zero on success, nonzero if an error occurred.

Executing mysql_commit() will not affected the behaviour of . This means, any update or insert statements following mysql_commit() will be rolled back when the connection gets closed.

mysql_data_seek

mysql_data_seek moves the result set pointer to an arbitrary row offset in a buffered result set obtained via mysql_store_result, enabling random row access.

Syntax

void mysql_data_seek(MYSQL_RES * result,
                     my_ulonglong offset);

Parameters

result - a result set identifier returned by mysql_store_result().
offset - the field offset. Must be between zero and the total number of rows minus one (0..mysql_num_rows - 1).

Description

The mysql_data_seek() function seeks to an arbitrary function result pointer specified by the offset in the result set.

This function can only be used with buffered result sets obtained from the use of the mysql_store_result function.

mysql_debug

mysql_debug enables debug output for a MariaDB Connector/C client using the DBUG library, accepting a colon-separated control string to configure trace and logging options.

Syntax

void mysql_debug(const char * debug);

debug - a string representing the debug operation to perform. See description below.

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 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:

Option

Description

Enable 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.

Delay 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.

Limit 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.

Identify the source file name for each line of debug or trace output.

Identify the process with the pid for each line of debug or trace output.

Enable 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.

Identify the source file line number for each line of debug or trace output.

Print the current function nesting depth for each line of debug or trace output.

Number each line of dbug output.

Redirect the debugger output stream to the specified file. The default output is stderr.

As o but the file is really flushed between each write. When needed the file is closed and reopened between each write.

Like o, but opens for append.

Like O, but opens for append.

Limit 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.

Print the current process name for each line of debug or trace output.

When 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.

Do function _sanity(file,line) at each debugged function until _sanity() returns something that differs from 0. (Mostly used with safemalloc)

Enable 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().

This function is deprecated and not supported anymore.

mysql_dump_debug_info

mysql_dump_debug_info instructs a MariaDB server to write connection status information to the error log, and requires the SUPER privilege for the current user.

Syntax

int mysql_dump_debug_info(MYSQL * mysql);

Parameter

mysql - a mysql handle, which was previously allocated by mysql_init() or mysql_real_connect().

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.

Return Value

Returns zero on success, nonzero if an error occurred.

The server status information will be dumped into the file, which can usually be found in the data directory of your server installation.

mysql_eof

Syntax

Parameter

Description

result

A result set handle returned by mysql_store_result().

Description

mysql_eof determines whether the final row in a result set has already been retrieved.

Return Value

Returns non-zero (true) if the entire result set has been read, or zero (false) if rows are still available.

Deprecated. mysql_eof is deprecated. To determine the end of a result set, check the return value of mysql_fetch_row instead: a NULL return indicates that all rows have been fetched.

When the result set was acquired via mysql_store_result(), mysql_eof always returns true because the entire result is buffered in memory at retrieval time.

mysql_errno

mysql_errno returns the numeric error code from the most recent MariaDB Connector/C function call, or zero if no error occurred.

Syntax

unsigned int mysql_errno(MYSQL * mysql);

Parameter

mysql - a mysql handle, which was previously allocated by mysql_init() or mysql_real_connect().

Description

Returns the last for the most recent function call that can succeed or fail. Zero means no error occurred.

Client error messages are listed in errmsg.h header file, server error messages are listed in mysqld_error.h header file of the server source distribution.

mysql_error

mysql_error returns the error message string for the most recent failed MariaDB Connector/C function call, or an empty string if no error occurred.

Syntax

const char * mysql_error(MYSQL * mysql);

Parameter

mysql - a mysql handle, which was previously allocated by mysql_init() or mysql_real_connect().

Description

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.

Client error codes are listed in errmsg.h header file, server error codes are listed in mysqld_error.h header file of the server source distribution.
Client error messages can be obtained by calling mariadb_get_infov() and passing the parameter MARIADB_CLIENT_ERRORS

mysql_escape_string

mysql_escape_string encodes a string using the default character set for safe use in SQL statements. Deprecated — use mysql_real_escape_string instead.

Syntax

unsigned long mysql_escape_string(char * to,
                                  const char * from,
                                  unsigned long);

Description

Escapes a string using the default character set.

This function is deprecated and will be discontinued. Please use mysql_real_escape_string() instead.

mysql_fetch_field

mysql_fetch_field returns the definition of one result set column as a MYSQL_FIELD pointer; call it repeatedly to iterate over all columns in the result set.

Syntax

MYSQL_FIELD * mysql_fetch_field(MYSQL_RES * result);

Parameter

result - a result set identifier returned by mysql_store_result() or mysql_use_result().

Description

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.

Return Value

A pointer of a MYSQL_FIELD structure, or NULL if there are no more fields.

The field order will be reset if you execute a new SELECT query.

In case only information for a specific field is required the field can be selected by using the mysql_field_seek() function or obtained by mysql_fetch_field_direct() function.

mysql_fetch_field_direct

mysql_fetch_field_direct returns a MYSQL_FIELD pointer for a specific column in a result set, identified by its zero-based field number.

Syntax

MYSQL_FIELD * mysql_fetch_field_direct(MYSQL_RES * res,
                                       unsigned int fieldnr);

Parameters

res - a result set identifier returned by mysql_store_result() or mysql_use_result().
fieldnr - the field number. This value must be within the range from 0 to number of fields - 1

Description

Returns a pointer to a MYSQL_FIELD structure which contains field information from the specified result set.

Return Value

Pointer to a MYSQL_FIELD structure. The caller must ensure that fieldnr is less than mysql_field_count(); specifying an out-of-range value results in undefined behavior, not a NULL return.

The total number of fields can be obtained by mysql_field_count().

mysql_fetch_fields

mysql_fetch_fields returns all column definitions for a MariaDB result set as an array of MYSQL_FIELD structures, one entry per column.

Syntax

MYSQL_FIELD * mysql_fetch_fields(MYSQL_RES * res);

Parameter

res - a result set identifier returned by mysql_store_result() or mysql_use_result().

Description

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.

Return Value

An array of type MYSQL_FIELD.

The total number of fields can be obtained by mysql_field_count().

mysql_fetch_lengths

mysql_fetch_lengths returns an array of byte lengths for each column in the current row of a MariaDB result set, valid only after mysql_fetch_row is called.

Syntax

unsigned long * mysql_fetch_lengths(MYSQL_RES * result);

Parameter

result - a result set identifier returned by mysql_store_result() or mysql_use_result().

Description

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.

Return Value

An array of unsigned long values . The size of the array can be determined by the number of fields in current result set.

mysql_fetch_lengths() is valid only for the current row of the result set. It returns NULL if you call it before calling mysql_fetch_row() or after retrieving all rows in the result.

mysql_fetch_row

mysql_fetch_row retrieves the next row from a MariaDB result set as an array of char pointers, returning NULL when no more rows are available.

Syntax

MYSQL_ROW mysql_fetch_row(MYSQL_RES * result);

Parameter

result - a result set identifier returned by mysql_store_result() or mysql_use_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.

mysql_field_count

mysql_field_count returns the number of columns in the most recent query result for a MariaDB connection, useful for checking whether a result set is available.

Syntax

unsigned int mysql_field_count(MYSQL * mysql);

Parameter

mysql - a mysql handle, which was previously allocated by mysql_init() or mysql_real_connect().

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.

Return Value

The number of columns for the most recent statement. The value is zero, if the statement didn't produce a result set.

The mysql_field_count() function should be used to determine if there is a result set available.

mysql_field_seek

mysql_field_seek sets the field cursor to a given column offset in a MariaDB result set, controlling which field mysql_fetch_field returns next.

Syntax

MYSQL_FIELD_OFFSET mysql_field_seek(MYSQL_RES * result,
                                    MYSQL_FIELD_OFFSET offset);

Parameters

result - a result set identifier returned by mysql_store_result() or mysql_use_result().
offset - the field number. This number must be in the range from 0..number of fields - 1.

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.

Return Value

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.

mysql_field_tell

mysql_field_tell retrieves the current field cursor position in a result set, which can be passed to mysql_field_seek to restore that position.

Syntax

MYSQL_FIELD_OFFSET mysql_field_tell(MYSQL_RES * result);

Parameter

result - a result set identifier returned by mysql_store_result() or mysql_use_result().

Description

Return the offset of the field cursor used for the last mysql_fetch_field() call. This value can be used as a parameter for the function mysql_field_seek().

Return Value

Returns the current offset of the field cursor

mysql_free_result

mysql_free_result releases the memory allocated for a MariaDB result set; row values obtained from prior mysql_fetch_row calls become invalid after this call.

Syntax

void mysql_free_result(MYSQL_RES * result);

Parameter

result - a result set identifier returned by mysql_store_result() or mysql_use_result().

Description

Frees the memory associated with a result set.

Return Value

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().

mysql_get_character_set_info

mysql_get_character_set_info populates a MY_CHARSET_INFO structure with details about the current default character set for a MariaDB Connector/C connection.

Syntax

void mysql_get_character_set_info(MYSQL * mysql,
                                  MY_CHARSET_INFO * charset);

Parameters

mysql - a mysql handle, which was previously allocated by mysql_init() or mysql_real_connect().
charset - a pointer to a MY_CHARSET_INFO structure, in which the information will be copied.

Description

Returns information about the current default for the specified connection.

A complete list of supported character sets in the client library is listed in the function description for mysql_set_character_set_info().

mysql_get_client_info

mysql_get_client_info retrieves the client library version as a string; use mysql_get_client_version for the equivalent numeric value.

Syntax

const char * mysql_get_client_info(void );

Description

Returns a string representing the client library version

To obtain the numeric value of the client library version use mysql_get_client_version().

mysql_get_client_version

mysql_get_client_version retrieves the client library version as an unsigned long; use mysql_get_client_info for the string representation.

Syntax

unsigned long mysql_get_client_version(void);

Description

Returns a number representing the client library version. The value has the format XXYYZZ: major version * 10000 + minor version * 100 + patch version.

Return Value

A long integer representing the client version

To obtain a string containing the client library version use the mysql_get_client_info() function.
Since MariaDB Server 10.2.6 and MariaDB Connector/C 3.0.1 the client library is bundled with server package and returns the server package version. To obtain the client version of the connector, please use the constant MARIADB_PACKAGE_VERSION_ID

mysql_get_host_info

mysql_get_host_info returns a string describing the connection type and server hostname for a MariaDB Connector/C connection, or NULL if invalid.

Syntax

char * mysql_get_host_info(MYSQL * mysql);

Parameter

mysql - a mysql handle, which was previously allocated by mysql_init() or mysql_real_connect().

Description

Describes the type of connection in use for the connection, including the server host name.

Return Value

Returns a string, describing host information or NULL if the connection is not valid.

mysql_get_optionv

mysql_get_optionv retrieves the current value of a connection option previously set with mysql_optionsv, supporting boolean, integer, string, and miscellaneous option types.

Syntax

int mysql_get_optionv(MYSQL * mysql,
                      enum mysql_option,
                      void * arg,
                      ...);

mysql - a mysql handle, which was previously allocated by mysql_init() or mysql_real_connect().
mysql_option - the option you want to retrieve. See description below.
arg - pointer to a variable for storing value of the specified option.
... - variable argument list

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)

MYSQL_OPT_COMPRESS
MYSQL_OPT_NAMED_PIPE
MYSQL_OPT_RECONNECT
MYSQL_REPORT_DATA_TRUNCATION
MYSQL_OPT_NONBLOCK
MYSQL_OPT_SSL_VERIFY_SERVER_CERT
MARIADB_OPT_CONNECTION_READ_ONLY

MYSQL_SECURE_AUTH

uint8_t reconnect;

rc = mysql_get_optionv(mysql, MYSQL_OPT_RECONNECT, &reconnect);

Integer values

MYSQL_OPT_CONNECT_TIMEOUT
MYSQL_OPT_READ_TIMEOUT
MYSQL_OPT_WRITE_TIMEOUT
MYSQL_OPT_LOCAL_INFILE

MYSQL_OPT_PROTOCOL

uint32_t timeout;

rc = mysql_get_optionv(mysql, MYSQL_OPT_CONNECT_TIMEOUT, &timeout);

Character arrays

MYSQL_INIT_COMMAND

char **commands;
int elements;

rc = mysql_get_optionv(mysql, MYSQL_INIT_COMMAND, &commands, &elements);

Character values

MYSQL_READ_DEFAULT_FILE
MYSQL_READ_DEFAULT_GROUP
MYSQL_SET_CHARSET_NAME
MYSQL_PLUGIN_DIR
MYSQL_OPT_SSL_KEY
MYSQL_OPT_SSL_CERT
MYSQL_OPT_SSL_CA
MYSQL_OPT_SSL_CAPATH
MYSQL_OPT_SSL_CRL
MYSQL_OPT_SSL_CRLPATH
MYSQL_OPT_SSL_CIPHER
MARIADB_OPT_SSL_FP
MARIADB_OPT_SSL_FP_LIST
MARIADB_OPT_SSL_PASSPHRASE
MYSQL_DEFAULT_AUTH
MYSQL_OPT_BIND

MARIADB_OPT_CONNECTION_HANDLER

char *plugin_dir;

rc = mysql_get_optionv(mysql, MYSQL_PLUGIN_DIR, &plugin_dir);

Misc

MYSQL_PROGRESS_CALLBACK: requires a function pointer *(const MYSQL *, uint, uint, double, const char *, uint))arg)

MYSQL_CONNECT_ATTRS: this option requires 5 parameters:

/* 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]);

MARIADB_OPT_USERDATA: retrieves userdata for a given key.

const char *ssh_user;
mysql_get_optionv(mysql, MARIADB_OPT_USERDATA, "ssh_user", (void *)ssh_user);

mysql_get_proto_info

mysql_get_proto_info returns the protocol version number used for a MariaDB Connector/C connection; versions 9 and below are not supported.

Syntax

unsigned int mysql_get_proto_info(MYSQL * mysql);

Parameter

mysql - a mysql handle, which was previously allocated by mysql_init() or mysql_real_connect().

Description

Returns the protocol version number for the specified connection.

Return Value

The protocol version number in use.

The client library doesn't support protocol version 9 and prior.

mysql_get_server_info

mysql_get_server_info retrieves the connected server version string; use mysql_get_server_version for the equivalent numeric representation.

Syntax

char * mysql_get_server_info(MYSQL * mysql);

Parameter

mysql - a mysql handle, which was previously allocated by mysql_init() or mysql_real_connect().

Description

Returns the server version or NULL on failure.

Return Value

Returns the server version as zero terminated string or NULLon failure.

To obtain the numeric server version please use mysql_get_server_version().

mysql_get_server_version

mysql_get_server_version retrieves the server version as an unsigned long; use mysql_get_server_info for the equivalent string representation.

Syntax

unsigned long mysql_get_server_version(MYSQL * mysql);

Parameter

mysql - a mysql handle, which was previously allocated by mysql_init() or mysql_real_connect().

Description

Returns an integer representing the version of connected server.

Return Value

The version number of the connected server.

The form of the version number is VERSION_MAJOR * 10000 + VERSION_MINOR * 100 + VERSION_PATCH

mysql_get_ssl_cipher

mysql_get_ssl_cipher returns the name of the TLS cipher in use for a MariaDB Connector/C connection, or NULL for non-TLS connections.

Syntax

const char *mysql_get_ssl_cipher(MYSQL *mysql)

Parameter

mysql - a mysql handle, which was previously allocated by mysql_init() or mysql_real_connect().

Description

Returns the name of the currently used cipher of the , or NULL for non TLS connections.

Return Value

Returns a zero terminated string containing the cipher suite used for a secure connection, or NULL if connection doesn't use TLS/SSL.

Notes

For using mysql_get_ssl_cipher() MariaDB Connector/C must be built with TLS/SSL support, otherwise the function will return NULL.
`mysql_get_ssl_cipher()' can be used to determine if the client server connection is secure.
Depending on the TLS library in use (OpenSSL, GnuTLS or Windows Schannel) the name of the cipher suites may differ. For example the cipher suite 0x002F (TLS_RSA_WITH_AES_128_CBC_SHA) has different names: AES128-SHA for OpenSSL and Schannel and TLS_RSA_AES_128_CBC_SHA1 for GnuTLS.

mysql_get_timeout_value

Syntax

Parameter

Description

mysql

A connection handle previously allocated by mysql_init() and connected by mysql_real_connect().

Description

mysql_get_timeout_value retrieves the current timeout value configured for asynchronous operations on the given connection, expressed in seconds.

Return Value

The timeout value in seconds as an unsigned int.

This function is deprecated. Use mariadb_get_infov() with the MARIADB_CONNECTION_ASYNC_TIMEOUT option instead.

mysql_get_timeout_value_ms

Syntax

Parameter

Description

mysql

A connection handle previously allocated by mysql_init() and connected by mysql_real_connect().

Description

mysql_get_timeout_value_ms retrieves the current timeout value configured for asynchronous operations on the given connection, expressed in milliseconds.

Return Value

The timeout value in milliseconds as an unsigned int.

This function is deprecated. Use mariadb_get_infov() with the MARIADB_CONNECTION_ASYNC_TIMEOUT option instead.

mysql_hex_string

mysql_hex_string converts a binary buffer to a hex-encoded string for safe embedding in SQL; the output buffer must be at least 2*length+1 bytes.

Syntax

unsigned long mysql_hex_string(char * to,
                               const char * from,
                               unsigned long len);

Parameters

to - result buffer
from - the string which will be encoded
len - length of the string (from)

Description

This function is used to create a hexadecimal string which can be used in SQL statements. e.g. INSERT INTO my_blob VALUES(X'A0E1CD').

Return Value

Returns the length of the encoded string without the trailing null character.

The size of the buffer for the encoded string must be 2 * length + 1.
The encoded string does not contain a leading X'.

mysql_info

mysql_info returns a string with summary statistics about the last executed query, covering INSERT, UPDATE, ALTER TABLE, and LOAD DATA operations; returns NULL for SELECT.

Syntax

const char * mysql_info(MYSQL * mysql);

Parameter

mysql - a mysql handle, which was previously allocated by mysql_init() or mysql_real_connect().

Description

The mysql_info() function returns a string providing information about the last query executed.

Return Value

Possible mysql_info return values. The nature of this string is provided below:

Query type

Example result string

Records: 100 Duplicates: 0 Warnings: 0

Records: 3 Duplicates: 0 Warnings: 0

Records: 1 Deleted: 0 Skipped: 0 Warnings: 0

Records: 3 Duplicates: 0 Warnings: 0

Rows matched: 40 Changed: 40 Warnings: 0

Queries which do not fall into one of the preceding formats are not supported (e.g. ). In these situations, mysql_info() will return NULL.

mysql_init

mysql_init allocates and initializes a MYSQL structure for use with mysql_real_connect, and also initializes the thread subsystem if not already done.

Syntax

MYSQL * mysql_init(MYSQL * mysql);

Parameter

mysql - a pointer to MYSQL or NULL. In case of passing a NULL pointer mysql_init() will allocate memory and return a pointer to a MYSQL structure.

Description

Prepares and initializes a MYSQL structure to be used with mysql_real_connect().

mysql_init() also ensures the client library is initialized, via a one-time internal initialization; it does not depend on mysql_thread_init(), which is a no-op retained for compatibility.

Return Value

The mysql_init() function returns an address of a MYSQL structure, or NULL in case of memory allocation error.

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

mysql_insert_id returns the AUTO_INCREMENT value generated by the last INSERT or UPDATE statement on a MariaDB connection, or zero if no such value was produced.

Syntax

my_ulonglong mysql_insert_id(MYSQL * mysql);

Parameter

mysql - a mysql handle, which was previously allocated by mysql_init() or mysql_real_connect().

Description

The mysql_insert_id() function returns the ID generated by a query on a table with a column having the attribute or the value for the last usage of . If the last query wasn't an or statement or if the modified table does not have a column with the attribute and was not used, this function will return zero.

Return Value

Returns the value of the modified column with AUTO_INCREMENT attribute. If the table doesn't contain an auto_increment column or no INSERT/UPDATE statement was executed, this function will return zero.

When performing a multi-insert statement, mysql_insert_id() will return the value of the first row.

mysql_kill

mysql_kill requests the MariaDB server to terminate the thread with the given process ID; use mysql_thread_id to obtain the ID of the current connection.

Syntax

int mysql_kill(MYSQL * mysql,
               unsigned long pid);

Parameters

mysql - a mysql handle, which was previously allocated by mysql_init() or mysql_real_connect().
unsigned long - process id

Description

This function is used to ask the server to kill a MariaDB thread specified by the processid parameter. This value must be retrieved by . If trying to kill the own connection mysql_thread_id() should be used.

Return Value

Returns 0 on success, otherwise error on nonzero.

To stop a running command without killing the connection, use .
The mysql_kill() function only kills a connection; it doesn't free any memory - this must be done explicitly by calling mysql_close().

mysql_load_plugin

Syntax

Parameters

Parameter

Description

mysql

A connection handle previously allocated by mysql_init() and connected by mysql_real_connect().

name

The name of the plugin to load.

type

The plugin type, or -1 to accept any type.

argc

The number of optional arguments that follow.

...

Optional arguments passed to the plugin's initialization function.

Description

mysql_load_plugin searches the client plugin directory for a plugin matching the given name and type, loads it, and calls its initialization function with any supplied arguments. If a plugin with that name is already loaded, the call fails and returns NULL (error "it is already loaded").

Valid Plugin Types

MYSQL_CLIENT_AUTHENTICATION_PLUGIN
MARIADB_CLIENT_PVIO_PLUGIN
MARIADB_CLIENT_REMOTEIO_PLUGIN
MARIADB_CLIENT_CONNECTION_PLUGIN or MARIADB_CLIENT_COMPRESSION_PLUGIN.

Return Value

A pointer to the plugin handle, or NULL if an error occurred.

If the type of the plugin is not known, -1 needs to be specified for parameter type.
The directory which contains the plugin can be specified either by the environment variable MARIADB_PLUGIN_DIR or it can be specified with mysql_optionsv() using the option MYSQL_PLUGIN_DIR.

mysql_library_end

mysql_library_end finalizes the MariaDB Connector/C library after use, performing memory cleanup and shutting down the embedded server if applicable.

Syntax

void mysql_library_end(void)

Description

Call when finished using the library, such as after disconnecting from the server. In an embedded server application, the embedded server is shut down and cleaned up. For a client program, only cleans up by performing memory management tasks.

mysql_server_end() is an alias.

mysql_library_init

mysql_library_init initializes the MariaDB Connector/C library before any other functions are called, starting the embedded server if used in that configuration.

Syntax

int mysql_library_init(int argc, char **argv, char **groups)

Description

Call to initialize the library before calling other functions, both for embedded servers and regular clients. If used on an embedded server, the server is started and subsystems initialized. Returns zero for success, or nonzero if an error occurred.

Call mysql_library_end() to clean up after completion.

mysql_server_init() is an alias.

mysql_more_results

mysql_more_results indicates whether additional result sets remain from a previous multi-statement query, returning 1 if more results are available.

Syntax

my_bool mysql_more_results(MYSQL * mysql);

Parameter

mysql - a mysql handle, which was previously allocated by mysql_init() or mysql_real_connect().

Description

Indicates if one or more result sets are available from a previous call to mysql_real_query().

Return Value

Returns 1 if more result sets are available, otherwise zero..

The function mysql_set_server_option() enables or disables multi statement support.
Multiple result sets can be obtained either by calling a stored procedure or by executing concatenated statements, e.g. SELECT a FROM t1;SELECT b, c FROM t2.

mysql_net_field_length

Syntax

Parameter

Description

packet

A pointer to a pointer to the current position in the packet buffer.

Description

Returns the length of a length encoded field and increments the pointer to the beginning of the field.

Return Value

Returns the length of the field.

This function is part of the low level protocol API and can be used to retrieve data if a callback function was provided for fetching results from prepared statements.

mysql_net_read_packet

Syntax

Parameter

Description

mysql

A connection handle previously allocated by mysql_init() and connected by mysql_real_connect().

Description

mysql_net_read_packet reads the next protocol packet from the server into the connection's internal network buffer.

Return Value

Returns the length of the received packet.

This function is part of the low level protocol API.

mysql_next_result

mysql_next_result advances to the next result set from a multi-statement query, making it available for retrieval via mysql_store_result or mysql_use_result.

Syntax

int mysql_next_result(MYSQL * mysql);

Parameter

mysql - a mysql handle, which was previously allocated by mysql_init() or mysql_real_connect().

Description

Prepares next result set from a previous call to mysql_real_query() which can be retrieved by mysql_store_result() or mysql_use_result().

Return Value

Returns zero on success, nonzero if an error occurred.

If a multi query contains errors the return value of mysql_errno/error() might change and there will be no result set available.

mysql_num_fields

mysql_num_fields retrieves the column count from a result set handle, useful for iterating over fields in a MariaDB query result.

Syntax

unsigned int mysql_num_fields(MYSQL_RES * );

Parameter

MYSQL RES * - A result set identifier returned by mysql_store_result() or mysql_use_result().

Description

Returns number of fields in a specified result set.

Return Value

Returns number of fields.

mysql_num_rows

mysql_num_rows returns the number of rows in a MariaDB result set; for unbuffered results the count is only accurate after all rows have been fetched.

Syntax

my_ulonglong mysql_num_rows(MYSQL_RES * );

Parameter

MYSQL_RES - a result set identifier returned by mysql_store_result() or mysql_use_result().

Description

Returns number of rows in a result set.

The behavior of mysql_num_rows() depends on whether buffered or unbuffered result sets are being used. For unbuffered result sets, mysql_num_rows() will not return the correct number of rows until all the rows in the result have been retrieved.

mysql_options4

Syntax

Parameters

Parameter

Description

mysql

A connection handle previously allocated by mysql_init(). Must be called before mysql_real_connect().

option

The option to set.

arg1

The first value for the option.

arg2

The second value for the option.

Description

mysql_options4 is used to set extra connect options and affect behavior for a connection. This function may be called multiple times to set several options. It must be called after mysql_init() and before mysql_real_connect().

Return Value

Returns zero on success, non-zero if the option is unknown or the value is invalid.

Options

An overview of the possible options can be found in the description of the mysql_optionsv() API function.

This function is deprecated, new implementations should use mysql_optionsv() api function instead.

mysql_options

mysql_options sets extra connection options on a MYSQL handle before calling mysql_real_connect. Deprecated since Connector/C 3.0 — use mysql_optionsv instead.

Syntax

int mysql_options(MYSQL * mysql,
                  enum mysql_option,
                  const void * arg);

Parameters

mysql - a mysql handle, which was previously allocated by mysql_init() or mysql_real_connect().
mysql_option - the option you want to set. See description below.
arg - the value for the option.

Description

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().

Return Value

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.

Options

See mysql_optionsv.

mysql_ping

mysql_ping checks whether a MariaDB server connection is still active and attempts an automatic reconnect if the connection has dropped and reconnect is enabled.

Syntax

int mysql_ping(MYSQL * mysql);

Parameter

mysql - a mysql handle, which was previously allocated by mysql_init() or mysql_real_connect().

Description

Checks whether the connection to the server is working. If it has gone down, and global option reconnect is enabled an automatic reconnection is attempted.

This function can be used by clients that remain idle for a long while, to check whether the server has closed the connection and reconnect if necessary.

Return Value

Returns zero on success, nonzero if an error occurred.

If a reconnect occurred the thread_id will change. Also resources bundled to the connection (prepared statements, locks, temporary tables, ...) will be released.

mysql_query

mysql_query sends a null-terminated SQL string to the MariaDB server for execution, returning zero on success; use mysql_real_query for binary-safe operation.

Syntax

int mysql_query(MYSQL * mysql,
                const char * query);

Parameters

mysql - a mysql handle, which was previously allocated by mysql_init() or mysql_real_connect().
query -a null terminated string containing the statement to be performed.

Description

Performs a statement pointed to by the null terminate string query against the database. Contrary to mysql_real_query(), mysql_query() is not binary safe.

Return Value

Returns zero on success, non zero on failure

For executing multi statements the statements within the null terminated string statements must be separated by a semicolon.

If your statement contains binary data you should use mysql_real_query() or escape your data with mysql_hex_string().

To determine if a statement returned a result set use the function mysql_num_fields().

mysql_read_query_result

mysql_read_query_result reads the result of a statement previously sent with mysql_send_query, and must be called once for each successful mysql_send_query call.

Syntax

my_bool mysql_read_query_result(MYSQL * mysql);

Parameter

mysql - a mysql handle, which was previously allocated by mysql_init() or mysql_real_connect().

Description

mysql_read_query_result() reads the result of a SQL statement executed with mysql_send_query(). If the SQL statement returned a result set, it must be freed before the next call to mysql_read_query_result() is made. This is similar to how results from mysql_query() must be processed before another call can be made.

Return Value

Returns zero on success, otherwise non-zero.

Example

For an example how to use mysql_send_query() in an event driven model, please check Jan Kneschke's Blog entry "Async MySQL Queries with C-API".

mysql_real_connect

mysql_real_connect opens a connection to a MariaDB server and returns a MYSQL handle on success, or NULL if the connection could not be established.

Syntax

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);

Parameters

mysql - a mysql handle, which was previously allocated by mysql_init().
host - can be either a host name or an IP address. Passing the NULL value or the string "localhost" to this parameter, the local host is assumed. When possible, pipes will be used instead of the TCP/IP protocol.
user - the user name.
passwd - If provided or NULL, the server will attempt to authenticate the user against those user records which have no password only. This allows one username to be used with different permissions (depending on if a password as provided or not).
db - if provided will specify the default database to be used when performing queries.
port - specifies the port number to attempt to connect to the server.
unix_socket - specifies the socket or named pipe that should be used.
flags - the flags allows various connection options to be set:
- CLIENT_FOUND_ROWS: Return the number of matched rows instead of number of changed rows.
- CLIENT_NO_SCHEMA: Forbids the use of database.tablename.column syntax and forces the SQL parser to generate an error.
- CLIENT_COMPRESS: Use compression protocol
- CLIENT_IGNORE_SPACE: Allows spaces after function names. All function names will become reserved words.
- CLIENT_LOCAL_FILES: Allows LOAD DATA LOCAL statements
- CLIENT_MULTI_STATEMENTS: Allows the client to send multiple statements in one command. Statements will be divided by a semicolon.
- CLIENT_MULTI_RESULTS: Indicates that the client is able to handle multiple result sets from stored procedures or multi statements. This option will be automatically set if CLIENT_MULTI_STATEMENTS is set.
- And others per .

Description

Establishes a connection to a database server.

Return Value

Returns a connection handle (same as passed for 1st parameter) or NULL on error. On error, please check mysql_errno() and mysql_error() functions for more information.

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

mysql_real_escape_string encodes a string for safe use in a SQL statement, taking the connection's current character set into account when escaping special characters.

Syntax

unsigned long mysql_real_escape_string(MYSQL * mysql,
                                       char * to,
                                       const char * from,
                                       unsigned long);

Parameters

mysql - a MySQL handle, which was previously allocated by mysql_init() or mysql_real_connect().
to - buffer for the encoded string. The size of this buffer must be length * 2 + 1 bytes: in the worst case every character of the from string needs to be escaped. Additionally, a trailing 0 character will be appended.
from - a string which will be encoded by mysql_real_escape_string().
long - the length of the from string.

Description

This function is used to create a legal SQL string that you can use in an SQL statement. The given string is encoded to an escaped SQL string, taking into account the current character set of the connection.

Return Value

Returns the length of the encoded (to) string.

mysql_real_query

mysql_real_query sends a binary-safe SQL statement to a MariaDB server; use mysql_num_fields to determine whether the query returned a result set.

Syntax

int mysql_real_query(MYSQL * mysql,
                     const char * q,
                     unsigned long);

Parameters

mysql - a mysql handle, which was previously allocated by mysql_init() or mysql_real_connect().
query - a string containing the statement to be performed.
long - length of the string.

Description

mysql_real_query() is a binary-safe function for executing a statement on the database server.

Return Value

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.

mysql_refresh

mysql_refresh flushes server-side caches and state using a bitmask of options such as REFRESH_GRANT, REFRESH_LOG, REFRESH_TABLES, and REFRESH_HOSTS.

Syntax

int mysql_refresh(MYSQL * mysql,
  unsigned int options);

Parameters

mysql - a mysql handle, which was previously allocated by mysql_init() or mysql_real_connect().
options - a bit masked composed integer. See below.

Description

Flushes different types of information stored on the server. The bit-masked parameter options specify which kind of information will be flushed.

options can be any combination of the following:

Option

Description

REFRESH_GRANT

Refresh grant tables.

REFRESH_LOG

Flush logs.

REFRESH_TABLES

Flush table cache.

REFRESH_HOSTS

Flush host cache.

REFRESH_STATUS

Reset status variables.

REFRESH_THREADS

Flush thread cache.

REFRESH_SLAVE

Reset master server information and restart slaves.

REFRESH_MASTER

Remove binary log files.

Return Value

Returns zero on success, otherwise nonzero.

To combine different values in the options parameter, use the OR operator '|'.
The function mysql_reload() is an alias for mysql_refresh().

mysql_reset_connection

mysql_reset_connection resets session state on a MariaDB Connector/C connection — rolling back transactions and clearing variables — without disconnecting or reauthenticating.

Syntax

int mysql_reset_connection(MYSQL * mysql);

Parameter

mysql - a MySQL handle, which was previously allocated by mysql_init() or mysql_real_connect().

Description

Resets the current connection and clears session state. Similar to mysql_change_user() or mariadb_reconnect(), mysql_reset_connection() resets session status, but without disconnecting, opening, or reauthenticating.

On client side mysql_reset_connection()

clears pending or unprocessed result sets
clears status like affected_rows, info or last_insert_id
invalidates active prepared statements

On server side mysql_reset_connection()

drops temporary table(s)
rollbacks active transaction
resets auto commit mode
releases table locks
initializes session variables (and sets them to the value of corresponding global variables)
closes active prepared statements
clears user variables

Return Value

Returns zero on success, non-zero if an error occurred.

History

This function was added in MariaDB Connector/C 3.0.0.

mysql_rollback

mysql_rollback undoes the current transaction for a database connection; it has no effect if autocommit is enabled or the engine is non-transactional.

Syntax

my_bool mysql_rollback(MYSQL * mysql);

Parameter

mysql - a mysql handle, which was previously allocated by mysql_init() or mysql_real_connect().

Description

Rolls back the current transaction for the database.

Return Value

Returns zero on success, nonzero if an error occurred.

mysql_rollback() will not work as expected if mode was set or the storage engine does not support transactions.

mysql_row_seek

mysql_row_seek repositions the row cursor in a buffered MariaDB result set to an arbitrary offset, returning the previous row position as a MYSQL_ROW_OFFSET.

Syntax

MYSQL_ROW_OFFSET mysql_row_seek(MYSQL_RES * result,
    MYSQL_ROW_OFFSET offset);

Parameters

result - a result set identifier returned by mysql_store_result().
offset - row offset. This value can be obtained either by mysql_row_seek() or mysql_row_tell()

Description

Positions the row cursor to an arbitrary row in a result set which was obtained by mysql_store_result().

Return Value

Returns the previous row offset.

This function will not work if the result set was obtained by mysql_use_result().

mysql_row_tell

mysql_row_tell returns the current row cursor offset for a buffered MariaDB result set, which can then be passed to mysql_row_seek to restore that position.

Syntax

MYSQL_ROW_OFFSET mysql_row_tell(MYSQL_RES * res);

Parameter

res - a result set identifier returned by mysql_store_result().

Description

Returns the row offset of a result cursor. The returned offset value can be used to reposition the result cursor by calling mysql_row_seek().

This function will not work if the result set was obtained by mysql_use_result().

mysql_select_db

mysql_select_db changes the default database on an active connection; the current default can also be queried with the SELECT DATABASE() SQL function.

Syntax

int mysql_select_db(MYSQL * mysql,
                    const char * db);

Parameters

mysql - a mysql handle, which was previously allocated by mysql_init() or mysql_real_connect().
db - the default database name

Description

Selects a database as default.

Return Value

Returns zero on success, non-zero on failure.

To retrieve the name of the default database either execute the SQL command SELECT DATABASE() or retrieve the value via mariadb_get_infov() API function.

The default database can also be set by the db parameter in mysql_real_connect().

Examples

SQL

# switch to default database test
USE test;
# check default database
SELECT DATABASE();
+------------+
| database() |
+------------+
| test       |
+------------+

MariadDB Connector/C

static int set_default_db(MYSQL *mysql)
{
  int rc;
  char *default_db;

  /* change default database to test */
  rc= mysql_select_db(mysql, "test");
  if (rc)
    return rc;  /* Error */

  /* get the default database */
  rc= mariadb_get_infov(mysql, MARIADB_CONNECTION_SCHEMA, &default_db);
  if (rc)
    return rc; /* Error */

  if (strcmp("test", default_db) != NULL)
  {
    printf("Wrong default database\n");
    return 1;
  }
  printf("Default database: %s", default_db);
  return 0;
}

mysql_send_query

mysql_send_query dispatches a query asynchronously on a MariaDB connection; each call must be followed by mysql_read_query_result to consume the response.

Syntax

int mysql_send_query(MYSQL * mysql,
                     const char * query,
                     unsigned long length);

Parameters

mysql - a mysql handle, which was previously allocated by mysql_init() or mysql_real_connect().
query - the query to execute.
length - length of query.

Returns zero on success, otherwise non-zero.

Description

mysql_send_query() executes a SQL statement without waiting for the Server OK packet and/or resultset. The main purpose of this function is to perform batch execution of DML statements.

The OK and result set package need to be retrieved by mysql_read_query_result() function
mysql_send_query() can be used for semi asynchronous operation. While the function itself is blocking, an event driven application can do other tasks until result set is available.

Example

For an example how to use 'mysql_send_query()` in an event driven model, please check Jan Kneschke's article "Async MySQL Queries with C-API".

mysql_server_end

mysql_server_end is an alias for mysql_library_end in MariaDB Connector/C, used to finalize and clean up the client library.

Syntax

void mysql_server_end(void );

Description

mysql_server_end() is an alias for mysql_library_end().

mysql_server_init

mysql_server_init is an alias for mysql_library_init in MariaDB Connector/C, used to initialize the client library before making any other calls.

Syntax

int mysql_server_init(int argc, char **argv, char **groups);

Description

Call to initialize the library before calling other functions. mysql_server_init() is an alias for mysql_library_init().

mysql_session_track_get_first

mysql_session_track_get_first retrieves the first session state change notification from the server, covering schema changes, system variables, and state flags. Added in Connector/C 3.0.

Syntax

int mysql_session_track_get_first(MYSQL * mysql,enum enum_session_state_type type, const char **data, size_t *length );

Parameters

mysql - mysql handle, which was previously allocated by mysql_init() or mysql_real_connect().
type - type of information. Valid values are
- SESSION_TRACK_SYSTEM_VARIABLES
- SESSION_TRACK_SCHEMA
- SESSION_TRACK_STATE_CHANGE
- SESSION_TRACK_GTIDS (unsupported)
data - pointer to data, which must be declared as const char *
length - pointer to a size_t variable, which will contain the length of data

Description

mysql_session_track_get_first() retrieves the first session status change information received from the server.

Depending on the specified type the read only data pointer will contain the following information:

SESSION_TRACK_SCHEMA: The name of the default schema (database)
SESSION_TRACK_SYSTEM_VARIABLES: If a session system variable is changed, the first call contains the name of the changed system variable, the second call contains the new value. Both name and value are represented as strings.
SESSION_TRACK_STATE_CHANGE: shows whether the session status has changed. The value is changed as string "1" (changed) or "0" (unchanged).

Further data needs to be obtained by calling mysql_session_track_get_next().

Returns

Zero for success, nonzero if an error occurred.

History

mysql_session_track_get_first() was added in Connector/C 3.0 and MariaDB Server 10.2.

mysql_session_track_get_next

mysql_session_track_get_next retrieves subsequent session state change notifications after mysql_session_track_get_first, called repeatedly until a nonzero value signals end of data.

Syntax

int mysql_session_track_get_next(MYSQL * mysql,enum enum_session_state_type type, const char **data, size_t *length );

Parameters

mysql - mysql handle, which was previously allocated by mysql_init() or mysql_real_connect().
type - type of information. Valid values are
- SESSION_TRACK_SYSTEM_VARIABLES
- SESSION_TRACK_SCHEMA
- SESSION_TRACK_STATE_CHANGE
- SESSION_TRACK_GTIDS (unsupported)
data - pointer to data, which must be declared as const char *
length - pointer to a size_t variable, which will contain the length of data

Description

mysql_session_track_get_next() retrieves the session status change information received from the server after a successful call to mysql_session_track_get_first().

mysql_session_track_get_next() needs to be called repeatedly until a non-zero return value indicates the end of data.

Return Value

Zero for success, nonzero if an error occurred.

History

mysql_session_track_get_next() was added in Connector/C 3.0 and MariaDB Server 10.2.

mysql_set_character_set

mysql_set_character_set sets the default character set for a MariaDB Connector/C connection, ensuring mysql_real_escape_string uses the correct encoding.

mysql - a mysql handle, which was previously allocated by or .
csname - character set name

Sets the default for the current connection.

mysql_set_server_option

mysql_set_server_option enables or disables multi-statement support on a MariaDB connection using MYSQL_OPTION_MULTI_STATEMENTS_ON or _OFF.

Syntax

int mysql_set_server_option(MYSQL * mysql,
  enum enum_mysql_set_option);

Parameters

mysql - a mysql handle, which was previously allocated by mysql_init() or mysql_real_connect().
enum_mysql_set_option - server option (see below)

Description

Server option, which can be one of the following values:

Option

Description

MYSQL_OPTION_MULTI_STATEMENTS_OFF

Disables multi statement support

MYSQL_OPTION_MULTI_STATEMENTS_ON

Enable multi statement support

Return Value

Returns zero on success, non-zero on failure.

mysql_set_local_infile_handler

mysql_set_local_infile_handler registers custom callback functions for init, read, end, and error phases of a LOAD DATA LOCAL INFILE operation in MariaDB Connector/C.

Name

mysql_set_local_infile_handler - Registers callback functions for LOAD DATA LOCAL INFILE

Syntax

Description

Registers four callback functions which will be called if a LOAD DATA LOCAL INFILE command will be executed.

The initialization function accepts 3 parameters and returns zero on success, nonzero on error. It allocates an handle, which will be passed to read, end and error functions:

int init(void **handle, const char *filename, void *userdata)

The read function is called repeatedly to read data chunks from file into buffer. The amount of bytes is limited by parameer buffer_len. The function returns the number of bytes which were read from the file:

int mysql_local_infile_read(void *handle, char * buffer, unsigned int buffer_len)

The end function will be called after the read function returned zero (no more bytes to read). To prevent leaking of resources, the file must be closed and handle must be freed inside this function:

void end(void *handle);

The error function is called to get an error message in case init, read or end functions returned an error.

error(void *handler, char *error_buf, unsigned int error_buf_len);

Parameters

mysql - mysql handle, which was previously allocated by mysql_init()
local_infile_init - initialization function, e.g. for opening the file
local_infile_read - read function
local_infile_end - terminating function, e.g. for closing the file
local_infile_error - error function
userdata - a buffer which will be passed to all callback function

mysql_set_local_infile_default

mysql_set_local_infile_default resets local infile callbacks to the Connector/C internal defaults, reversing any custom handler registered via mysql_set_local_infile_handler.

Name

mysql_set_local_infile_default - Sets local infile callback functions to default

Syntax

Parameter

mysql - mysql handle, which was previously allocated by mysql_init().

Description

Sets local infile callback functions to MariaDB Connector/C internal default callback functions.

mysql_shutdown

mysql_shutdown sends a shutdown request to the MariaDB server over the current connection, requiring the SHUTDOWN privilege for the authenticated user.

Syntax

int mysql_shutdown(MYSQL * mysql,
  enum mysql_enum_shutdown_level);

Parameters

mysql - a mysql handle, which was previously allocated by mysql_init() or mysql_real_connect().
mysql_enum_shutdown_level - currently only one shutdown level, SHUTDOWN_DEFAULT is supported.

Description

Sends a shutdown message to the server. To shut down the database server, the user for the current connection must have SHUTDOWN privileges.

Return Value

Returns zero on success, non-zero on failure.

mysql_sqlstate

mysql_sqlstate returns the five-character SQLSTATE error code for the most recent MariaDB Connector/C function call, with 00000 indicating success.

Syntax

const char * mysql_sqlstate(MYSQL * mysql);

Parameter

mysql - a mysql handle, which was previously allocated by mysql_init() or mysql_real_connect().

Description

Returns a string containing the error code for the most recently invoked function that can succeed or fail. The error code consists of five characters. '00000' means no error. The values are specified by ANSI SQL and ODBC.

Please note that not all client library error codes are mapped to SQLSTATE errors. Errors which can't be mapped will be returned as value HY000.

mysql_ssl_set

mysql_ssl_set configures TLS parameters including key, certificate, CA, and cipher list for a MariaDB connection, and must be called before mysql_real_connect.

Syntax

int mysql_ssl_set(MYSQL *mysql, const char *key, const char *cert,
  const char *ca, const char *capath, const char *cipher)

Parameters

mysql - a mysql handle, which was previously allocated by mysql_init() or mysql_real_connect().
key - path to the key file.
cert - path to the certificate file.
ca - path to the certificate authority file.
capath - path to the directory containing the trusted TLS CA certificates in PEM format.
cipher list of permitted ciphers to use for TLS encryption.

Description

Used for establishing a . It must be called before attempting to use mysql_real_connect(). TLS support must be enabled in the client library in order for the function to have any effect.

NULL can be used for an unused parameter. Always returns zero.

To enable TLS without specifying certificates, set all values to NULL:

mysql_ssl_set(mysql, NULL, NULL, NULL, NULL, NULL)

This is the same as mysql_optionsv(mysql, MYSQL_OPT_SSL_ENFORCE, &yes).

mysql_real_connect() will return an error if attempting to connect and TLS is incorrectly set up.
Even if Connector/C supports TLSv1.3 protocol, it is not possible yet to specify TLSv1.3 cipher suites via cipher parameter.

mysql_stat

mysql_stat returns a status string from the MariaDB server covering uptime, active threads, query count, open tables, and queries per second.

Syntax

char * mysql_stat(MYSQL * mysql);

Parameter

mysql - a mysql handle, which was previously allocated by mysql_init() or mysql_real_connect().

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 SQL command.

mysql_store_result

mysql_store_result retrieves a complete buffered result set from the last executed MariaDB query, returning NULL on error or for non-SELECT statements.

Syntax

MYSQL_RES * mysql_store_result(MYSQL * mysql);

Parameter

mysql - a mysql handle, which was previously allocated by mysql_init() or mysql_real_connect().

Description

Returns a buffered result set from the last executed query.

Return Value

Returns a buffered result set or NULL in case an error occurred or if the query didn't return data (e.g. when executing an INSERT, UPDATE, DELETE or REPLACE statement).

mysql_store_result() returns NULL in case an error occurred or if the query didn't return data (e.g. when executing an or query.

mysql_field_count() indicates if there will be a result set available.

The memory allocated by mysql_store_result() needs to be released by calling the function mysql_free_result().

mysql_thread_end

mysql_thread_end releases thread-local memory allocated by mysql_thread_init and must be called explicitly before a thread exits to avoid memory leaks. Deprecated in Connector/C 3.0.

Syntax

void mysql_thread_end(void );

Description

The mysql_thread_end() function is now an empty no-op, retained only for API/ABI compatibility.

Return Value

Returns void.

Unlike mysql_thread_init() mysql_thread_end() will not be invoked automatically if the thread ends. To avoid memory leaks mysql_thread_end() must be called explicitly.

This function has been deprecated since MariaDB Connector/C 3.0.0.

mysql_thread_id

mysql_thread_id retrieves the thread identifier for an active connection; the value may change after a reconnect if the reconnect option is enabled.

Syntax

unsigned long mysql_thread_id(MYSQL * mysql);

Parameter

mysql - a mysql handle, which was previously allocated by mysql_init() or mysql_real_connect().

Description

The mysql_thread_id() function returns the thread id for the current connection.

The current connection can be killed with mysql_kill(). If reconnect option is enabled the thread id might change if the client reconnects to the server.

mysql_thread_init

mysql_thread_init initializes thread-local variables for multi-threaded Connector/C clients; called automatically by mysql_init if not invoked explicitly. Deprecated in Connector/C 3.0.

Syntax

my_bool mysql_thread_init(void );

Description

Thread initialization for multi-threaded clients. mysql_thread_init() is now an empty no-op; it is not called automatically by mysql_init() or mysql_real_connect().

Return Value

Always returns 0 (no-op).

Before a client thread ends the mysql_thread_end() function must be called to release memory - otherwise the client library will report an error.

This function has been deprecated since MariaDB Connector/C 3.0.0.

mysql_thread_safe

mysql_thread_safe returns 1 if the MariaDB Connector/C client library was compiled with thread-safety support, or zero otherwise.

Syntax

unsigned int mysql_thread_safe(void );

Description

Indicates whether or not the client library is compiled as thread safe. Returns 1 if the client library was compiled as thread safe otherwise zero.

Return Value

Returns always 1.

This function exists for compatibility reasons and returns always 1.

mysql_use_result

mysql_use_result initiates unbuffered retrieval of a query result set row by row from the MariaDB server, blocking the connection until all rows are fetched or freed.

Syntax

MYSQL_RES * mysql_use_result(MYSQL * mysql);

Parameter

mysql - a mysql handle, which was previously allocated by mysql_init() or mysql_real_connect().

Description

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.

Return Value

Returns an unbuffered result set or NULL if an error occurred.

The mysql_use_result() function does not transfer the entire result set. Hence, several functions like mysql_num_rows() or mysql_data_seek() cannot be used.

mysql_use_result() will block the current connection until all result sets are retrieved, or result set was released by mysql_free_result().

mysql_warning_count

mysql_warning_count retrieves the warning count from the most recent query execution; use SHOW WARNINGS for the full warning message text.

Syntax

unsigned int mysql_warning_count(MYSQL * mysql);

Parameter

mysql - a mysql handle, which was previously allocated by mysql_init() or mysql_real_connect().

Description

Returns the number of warnings from the last executed query, or zero if there are no warnings.

For retrieving warning messages you should use the SQL command . If TRADITIONAL is enabled an error instead of warning will be returned. For detailed information check the server documentation.

mariadb_cancel

Syntax

Parameter

Description

Return Value

History

mariadb_connect

Syntax

Parameter

Return Value

Note

Example

History

mariadb_connection

Syntax

Parameter

Description

Return Value

mariadb_convert_string

Syntax

Description

mariadb_field_attr

Syntax

Parameter

Description

Return Value

Notes

Example

History

See Also

mariadb_get_info

Syntax

Description

See Also

mariadb_get_infov

Syntax

Parameter

Description

Value types

Generic information

Connection related information

Return Value

History

Examples

See Also

mariadb_reconnect

Syntax

Parameter

Description

Return Value

History

See Also

mysql_affected_rows

Syntax

Parameter

Description

Return Value

See Also

mysql_autocommit

Syntax

Parameters

Description

Return Value

Examples

SQL

MariaDB Connector/C

mysql_change_user

Syntax

Description

Return Value

See Also

mysql_character_set_name

Syntax

Parameter

Description

Return value

See Also

mysql_client_find_plugin

Syntax

Parameters