MySql C Connector 文档翻译 Overview

mysql_affected_rows() 返回被最新的UPDATE, DELETE或INSERT查询影响的行数。  
mysql_close() 关闭一个服务器连接。  
mysql_connect() 连接一个MySQL服务器。该函数不推荐；使用mysql_real_connect()代替。  
mysql_change_user() 改变在一个打开的连接上的用户和数据库。  
mysql_create_db() 创建一个数据库。该函数不推荐；而使用SQL命令CREATE DATABASE。  
mysql_data_seek() 在一个查询结果集合中搜寻一任意行。  
mysql_debug() 用给定字符串做一个DBUG_PUSH。  
mysql_drop_db() 抛弃一个数据库。该函数不推荐；而使用SQL命令DROP DATABASE。  
mysql_dump_debug_info() 让服务器将调试信息写入日志文件。  
mysql_eof() 确定是否已经读到一个结果集合的最后一行。这功能被反对; mysql_errno()或mysql_error()可以相反被使用。  
mysql_errno() 返回最近被调用的MySQL函数的出错编号。  
mysql_error() 返回最近被调用的MySQL函数的出错消息。  
mysql_escape_string() 用在SQL语句中的字符串的转义特殊字符。  
mysql_fetch_field() 返回下一个表字段的类型。  
mysql_fetch_field_direct () 返回一个表字段的类型，给出一个字段编号。  
mysql_fetch_fields() 返回一个所有字段结构的数组。  
mysql_fetch_lengths() 返回当前行中所有列的长度。  
mysql_fetch_row() 从结果集合中取得下一行。  
mysql_field_seek() 把列光标放在一个指定的列上。  
mysql_field_count() 返回最近查询的结果列的数量。  
mysql_field_tell() 返回用于最后一个mysql_fetch_field()的字段光标的位置。  
mysql_free_result() 释放一个结果集合使用的内存。  
mysql_get_client_info() 返回客户版本信息。  
mysql_get_host_info() 返回一个描述连接的字符串。  
mysql_get_proto_info() 返回连接使用的协议版本。  
mysql_get_server_info() 返回服务器版本号。  
mysql_info() 返回关于最近执行得查询的信息。  
mysql_init() 获得或初始化一个MYSQL结构。  
mysql_insert_id() 返回有前一个查询为一个AUTO_INCREMENT列生成的ID。  
mysql_kill() 杀死一个给定的线程。  
mysql_list_dbs() 返回匹配一个简单的正则表达式的数据库名。  
mysql_list_fields() 返回匹配一个简单的正则表达式的列名。  
mysql_list_processes() 返回当前服务器线程的一张表。  
mysql_list_tables() 返回匹配一个简单的正则表达式的表名。  
mysql_num_fields() 返回一个结果集合重的列的数量。  
mysql_num_rows() 返回一个结果集合中的行的数量。  
mysql_options() 设置对mysql_connect()的连接选项。  
mysql_ping() 检查对服务器的连接是否正在工作，必要时重新连接。  
mysql_query() 执行指定为一个空结尾的字符串的SQL查询。  
mysql_real_connect() 连接一个MySQL服务器。  
mysql_real_query() 执行指定为带计数的字符串的SQL查询。  
mysql_reload() 告诉服务器重装授权表。  
mysql_row_seek() 搜索在结果集合中的行，使用从mysql_row_tell()返回的值。  
mysql_row_tell() 返回行光标位置。  
mysql_select_db() 连接一个数据库。  
mysql_shutdown() 关掉数据库服务器。  
mysql_stat() 返回作为字符串的服务器状态。  
mysql_store_result() 检索一个完整的结果集合给客户。  
mysql_thread_id() 返回当前线程的ID。  
mysql_use_result() 初始化一个一行一行地结果集合的检索

应用程序应该按照这个大纲中的描述与MySQL交互：

1、通过调用mysql_library_init()来初始化MySQL库。该函数在libmysqlclient C客户端库和libmysqld嵌入式服务器库中都有，构建一个普通的客户端程序在链接时应该指定-libmysqlclient选项，或在构建嵌入式服务器应用时指定- libmysqld选项。

2、通过调用mysql_init()初始化一个连接处理器(connection handler)，并通过调用mysql_real_connect()连接到服务器。

3、SQL语句和自执行结果的处理的问题。（下面的讨论提供了更多的信息关于如何做到这一点。）

4、通过调用mysql_close()关闭MySQL服务器的连接。

5、通过调用mysql_library_end()来结束MySQL库的使用。

调用mysql_library_init()和mysql_library_end()的目的是对MySQL库适当的初始化和终止。那些与客户端库链接的应用程序，它们提供了高级的(improve，改进的)内存管理。如果你不调用mysql_library_end()，与其关联的一段内存将被保留。（这不增加的程序使用的内存，但一些内存泄漏检测器会误测到(comlain about it)。）那些与嵌入式服务器连接的应用程序，这些调用将会启动和停止服务器。

在非多线程的环境中，调用mysql_library_init()的过程可以省略，因为mysql_init()将在必要时调用它。然而，mysql_library_init()在多线程环境下是非线程安全的，mysql_init()和mysql_library_init()都不是（线程安全的）。你必须先调用mysql_library_init()产生任何其他线程前，或者使用互斥锁来保护这个调用，无论你调用mysql_library_init()还是间接通过mysql_init()。这应该在任何其他的客户端库函数调用之前完成。

要连接到服务器，调用mysql_init()初始化连接处理器(handler)，然后用这个处理器调用mysql_real_connect()（以及其他信息，如主机名，用户名，密码）。在连接前，mysql_real_connect()设置重连接标志(reconncet flag)（MYSQL结构体的一部分）的值为1（在旧版本的API中），或0（在更新的版本里）。值为1的这个标志表示SQL语句不能被执行因为失去了连接，在放弃执行之前可以尝试重新连接到服务器。在调用mysql_options()时你可以使用MYSQL_OPT_RECONNECT选项来控制重连接行为。当完成连接后，调用mysql_close()终止它。

当一个连接还存活时，客户端可以使用mysql_query()或mysql_real_query()发送SQL语句给服务器。两者的区别是，mysql_query()期望查询语句被指定为一个以NULL结尾的字符串而mysql_real_query()期望一个知道字符数目的字符串。如果字符串包含二进制数据（可能包括NULL字节），这时必须使用mysql_real_query()。

对于每个非SELECT查询（例如，插入，更新，删除），你可以通过调用mysql_affected_rows()找到多少行被改变（影响）了。

对于选择查询，您应该重新检索选定的行作为结果集。（注意，在返回的行里有些语句是类似SELECT的。这些包括SHOW，DESCRIBE和EXPLAIN，用和对待SELECT语句相同的方式对待这些语句。）

客户端有有两种处理结果集(result sets)的方式。方法之一是通过调用一次mysql_store_result()来索取整个结果集。这个函数从服务器从服务器取得了查询操作返回的所有行并且把它们存储在客户端。方法之二是为在客户端通过调用mysql_use_result()初始化一个一行接一行的结果集。该函数只是初始化检索，但实际上并没有从服务器上得到任何行。

在这两种情况下，你可以通过调用mysql_fetch_row()来访问行。用mysql_store_result()，mysql_fetch_row()访问先前已从服务器读取的行。用mysql_use_result()，mysql_fetch_row()是真正从服务器取回行的。可以调用mysql_fetch_lengths()来获得每一行中的数据的size的信息。

在你用完了一个结果集(result set)之后，调用mysql_free_result()释放其相关内存。

这两种检索机制是互补的。为每个客户端选择合适的检索方法。在实践中，客户端往往使用mysql_store_result()。

mysql_store_result()的一个优点是，由于所有的行都被fetch到了客户端，你不仅可以顺序访问行，而且可以在结果集中来回移动，通过使用mysql_data_seek()或mysql_row_seek()改变当前行的位置。你也可以调用mysql_num_rows()知道有多少行。另一方面，对于在的结果集来说mysql_store_result()内存要求可能会很大并且你更可能会遇到内存不足的情况。

mysql_use_result()的一个优点是，客户端要求对结果集的需求的内存更少因为在一段时间里它只把持一行数据（因为有更少的内存分配的开销，mysql_use_result()可以更快）。缺点是你必须迅速地处理每一行数据来避免服务器完成处理。你不能在一个结果集里随机访问行（你只能顺序的访问行），并在结果集的行数是未知的直到你收到所有的数据。此外，你必须要检索完所有的行即使你在中间的收取过程中找到了你想要的信息。

这个API可以让客户端响应适当的语句（只在必要时索取行）而不用知道该语句是否为SELECT。你可以在每次调用完mysql_query()（或mysql_real_query()）后调用mysql_store_result()来这样做。如果结果集调用成功，则语句为SELECT并且你可以读取行。如果结果集调用失败，调用mysql_field_count()来判断结果是否为预期的。如果mysql_field_count()返回0，则SQL语句没有返回数据（表明它是一个INSERT，UPDATE，DELETE，等等），而不是希望返回行。如果mysql_field_count()是非零的， the statement should have returned rows, but did not. This indicates that the statement was a SELECT that failed. 看看mysql_field_count()的描述来知道这是如何做到的。

mysql_store_result()和mysql_use_result()都可以使你获得关于组成结果集的字段的信息（字段的数目，名字和类型，等等）。你可以顺序地访问字段信息在一行内通过重复的调用mysql_fetch_field()，或在一行内通过字段数调用mysql_fetch_field_direct()（获取字段信息）。当前场的光标位置可以通过调用mysql_field_seek()改变。设置字段的光标会影响随后调用的mysql_fetch_field()。你也可以得到所有的字段信息通过调用一次mysql_fetch_fields()。

对于检测和报告错误，MySQL提供了访问错误信息的mysql_errno()和mysql_error()函数。这些返回的错误代码或最近的一次函数调用的错误信息是成功还是失败，你可以在一条错误出现时确定它是什么。