Detailed explanation of MySQL interface in C language

Introduce a MySQL interface to C language

mysql_character_set_name()

const char* mysql_character_set_name(MYSQL* mysql)
Returns the default charset for the current connection
Return value: the default character set

mysql_close()

void mysql_close(MYSQL* mysql)
Description: Close the previously opened connection, if the handle was automatically allocated by mysql_init() or mysql_connect(), mysql_close() will also deallocate the connection handle pointed to by mysql.

mysql_data_seek()

void mysql_data_seek(MYSQL_RES* result, my_ulonglong offset)
Find any row in the query result set. The offset value is the row number, ranging from 0 to mysql_num_rows(result) -1 .
This function requires that the result set structure contains all the results of the query. As a result, mysql_data_seek() should only be used in conjunction with mysql_store_result(), not mysql_use_result().

mysql_errno()

unsigned int mysql_errno(MYSQL* mysql)
For the connection specified by mysql, mysql_errno() returns the error code of the most recently called API function, which may or may not have succeeded.
A return value of "0" indicates that no error occurred.
On failure, returns the error code of the last mysql_xxx() call.

mysql_error()

const char* mysql_error(MYSQL* mysql)
For the connection specified by mysql, mysql_error() returns a NULL-terminated string containing the error message for the most recently called API function that failed.
If the function does not fail, the return value of mysql_error() may be the previous error, or an empty string indicating no error.

mysql_fetch_field()

MYSQL_FIELD* mysql_fetch_field(MYSQL_RES* result)
Returns the columns of the result set in the MYSQL_FIELD structure. Call this function repeatedly to retrieve information about all columns in the result set. When no fields remain, mysql_fetch_field() returns NULL.
Each time a new SELECT query is executed, mysql_fetch_field() is reset to return information about the first field.
Calls to mysql_field_seek() also affect the fields returned by mysql_fetch_field().
MYSQL_FIELD structure for the current column. Returns NULL if no columns remain.
Note: If mysql_query() is called to perform a SELECT on a table, but mysql_store_result() is not called, if mysql_fetch_field() is called to request the length of a BLOB field, MYSQL will return the default blob length (8KB).

MYSQL_FIELD* field;
while(field = mysql_fetch_field(result))
printf("field name %s
",field->name); //Print out the field name of each column

mysql_fetch_fields()

MYSQL_FIELD* mysql_fetch_fields(MYSQL_RES* result)
For a result set, returns an array of all MYSQL_FIELD structures. Each structure provides field definitions for 1 column in the result set

Return value: An array of MYSQL_FIELD structures for all columns in the result set.

unsigned int num_fields;
unsigned int i;
MYSQL_FIELD* fields;

num_fields = mysql_num_fields(res);
fields = mysql_fetch_field(res);
for (i = 0; i < num_fields; ++i)
	printf("Field %u is %s

", i, fields[i].name);

mysql_fetch_lengths()

unsigned long* mysql_fetch_lengths(MYSQL_RES* result )
Returns the length of the columns of the current row of the result set.
If the result set contains binary data, this function must be used to determine the size of the data because strlen() will return incorrect results for any field that contains NULL characters.

Return Value: Array of unsigned long integers representing the size of each column (without any terminating NULL characters). If there is an error, return NULL

MYSQL_ROW row;
unsigned long *lengths;
unsigned int num_fields;
unsigned int i;

mysql_data_seek(res, 1);

row = mysql_fetch_row(res);
if (row)
{
	num_fields = mysql_num_fields(res);
	lengths = mysql_fetch_lengths(res);

	for (i = 0; i < num_fields; ++i)
		printf("Column %u is %lu bytes in length.

", i, lengths[i]);
}

mysql_fetch_row()

MYSQL_ROW mysql_fetch_row(MYSQL_RES* result)
Retrieves the next row of the result set. When used after mysql_store_result(), mysql_fetch_row() returns NULL if there are no rows to retrieve
The number of inline values is given by mysql_num_fields(result). If the row holds values returned by a call to mysql_fetch_row(), pointers to those values are accessed as row[0] through row[mysql_num_fields(result)-1]. A NULL value in a row is indicated by a NULL pointer.
The lengths of field values in a row can be obtained by calling mysql_fetch_lengths(). For empty fields and fields containing NULL, the length is 0. By examining the pointer to the field value, they can be distinguished. If the pointer is NULL, the field is NULL, otherwise the field is empty.
Return value: MYSQL_ROW structure for the next row, or NULL if there are no more rows to retrieve or an error occurred.

MYSQL_ROW row;
unsigned int num_fields;
unsigned int i;

num_fields = mysql_num_fields(result);
while(row = mysql_fetch_row(result))
{ unsigned long * lengths; lengths = mysql_fetch_lengths(result); for(i = 0;i < num_fields; ++i) printf("[%.*s] “,(int)lengths[i], row[i] ? row[i] : “NULL”); printf(” "); }

mysql_field_count()

unsigned int mysql_field_count(MYSQL* mysql)
Returns the number of columns of the most recent query acting on the join
The normal use of this function is when mysql_store_result() returns NULL (and thus no result set pointer). In this case, mysql_field_count() can be called to determine whether mysql_store_result() should produce a non-null result. This way the client can take the appropriate action without knowing whether the query is a SELECT (or SELECT-like) statement.

mysql_field_seek()

MYSQL_FIELD_OFFSET mysql_field_seek(MYSQL_RES* result, MYSQL_FIELD_OFFSET offset)
Set the field cursor to the given offset. The next call to mysql_fetch_field() will retrieve the column definition associated with that offset.
To find the start of the line, pass an offset of 0.
Return value: The previous value of the field cursor.

mysql_field_tell()

MYSQL_FIELD_OFFSET mysql_field_tell(MYSQL_RES* result)
Returns the current offset of the cursor

mysql_free_result()

Frees the memory allocated for the result set. After completing the operation on the result set, you must call mysql_free_result() to free the memory used by the result set.
Do not try to access the result set after the release is complete

mysql_get_character_set_info()

void mysql_get_character_set_info(MYSQL* mysql, MY_CHARSET_INFO* cs)
This function provides information about the default client character set. The default character set can be changed using the mysql_set_character_set() function.

mysql_init()

MYSQL* mysql_init(MYSQL* mysql)
Allocate or initialize a MYSQL object appropriate for mysql_real_connect(). If mysql is a NULL pointer, this function will allocate, initialize, and return the new object. Otherwise, the object is initialized and the address of the object is returned.
If mysql_init() allocated a new object, when mysql_close() is called to close the connection. The object will be released.
Return value: The initialized MYSQL* handle. Returns NULL if there is not enough memory to allocate the new object.

mysql_list_dbs()

MYSQL_RES* mysql_list_dbs(MYSQL_mysql,const char_ wild)
Returns a result set consisting of database names on a server that matches a simple regular expression specified by a wildcard parameter. Wildcard parameters can contain "%" or "_", or can be NULL for all databases to match.
The method of calling mysql_list_dbs() is similar to executing a query SHOW databases
The result set must be freed with mysql_free_result()
Return value: return MYSQL_RES result set after success. Returns NULL if there is an error.

mysql_list_fields()

MYSQL_RES* mysql_list_fields(MYSQL* mysql,const char* table,const char* wild)
Returns a result set consisting of field names from the given table that matches the simple regular expression specified by the wildcard argument. Wildcard parameters can contain wildcards "%" or "_", or a NULL pointer to match all fields.
Calling the mysql_list_fields() method is similar to executing the query SHOW COLUMNS FROM tal_name.
Return value: If successful, return the MYSQL_RES result set. Returns NULL if there is an error.

mysql_list_tables()

MYSQL_RES* mysql_list_tables(MYSQL_mysql,const char_ wild)
Return value: Returns a result set consisting of table names in the current database that matches the simple regular expression specified by the wildcard parameter. Wildcard arguments can contain wildcards "%" or "_", or a NULL pointer to match against all other tables.
The method of calling mysql_list_tables() is similar to executing the query SHOW tables;
Return value: If successful, return the MYSQL_RES result set. Returns NULL if there is an error.

mysql_num_rows()

my_ulonglong mysql_num_rows(MYSQL_RES* result)
Returns the number of rows in the result set
If mysql_store_result() is used, mysql_num_rows() can be called immediately.
If mysql_use_result() is used, mysql_num_rows() does not return the correct value until all rows in the result set have been retrieved.
Return value: The number of rows in the result set.

mysql_options()

int mysql_options(MYSQL* mysql,enum mysql_option option,const char* arg)
Can be used to set additional connection options and affect the behavior of the connection. This function can be called multiple times to set several options.
mysql_options() should be called after mysql_init() and before mysql_connect() or mysql_real_connect()
The option parameter refers to the option you intend to set, and the Arg parameter is the value of the option. If the option is an integer, then arg should point to the value of the integer.
I do not list the possible option values here, you can Baidu by yourself.
Return value: 0 on success, non-zero if unknown options are used.

mysql_ping()

int mysql_ping(MYSQL*mysql)
Check that the connection to the server is working. If work is lost, reconnection will be automatically attempted.
This function can be used by clients that have been idle for a long time to check if the server has closed the connection and connect again if necessary.
Return Value: Returns 0 if the connection to the server is valid, non-zero if there is an error. The returned non-zero value does not indicate whether the MYSQL server has been closed, and the connection may be terminated for other reasons, such as network problems.

mysql_query()

int mysql_query(MYSQL* mysql,const char* query)
Execute the SQL query pointed to by the "NULL-terminated string" query. Normally, the string must contain an SQL statement, and no semicolons ";" or "g" should be added to the statement.
mysql_query() cannot be used for queries containing binary data, mysql_real_query() should be used instead, because binary data may contain the character "", which mysql_query() interprets as the end of the query string.
Returns 0 if the query is successful, and non-zero if there is an error.

mysql_real_connect()

MYSQL* mysql_real_connect(MYSQL* mysql,const char* host,const char* user,const char* passwd,const char* db,const char* unix_socket,unsigned long client_flag)
mysql_real_connect() attempts to establish a connection with the MYSQL database engine running on the host. mysql_real_connect() must complete successfully before you can execute any other API functions that require a valid MYSQL connection handle mechanism.
The first parameter should be the address of an existing MYSQL structure. Call mysql_init() to initialize the MYSQL structure.
The value of the second parameter host must be the host name or IP address. If host is NULL or the string "localhost", the connection will be treated as a connection to the localhost. If the operating system supports sockets Unix or this named pipes Windows, they will be used instead of TCP/IP to connect to the server.
The third parameter user parameter contains the user's MYSQL login ID. If user is NULL or the empty string, the user will be considered the current user. In a UNIX environment, this is the current login name. Under Windows, the current user name must be specified.
The passwd parameter contains the user's password. If passwd is NULL, only the entries in the user table (with an empty password field) for that user are checked for a match. In this way, the database administrator can set the MYSQL permission system in a specific way, according to whether the user has the specified password, the user will get different permissions.
Note: Do not attempt to encrypt the password before calling mysql_real_connect(), password encryption will be handled automatically by the client API.
"db" is the database name, if db is NULL, the connection will set the default database to this value.
If port is not 0, its value will be used as the port number for TCP/IP connections. Note that the host parameter determines the type of connection.
If unix_socket is not NULL, this string describes which socket or named pipe should be used. Note: The "host" parameter determines the type of connection.
The value of client_flag is usually 0, however, flags can also be set. I won't introduce it, just Google it yourself.
Return value: If the connection is successful, return the MYSQL* connection handle. Returns NULL if the connection fails. For a successful connection, the return value is the same as the value of the first parameter.

mysql_real_query()

int mysql_real_query(MYSQL* mysql,const char* query,unsigned long length)
Execute the SQL query pointed to by "query", which shall be the string length byte "long". Normally, the string must contain an SQL statement, and no ";" or "g" should be added to the statement.
For queries that contain binary data, you must use mysql_real_query() instead of mysql_query() because binary data may contain "" characters. Also, mysql_real_query() is faster than mysql_query() because it does not call strlen() on the query string.
Returns 0 if the query is successful. If an error occurs, a non-zero value is returned.

mysql_row_seek()

MYSQL_ROW_OFFSET mysql_row_seek(MYSQL_RES* result, MYSQL_ROW_OFFSET offset)
Places row coordinates on any row in the query result set. offset is the row offset, which should be the value returned from mysql_row_tell() or mysql_row_seek(). The value is not a row number, use mysql_data_seek() if you intend to query the rows in the result set by number
This function requires the full results of the query in the result set, so mysql_row_seek() should only be used with mysql_store_result(), not with mysql_use_result().
The previous value of the row coordinate that can be passed to subsequent uses of mysql_row_seek().

mysql_row_tell()

MYSQL_ROW_OFFSET mysql_row_tell(MYSQL_RES* result)
For the previous mysql_fetch_row(), returns the current position of the cursor. This value can be used as an argument to mysql_row_seek().
Can only be used after mysql_store_result(), not after mysql_use_result().
Return value: the current offset of the row coordinates

mysql_set_character_set()

int mysql_set_character_set(MYSQL* mysql, char* csname)
This function is used to set the default character set for the current connection. The string csname specifies a valid character set name. The connection collation becomes the default collation for the character set.
Return value: 0 means success, non-zero value means error

if(!mysql_set_charset_name(&mysql,“utf8”))
{ printf("New client character set : %s ", mysql_character_set_name(&mysql)); }

mysql_shutdown()

int mysql_shutdown(MYSQL* mysql, enum enum_shutdown_level shutdown_level)
Request database server shutdown. To ensure that the connected user must have SHUTDOWN authority.
Return value: 0 for success, non-zero for an error.

mysql_store_result()

MYSQL_RES* mysql_store_result(MYSQL*mysql)
For each query (SELECT, SHOW, DESCRIBE, EXPLAIN, CHECK TABLE, etc.) that successfully retrieves data, mysql_store_result() or mysql_use_store() must be called.
mysql_store_result() reads the full results of the query to the client, allocates a MYSQL_RES structure, and places the results in that structure.
mysql_store_result() returns a NULL pointer if the query does not return a result set
If reading the result set fails, mysql_store_result() will also return a NULL pointer. You can check whether an error occurred by checking whether mysql_error() returns a non-empty string and mysql_errno() returns a non-zero value.
If no rows are returned, an empty result set will be returned. (Empty result set setting is different from null pointer as return value)
Once you call mysql_store_result() and get a result that is not a NULL pointer, you can call mysql_num_rows() to find out the number of rows in the result set.
You can call mysql_fetch_row() to get a row in the result set, or mysql_row_seek() or mysql_row_tell() to get or set the current row position in the result set.
Once the operation on the result set is complete, mysql_free_result() must be called.
Return value: MYSQL_RES result collection with multiple results. Returns NULL if there is an error.

mysql_use_result()

MYSQL_RES* mysql_use_result(MYSQL* mysql)
mysql_use_result will initialize the result set retrieval, but does not actually read the result set to the client as mysql_store_result() does. It must retrieve each row individually through a call to mysql_fetch_row(). This will read the result directly from the server without saving it to a temporary table or local buffer, which is faster and uses less memory than mysql_store_result(). The client allocates memory only for the current line and communication buffers.
If mysql_use_result() is used, this binds the server and prevents other threads from updating any tables.
When using mysql_use_result(), mysql_fetch_row() must be executed until a NULL value is returned, otherwise unfetched rows will be returned as part of the next retrieval.
mysql_data_seek(), mysql_row_seek(), mysql_row_tell(), mysql_num_row() should not be used with results returned from mysql_use_result(), nor should other queries be issued until mysql_use_result() completes.
Once the operation on the result set is complete, mysql_free_result() must be called.