Chapter 141. MySQL C API

Table of Contents

C API Datatypes
C API Function Overview
C API Function Descriptions
Description
Return Values
Errors
Example
Description
Return Values
Errors
Example
Description
Return Values
Errors
Description
Return Values
Errors
Description
Return Values
Errors
Description
Return Values
Errors
Example
Description
Return Values
Errors
Description
Return Values
Errors
Example
Description
Return Values
Errors
Example
Description
Return Values
Errors
Description
Return Values
Errors
Example
Description
Return Values
Errors
Description
Return Values
Errors
Description
Return Values
Errors
Example
Description
Return Values
Errors
Example
Description
Return Values
Errors
Example
Description
Return Values
Errors
Example
Description
Return Values
Errors
Example
Description
Return Values
Errors
Example
Description
Return Values
Errors
Description
Return Values
Errors
Description
Return Values
Errors
Description
Return Values
Errors
Description
Return Values
Errors
Description
Return Values
Errors
Description
Return Values
Errors
Description
Return Values
Errors
Description
Return Values
Errors
Description
Return Values
Errors
Description
Return Values
Errors
Description
Return Values
Errors
Description
Return Values
Errors
Description
Return Values
Errors
Description
Return Values
Errors
Description
Return Values
Errors
Description
Return Values
Errors
Description
Return Values
Errors
Example
Description
Return Values
Errors
Description
Return Values
Example
Description
Return Values
Errors
Description
Return Values
Errors
Description
Return Values
Errors
Example
Description
Example
Return Values
Errors
Description
Return Values
Errors
Description
Return Values
Errors
Description
Return Values
Errors
Description
Return Values
Errors
Description
Return Values
Errors
Description
Return Values
Errors
Description
Return Values
Errors
Description
Return Values
See Also
Description
Return Values
Description
Return Values
Errors
Description
Return Values
Errors
Description
Return Values
Errors
Description
Return Values
Errors
Description
Return Values
Errors
Description
Return Values
Errors
Description
Return Values
Errors
Description
Return Values
Errors
Description
Return Values
Errors
Description
Return Values
Errors
mysql_affected_rows()
mysql_change_user()
mysql_character_set_name()
mysql_close()
mysql_connect()
mysql_create_db()
mysql_data_seek()
mysql_debug()
mysql_drop_db()
mysql_dump_debug_info()
mysql_eof()
mysql_errno()
mysql_error()
mysql_escape_string()
mysql_fetch_field()
mysql_fetch_fields()
mysql_fetch_field_direct()
mysql_fetch_lengths()
mysql_fetch_row()
mysql_field_count()
mysql_field_seek()
mysql_field_tell()
mysql_free_result()
mysql_get_client_info()
mysql_get_client_version()
mysql_get_host_info()
mysql_get_proto_info()
mysql_get_server_info()
mysql_get_server_version()
mysql_info()
mysql_init()
mysql_insert_id()
mysql_kill()
mysql_list_dbs()
mysql_list_fields()
mysql_list_processes()
mysql_list_tables()
mysql_num_fields()
mysql_num_rows()
mysql_options()
mysql_ping()
mysql_query()
mysql_real_connect()
mysql_real_escape_string()
mysql_real_query()
mysql_reload()
mysql_row_seek()
mysql_row_tell()
mysql_select_db()
mysql_set_server_option()
mysql_shutdown()
mysql_sqlstate()
mysql_ssl_set()
mysql_stat()
mysql_store_result()
mysql_thread_id()
mysql_use_result()
mysql_warning_count()
mysql_commit()
mysql_rollback()
mysql_autocommit()
mysql_more_results()
mysql_next_result()
C API Prepared Statements
C API Prepared Statement Datatypes
C API Prepared Statement Function Overview
Execution Steps
C API Prepared Statement Function Descriptions
Description
Return Values
Errors
Example
Description
Return Values
Errors
Example
Description
Return Values
Errors
Example
Description
Return Values
Errors
Example
Description
Return Values
Errors
Description
Return Values
Errors
Example
Description
Return Values
Errors
Example
Description
Return Values
Errors
Description
Return Values
Errors
Example
Description
Return Values
Errors
Example
Description
Return Values
Errors
Example
Description
Return Values
Errors
Example
Description
Return Values
Errors
Description
Return Values
Errors
Description
Return Values
Errors
Description
Return Values
Errors
Description
Return Values
Errors
Description
Return Values
Errors
Description
Return Values
Errors
Description
Return Values
Errors
Description
Return Values
Description
Return Values
Errors
mysql_bind_param()
mysql_bind_result()
mysql_execute()
mysql_fetch()
mysql_fetch_column()
mysql_get_metadata()
mysql_param_count()
mysql_param_result()
mysql_prepare()
mysql_send_long_data()
mysql_stmt_affected_rows()
mysql_stmt_close()
mysql_stmt_data_seek()
mysql_stmt_errno()
mysql_stmt_error()
mysql_stmt_free_result()
mysql_stmt_num_rows()
mysql_stmt_reset()
mysql_stmt_row_seek()
mysql_stmt_row_tell()
mysql_stmt_sqlstate()
mysql_stmt_store_result()
C API Handling of Multiple Query Execution
C API Handling of Date and Time Values
C API Threaded Function Descriptions
Description
Return Values
Description
Return Values
Description
Return Values
Description
Return Values
my_init()
mysql_thread_init()
mysql_thread_end()
mysql_thread_safe()
C API Embedded Server Function Descriptions
Description
Example
Return Values
Description
Return Values
mysql_server_init()
mysql_server_end()
Common questions and problems when using the C API
Why mysql_store_result() Sometimes Returns NULL After mysql_query() Returns Success
What Results You Can Get from a Query
How to Get the Unique ID for the Last Inserted Row
Problems Linking with the C API
Building Client Programs
How to Make a Threaded Client
libmysqld, the Embedded MySQL Server Library
Overview of the Embedded MySQL Server Library
Compiling Programs with libmysqld
Restrictions when using the Embedded MySQL Server
Using Option Files with the Embedded Server
Things left to do in Embedded Server (TODO)
A Simple Embedded Server Example
Licensing the Embedded Server

The C API code is distributed with MySQL. It is included in the mysqlclient library and allows C programs to access a database.

Many of the clients in the MySQL source distribution are written in C. If you are looking for examples that demonstrate how to use the C API, take a look at these clients. You can find these in the clients directory in the MySQL source distribution.

Most of the other client APIs (all except Connector/J) use the mysqlclient library to communicate with the MySQL server. This means that, for example, you can take advantage of many of the same environment variables that are used by other client programs, because they are referenced from the library. See Client-Side Scripts, for a list of these variables.

The client has a maximum communication buffer size. The size of the buffer that is allocated initially (16K bytes) is automatically increased up to the maximum size (the maximum is 16M). Because buffer sizes are increased only as demand warrants, simply increasing the default maximum limit does not in itself cause more resources to be used. This size check is mostly a check for erroneous queries and communication packets.

The communication buffer must be large enough to contain a single SQL statement (for client-to-server traffic) and one row of returned data (for server-to-client traffic). Each thread's communication buffer is dynamically enlarged to handle any query or row up to the maximum limit. For example, if you have BLOB values that contain up to 16M of data, you must have a communication buffer limit of at least 16M (in both server and client). The client's default maximum is 16M, but the default maximum in the server is 1M. You can increase this by changing the value of the max_allowed_packet parameter when the server is started. See Server parameters.

The MySQL server shrinks each communication buffer to net_buffer_length bytes after each query. For clients, the size of the buffer associated with a connection is not decreased until the connection is closed, at which time client memory is reclaimed.

For programming with threads, see Threaded clients. For creating a stand-alone application which includes the "server" and "client" in the same program (and does not communicate with an external MySQL server), see libmysqld.

C API Datatypes

MYSQL This structure represents a handle to one database connection. It is used for almost all MySQL functions.
MYSQL_RES This structure represents the result of a query that returns rows (SELECT, SHOW, DESCRIBE, EXPLAIN). The information returned from a query is called the result set in the remainder of this section.
MYSQL_ROW This is a type-safe representation of one row of data. It is currently implemented as an array of counted byte strings. (You cannot treat these as null-terminated strings if field values may contain binary data, because such values may contain null bytes internally.) Rows are obtained by calling mysql_fetch_row().
MYSQL_FIELD This structure contains information about a field, such as the field's name, type, and size. Its members are described in more detail here. You may obtain the MYSQL_FIELD structures for each field by calling mysql_fetch_field() repeatedly. Field values are not part of this structure; they are contained in a MYSQL_ROW structure.
MYSQL_FIELD_OFFSET This is a type-safe representation of an offset into a MySQL field list. (Used by mysql_field_seek().) Offsets are field numbers within a row, beginning at zero.
my_ulonglong The type used for the number of rows and for mysql_affected_rows(), mysql_num_rows(), and mysql_insert_id(). This type provides a range of 0 to 1.84e19. On some systems, attempting to print a value of type my_ulonglong will not work. To print such a value, convert it to unsigned long and use a %lu print format. Example:
    printf ("Number of rows: %lu\n", (unsigned long) mysql_num_rows(result));
    

The MYSQL_FIELD structure contains the members listed here:

char * name The name of the field, as a null-terminated string.
char * table The name of the table containing this field, if it isn't a calculated field. For calculated fields, the table value is an empty string.
char * def The default value of this field, as a null-terminated string. This is set only if you use mysql_list_fields().
enum enum_field_types type The type of the field. The type value may be one of the following:
Type valueType description
FIELD_TYPE_TINYTINYINT field
FIELD_TYPE_SHORTSMALLINT field
FIELD_TYPE_LONGINTEGER field
FIELD_TYPE_INT24MEDIUMINT field
FIELD_TYPE_LONGLONGBIGINT field
FIELD_TYPE_DECIMALDECIMAL or NUMERIC field
FIELD_TYPE_FLOATFLOAT field
FIELD_TYPE_DOUBLEDOUBLE or REAL field
FIELD_TYPE_TIMESTAMPTIMESTAMP field
FIELD_TYPE_DATEDATE field
FIELD_TYPE_TIMETIME field
FIELD_TYPE_DATETIMEDATETIME field
FIELD_TYPE_YEARYEAR field
FIELD_TYPE_STRINGCHAR field
FIELD_TYPE_VAR_STRINGVARCHAR field
FIELD_TYPE_BLOBBLOB or TEXT field (use max_length to determine the maximum length)
FIELD_TYPE_SETSET field
FIELD_TYPE_ENUMENUM field
FIELD_TYPE_NULLNULL-type field
FIELD_TYPE_CHARDeprecated; use FIELD_TYPE_TINY instead
unsigned int length The width of the field, as specified in the table definition.  
unsigned int max_length The maximum width of the field for the result set (the length of the longest field value for the rows actually in the result set). If you use mysql_store_result() or mysql_list_fields(), this contains the maximum length for the field. If you use mysql_use_result(), the value of this variable is zero.  
unsigned int flags Different bit-flags for the field. The flags value may have zero or more of the following bits set:
Flag valueFlag description
NOT_NULL_FLAGField can't be NULL
PRI_KEY_FLAGField is part of a primary key
UNIQUE_KEY_FLAGField is part of a unique key
MULTIPLE_KEY_FLAGField is part of a non-unique key
UNSIGNED_FLAGField has the UNSIGNED attribute
ZEROFILL_FLAGField has the ZEROFILL attribute
BINARY_FLAGField has the BINARY attribute
AUTO_INCREMENT_FLAGField has the AUTO_INCREMENT attribute
ENUM_FLAGField is an ENUM (deprecated)
SET_FLAGField is a SET (deprecated)
BLOB_FLAGField is a BLOB or TEXT (deprecated)
TIMESTAMP_FLAGField is a TIMESTAMP (deprecated)
Flag statusDescription
IS_NOT_NULL(flags)True if this field is defined as NOT NULL
IS_PRI_KEY(flags)True if this field is a primary key
IS_BLOB(flags)True if this field is a BLOB or TEXT (deprecated; test field->type instead)
unsigned int decimals The number of decimals for numeric fields.