Table of Contents
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.
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: |
| ||||||||||||||||||||||||||||||||||||||||||
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: |
|
| |||||||||||||||||||||||||||||||||||||||||
unsigned int decimals | The number of decimals for numeric fields. |