mysql c api 总览文档翻译

花了好久终于把文档翻译完了，文档摘自mysql的官网，MySQL c api的具体使用流程在本文的最后有详细的讲解，是本文最重要的部分，至于函数的查阅，使用中文的翻译希望能够减轻查阅者的负担。

28.7.6 C API Function Overview

The following list summarizes the functions available in
the C API. For greater detail, see the descriptions in Section 28.7.7,
“C API Function Descriptions”.

l
my_init(): Initializes global variables and the
thread handler in thread-safe programs.

my_init()：初始化全局变量 以及 线程安全程序中的线程句柄

l
mysql_affected_rows(): Returns the number of rows changed/deleted/inserted by
the last UPDATE, DELETE, or INSERT query.

mysql_affected_rows():返回最后一个被修改/删除/插入命令影响的行数

l
mysql_autocommit(): Toggles autocommit mode on/off.

mysql_autocommit():切换自动提交模式，开启或关闭

l
mysql_change_user(): Changes the user and database on an
open connection.

mysql_change_user():在开放的连接中改变用户和数据库

l
mysql_character_set_name(): Returns the default character set name
for the current connection.

mysql_character_set_name():返回当前连接的默认的字符集名称

l
mysql_client_find_plugin(): Returns a pointer to a plugin.

mysql_client_find_plugin():返回一个插件的指针

l
mysql_client_register_plugin(): Registers a plugin.

mysql_client_register_plugin():注册一个插件

l
mysql_close(): Closes a server connection.

mysql_close():关闭服务器连接

l
mysql_commit(): Commits the transaction.

mysql_commit():提交数据库事务。

l
mysql_connect(): Connects to a MySQL server. This
function is deprecated; use mysql_real_connect() instead.

mysql_connect():连接mysql服务器。这个函数不建议使用；应用mysql_real_connect()替代。

l
mysql_create_db(): Creates a database. This function is
deprecated; use the SQL statement CREATE DATABASE instead.

mysql_create_db():创建一个数据库。这个函数不建议使用；应用SQL语句 CREATE DATABASE替代。

l
mysql_data_seek(): Seeks to an arbitrary row number in a
query result set.

mysql_data_seek():搜索一个查询结果集中的任意行号

l
mysql_debug(): Does a DBUG_PUSH with the given string.

mysql_debug():用指定字符串进行 DBUG_PUSH

l
mysql_drop_db(): Drops a database. This function is
deprecated; use the SQL statement DROP DATABASE instead.

mysql_drop_db():删除一个数据库。这个函数不建议使用；应用SQL语句 DROP DATABASE替代。

l
mysql_dump_debug_info(): Causes the server to write debug
information to the log.

mysql_dump_debug_info():使服务器在日志中写下纠错信息。

l
mysql_eof(): Determines whether the last row of a
result set has been read. This function is deprecated; use mysql_errno() or mysql_error() instead.

mysql_eof():判断一个结果集的最后一行是否被读过。这个函数不建议使用；应用mysql_errno() 或 mysql_error()替代。

l
mysql_errno(): Returns the error number for the most
recently invoked MySQL function.

mysql_errno():返回最后使用的mysql函数的错误号码

l
mysql_error(): Returns the error message for the most
recently invoked MySQL function.

mysql_error():返回最后使用的mysql函数的错误消息

l
mysql_escape_string(): Escapes special characters in a string
for use in an SQL statement.

mysql_escape_string():在一个sql语句的字符串中逃避指定的字符串（官方声明不要用）。

l
mysql_fetch_field(): Returns the type of the next table
field.

mysql_fetch_field():返回表的下一个字段（注：field，是数据项，可作属性名）的类型

l
mysql_fetch_field_direct(): Returns the type of a table field,
given a field number.

mysql_fetch_field_direct():返回表的指定字段号的字段的类型

l
mysql_fetch_fields(): Returns an array of all field
structures.

mysql_fetch_fields():返回一个包含全部的字段结构体（注：每个结构体包含一个列的字段的定义）的数组

l
mysql_fetch_lengths(): Returns the lengths of all columns in
the current row.

mysql_fetch_lengths():返回一个包含当前行的所有列长度的数组

l
mysql_fetch_row(): Fetches the next row from the result
set.

mysql_fetch_row():取得结果集的下一行（注：返回行结构体）

l
mysql_field_count(): Returns the number of result columns
for the most recent statement.

mysql_field_count():返回最后一个指令中结果的行的数量

l
mysql_field_seek(): Puts the column cursor on a specified
column.

mysql_field_seek():把列光标放在指定的列上（注：主要是mysql_fetch_field()使用，通过指定offset，而offset是字段序号，通过光标，fetch下一个field的时候，会fetch到指定field。）

l
mysql_field_tell(): Returns the position of the field
cursor used for the last mysql_fetch_field().

mysql_field_tell():返回最后一次用于mysql_fetch_field()的列光标的位置（fetch field本身是使用光标的么？）

l
mysql_free_result(): Frees memory used by a result set.

mysql_free_result():释放结果集使用的内存

l
mysql_get_character_set_info(): Returns information about default
character set.

mysql_get_character_set_info():返回默认字符集的信息

l
mysql_get_client_info(): Returns client version information as
a string.

mysql_get_client_info():以字符串的方式返回客户端的版本信息

l
mysql_get_client_version(): Returns client version information as
an integer.

mysql_get_client_version():以整数的形式返回客户端的版本信息

l
mysql_get_host_info(): Returns a string describing the
connection.

mysql_get_host_info():返回一个描述连接的字符串（注：服务器名和连接类型）

l
mysql_get_option(): Returns the value of a mysql_options() option.

mysql_get_option():返回指定的一个选项的选项值

l
mysql_get_proto_info(): Returns the protocol version used by
the connection.

mysql_get_proto_info():返回连接使用的协议版本

l
mysql_get_server_info(): Returns the server version number.

mysql_get_server_info():返回服务器端的版本号

l
mysql_get_server_version(): Returns the server version number as
an integer.

mysql_get_server_version():以整数的形式返回服务器端的版本信息

l
mysql_get_ssl_cipher(): Returns the current SSL cipher.

mysql_get_ssl_cipher():返回当前与服务器连接的ssl加密密钥

l
mysql_hex_string(): Encodes a string in hexadecimal
format.

mysql_hex_string():以16进制的格式编码一个字符串

l
mysql_info(): Returns information about the most
recently executed query.

mysql_info():返回最后的已执行的查询的信息

l
mysql_init(): Gets or initializes a MYSQL structure.

mysql_init():创建或初始化一个mysql的结构体

l
mysql_insert_id(): Returns the ID generated for an AUTO_INCREMENT column by the previous query.

mysql_insert_id():返回由之前查询产生的一个AUTO_INCREMENT列的id

l
mysql_kill(): Kills a given thread.

mysql_kill():关闭指定线程

l
mysql_library_end(): Finalizes the MySQL C API library.

mysql_library_end():结束ＭｙＳＱＬ　C　ＡＰＩ库

l
mysql_library_init(): Initializes the MySQL C API library.

mysql_library_init():初始化ＭｙＳＱＬ　C　ＡＰＩ库

l
mysql_list_dbs(): Returns database names matching a
simple regular expression.

mysql_list_dbs():返回符合表达的数据库名（类似％，＿；相当于　ｓｈｏｗｄａｔａｂａｓｅ　ｌｉｋｅ　。。。）

l
mysql_list_fields(): Returns field names matching a simple
regular expression.

mysql_list_fields():返回符合表达的字段名

l
mysql_list_processes(): Returns a list of the current server
threads.

mysql_list_processes():返回当前服务器的线程列表

l
mysql_list_tables(): Returns table names matching a simple
regular expression.

mysql_list_tables():返回符合表达的表格名

l
mysql_load_plugin(): Loads a plugin.

mysql_load_plugin():加载一个插件

l
mysql_load_plugin_v(): Loads a plugin.

mysql_load_plugin_v():加载一个插件

l
mysql_more_results(): Checks whether any more results exist.

mysql_more_results():检查是否有更多的结果存在

l
mysql_next_result(): Returns/initiates the next result in
multiple-result executions.

mysql_next_result():返回或启动有多结果操作的下一个结果

l
mysql_num_fields(): Returns the number of columns in a
result set.

mysql_num_fields():返回结果集的行数

l
mysql_num_rows(): Returns the number of rows in a result
set.

mysql_num_rows():返回结果集的列数

l
mysql_options(): Sets connect options for mysql_real_connect().

mysql_options():设置mysql_real_connect()的连接选项

l
mysql_options4(): Sets connect options for mysql_real_connect().

mysql_options4():设置mysql_real_connect()的连接选项

l
mysql_ping(): Checks whether the connection to the
server is working, reconnecting as necessary.

mysql_ping():检查对服务器的连接是否有效，必要时进行再次连接。

l
mysql_plugin_options(): Sets a plugin option.

mysql_plugin_options():设置插件选项

l
mysql_query(): Executes an SQL query specified as a
null-terminated string.

mysql_query():执行一个用以空结尾的字符串指定的SQL指令

l
mysql_real_connect(): Connects to a MySQL server.

mysql_real_connect():与一个MYSQL的服务器连接

l
mysql_real_escape_string(): Escapes special characters in a string
for use in an SQL statement, taking into account the current character set of
the connection.

mysql_real_escape_string():考虑当前连接的字符集，跳过字符串中的特殊的字符来用于sql语句。

l
mysql_real_escape_string_quote(): Escapes special characters in a string
for use in an SQL statement, taking into account the current character set of
the connection and the quoting context.

mysql_real_escape_string_quote():考虑当前连接的字符集和引用的上下文，跳过字符串中的特殊的字符来用于sql语句。

l
mysql_real_query(): Executes an SQL query specified as a
counted string.

mysql_real_query():执行一个被计数的字符串指定的sql查询

l
mysql_refresh(): Flushes or resets tables and caches.

mysql_refresh():刷新或重置表格和缓存

l
mysql_reload(): Tells the server to reload the grant
tables.

mysql_reload():指使服务器重新加载授权的表格

l
mysql_reset_connection(): Resets the connection to clear session state.

mysql_reset_connection():重置连接来清理

l
mysql_reset_server_public_key(): Clears a cached RSA public key from
the client library.

mysql_reset_server_public_key():清理在客户库中的隐藏的RSA公钥

l
mysql_result_metadata(): Whether a result set has metadata.

mysql_result_metadata():检查一个结果集是否有元数据

l
mysql_rollback(): Rolls back the transaction.

mysql_rollback():回滚事务

l
mysql_row_seek(): Seeks to a row offset in a result set, using value returned
from mysql_row_tell().

mysql_row_seek():用mysql_row_tell()里返回的值找一个结果集中的

l
mysql_row_tell(): Returns the row cursor position.

mysql_row_tell():返回行光标的位置

l
mysql_select_db(): Selects a database.

mysql_select_db():选择一个数据库

l
mysql_server_end(): Finalizes the MySQL C API library.

mysql_server_end():使MySQL C API库结束

l
mysql_server_init(): Initializes the MySQL C API library.

mysql_server_init():初始化MySQL C API库

l
mysql_session_track_get_first(): Gets the first part of session
state-change information.

mysql_session_track_get_first():获得会话状态改变信息的第一部分

l
mysql_session_track_get_next(): Gets the next part of session
state-change information.

mysql_session_track_get_next():获得会话状态改变信息的接下来的部分

l
mysql_set_character_set(): Sets the default character set for the
current connection.

mysql_set_character_set():为当前连接设置默认字符集

l
mysql_set_local_infile_default(): Sets the LOAD DATA LOCAL handler callbacks to their default
values.

mysql_set_local_infile_default():设置LOAD DATA LOCAL的回调函数设置为默认（由c客户函数库提供）

l
mysql_set_local_infile_handler(): Installs application-specific LOAD DATA LOCAL handler callbacks.

mysql_set_local_infile_handler():安装自定义的LOAD DATA LOCAL回调函数

l
mysql_set_server_option(): Sets an option for the connection
(like multi-statements).

mysql_set_server_option():为连接设置一个选项（如多个语句）

l
mysql_sqlstate(): Returns the SQLSTATE error code for
the last error.

mysql_sqlstate():返回最近一个错误的SQLSTATE错误代码

l
mysql_shutdown(): Shuts down the database server.

mysql_shutdown():关闭数据库服务器

l
mysql_ssl_set(): Prepares to establish an SSL
connection to the server.

mysql_ssl_set():准备建立一个对服务器的ssl连接

l
mysql_stat(): Returns the server status as a string.

mysql_stat():以字符串的形式返回服务器状态

l
mysql_store_result(): Retrieves a complete result set to the
client.

mysql_store_result():在语句查询后为客户提供完整的结果集

l
mysql_thread_end(): Finalizes a thread handler.

mysql_thread_end():使一个线程句柄结束

l
mysql_thread_id(): Returns the current thread ID.

mysql_thread_id():返回当前线程id

l
mysql_thread_init(): Initializes a thread handler.

mysql_thread_init():初始化一个线程句柄

l
mysql_thread_safe(): Returns 1 if the clients are compiled
as thread-safe.

mysql_thread_safe():如果客户被编译后为线程安全返回1

l
mysql_use_result(): Initiates a row-by-row result set
retrieval.

mysql_use_result():初始化一个一个行接一个行的结果集遍历（即，挨着返回一个一个行，初始化后都要一直用fetchrow来取得行，直到出现空，否则会成为接下来查询的返回结果）

l
mysql_warning_count(): Returns the warning count for the
previous SQL statement.

mysql_warning_count():返回前一个sql语句有多少错误

Application programs should use this
general outline for interacting with MySQL:

应用程序需要用这个大纲来与MySQL交互：

Initialize the MySQL client library by calling mysql_library_init().

通过mysql_library_init()初始化MySQL客户函数库

Initialize a connection handler by calling mysql_init() and connect to the server by calling mysql_real_connect().

通过mysql_init()初始化一个连接的句柄并通过mysql_real_connect()与服务器进行连接。

Issue SQL statements and process their results. (The
following discussion provides more information about how to do this.)

发出sql语句并处理他们的结果

Close the connection to the MySQL server by calling mysql_close().

通过mysql_close()关闭与MySQL的服务器连接

End use of the MySQL client library by calling mysql_library_end().

通过mysql_library_end()结束使用MySQL客户函数库

The purpose of calling mysql_library_init() and mysql_library_end() is to provide proper initialization and
finalization of the MySQL client library. For applications that are linked with
the client library, they provide improved memory management. If you do not call
mysql_library_end(), a block of memory remains allocated.
(This does not increase the amount of memory used by the application, but some
memory leak detectors will complain about it.)

调用mysql_library_init()和mysql_library_end()的目的是提供合适的初始化和结束客户函数库的操作。对于链接客户函数库的应用，他们提供改进的内存管理。如果不调用mysql_library_end()，一块内存将持续被申请。（这不会增加应用使用的内存数量，但有的内存泄漏检测会对此报错。）

In a nonmultithreaded environment, the call to mysql_library_init() may be omitted, because mysql_init() will invoke it automatically as
necessary. However, mysql_library_init() is not thread-safe in a multithreaded
environment, and thus neither is mysql_init(), which calls mysql_library_init(). You must either call mysql_library_init() prior to spawning any threads, or else
use a mutex to protect the call, whether you invoke mysql_library_init() or indirectly through mysql_init(). This should be done prior to any other
client library call.

To connect to the server, call mysql_init() to initialize a connection handler, then
call mysql_real_connect() with that handler (along with other
information such as the host name, user name, and password). Upon connection, mysql_real_connect() sets the reconnect flag (part of the MYSQL structure) to a value of 1 in versions of the API older than
5.0.3, or 0 in newer versions. A value of 1 for this flag indicates that if a
statement cannot be performed because of a lost connection, to try reconnecting
to the server before giving up. You can use the MYSQL_OPT_RECONNECT option to mysql_options() to control reconnection behavior. When
you are done with the connection, call mysql_close() to terminate it. Do not use the handler
after it has been closed.

在非多线程环境中，对mysql_library_init()的引用可能被省略，因为mysql_init()在必要时会自动调用它。但是，mysql_library_init()在多线程环境中不是线程安全的，因此调用mysql_library_init()的mysql_init()也不是线程安全的。你必须要么在大量开启线程前调用mysql_library_init()，要么不论用mysql_library_init()还是间接地用mysql_init()都要用互斥体来保护一个调用。

这需要在任何调用客户函数库前完成。为了与服务器连接，调用mysql_init()来初始化一个连接句柄，然后用那个句柄（带着其他信息比如主机名，用户名，密码）来调用mysql_real_connect()。在连接之上，mysql_real_connect()设置reconnect标志（MySQL结构体的一部分），在api小于5.0.3的版本中函数将值设为为1，在新版本中设为0.这个标志的1，代表着，如果一个语句因为断开连接而无法执行，在放弃之前尝试再连接服务器。你可以用mysql_options()的MYSQL_OPT_RECONNECT设置项来控制再连接行为。当你完成了连接的工作，调用mysql_close()来终结。在关闭之后不要再用句柄。

While a connection is active, the client may send SQL
statements to the server using mysql_query() or mysql_real_query(). The difference between the two is that
mysql_query() expects the query to be specified as a
null-terminated string whereas mysql_real_query() expects a counted string. If the string
contains binary data (which may include null bytes), you must use mysql_real_query().

For each non-SELECT query (for example, INSERT, UPDATE, DELETE), you can find out how many rows were
changed (affected) by calling mysql_affected_rows().

For SELECT queries, you retrieve the selected rows
as a result set. (Note that some statements are SELECT-like in that they return rows. These
include SHOW, DESCRIBE, and EXPLAIN. Treat these statements the same way as
SELECT statements.)

There are two ways for a client to process result sets.
One way is to retrieve the entire result set all at once by calling mysql_store_result(). This function acquires from the server
all the rows returned by the query and stores them in the client. The second
way is for the client to initiate a row-by-row result set retrieval by calling mysql_use_result(). This function initializes the
retrieval, but does not actually get any rows from the server.

当一个连接活动时，客户可能用mysql_query() 或 mysql_real_query()发送SQL语句给服务器。两者的区别是，mysql_query()期待查询是用以空结尾的字符串指定的，而mysql_real_query()期待被计数的字符串。如果一个字符串包含二进制数据（因此可能包含空字符），你必须用mysql_real_query()。对每一个不进行SELECT的查询，（比如说INSERT, UPDATE, DELETE），你可以通过mysql_affected_rows()来发现多少行被修改。对于有SELECT的查询，你像对结果集一样，检索被选择的行。（要注意一些语句是类似选择的，因为他们返回行。它们包括SHOW, DESCRIBE, 和EXPLAIN。对这些语句与对SELECT语句一样。）

客户有两种方式去操作结果集。一种是通过mysql_store_result()一次性检索整个结果集。这个函数通过查询从服务器获得所有的行，并且为客户保留。第2种方式是客户通过mysql_use_result()初始化一个行挨着另一个行的结果集检索。这个函数初始化检索但实际上并不从服务器取得任何行。（注：只是一个初始化的过程）

In both cases, you access rows by calling mysql_fetch_row(). With mysql_store_result(), mysql_fetch_row() accesses rows that have previously been
fetched from the server. With mysql_use_result(), mysql_fetch_row() actually retrieves the row from the
server. Information about the size of the data in each row is available by
calling mysql_fetch_lengths().

After you are done with a result set, call mysql_free_result() to free the memory used for it.

这两种情况下你通过调用mysql_fetch_row()来取得行。通过mysql_store_result(), mysql_fetch_row()取得的行是先前已经从服务器取得的。通过mysql_use_result(), mysql_fetch_row()实际上检索的事是直接来自服务器的行。可以通过调用mysql_fetch_lengths()利用每一个行数据大小的信息。在你操作完一个结果集后调用mysql_free_result()来释放它使用的内存。

The two retrieval mechanisms are complementary. Choose
the approach that is most appropriate for each client application. In practice,
clients tend to use mysql_store_result() more commonly.

两种检索机制是互相补充的。请为每一个客户应用选择最合适的方法。实际上客户更倾向于经常使用mysql_store_result()。

An advantage of mysql_store_result() is that because the rows have all been
fetched to the client, you not only can access rows sequentially, you can move
back and forth in the result set using mysql_data_seek() or mysql_row_seek() to change the current row position
within the result set. You can also find out how many rows there are by calling
mysql_num_rows(). On the other hand, the memory
requirements for mysql_store_result() may be very high for large result sets
and you are more likely to encounter out-of-memory conditions.

mysql_store_result()的一个好处是因为行已经为客户取得了，你不仅可以继续地取得行，你可以通过mysql_data_seek() 或 mysql_row_seek()在结果集中向前向后移动来改变当前在结果集中的行位置。你也可以通过调用mysql_num_rows()来发现结果集中有多少行。另一方面调用mysql_store_result()对内存的要求可能因为大的结果集而非常高并且你也更可能会遇到内存不足的情况。

An advantage of mysql_use_result() is that the client requires less memory
for the result set because it maintains only one row at a time (and because
there is less allocation overhead, mysql_use_result() can be faster). Disadvantages are that
you must process each row quickly to avoid tying up the server, you do not have
random access to rows within the result set (you can only access rows
sequentially), and the number of rows in the result set is unknown until you
have retrieved them all. Furthermore, you must retrieve all the rows even if you
determine in mid-retrieval that you’ve found the information you were looking
for.

mysql_use_result()的一个好处是客户为结果集需要更少的内存因为他一次只包含一行（并且因为mysql_use_result()有了更小的分配开销可以更快）。缺点有你必须快速取得每一行来避免捆绑服务器，并且你不能对结果集有随机的访问（你只能连续的访问行），并且结果集中的行数是未知的，除非历经完全地遍历了他们。还有即使你在检索的中途已经找到了你想寻找的信息而决定结束，但你必须遍历完所有的行。

The API makes it possible for clients to respond
appropriately to statements (retrieving rows only as necessary) without knowing
whether the statement is a SELECT. You can do this by calling mysql_store_result() after each mysql_query() (or mysql_real_query()). If the result set call succeeds, the
statement was a SELECT and you can read the rows. If the
result set call fails, call mysql_field_count() to determine whether a result was
actually to be expected. If mysql_field_count() returns zero, the statement returned no
data (indicating that it was an INSERT, UPDATE, DELETE, and so forth), and was not expected to
return rows. If mysql_field_count() is nonzero, the statement should have
returned rows, but did not. This indicates that the statement was a SELECT that failed. See the description for mysql_field_count() for an example of how this can be done.

API使客户在不知道语句是SELECT.的情况下正确地对语句进行响应成为了可能（仅在必要时检索行）。你可以通过调用在每次在调用mysql_query() (or mysql_real_query())之后调用mysql_store_result()来利用这点。如果结果集查询成功，那么这个语句是一个SELECT，然后你可以读取行。如果结果集查询失败，调用mysql_field_count()来决定函数是否真的期待一个结果。如果mysql_field_count()返回0，那么语句不返回数据并且不会返回数据。（表示这是一个INSERT, UPDATE, DELETE等等）。如果mysql_field_count()不返回0，那么这个语句本应该返回行，但并没有。这标示语句是一个失败的SELECT。看mysql_field_count()的描述为例子来知道这是什么情况。Both mysql_store_result() and mysql_use_result() enable you to obtain information about
the fields that make up the result set (the number of fields, their names and
types, and so forth). You can access field information sequentially within the
row by calling mysql_fetch_field() repeatedly, or by field number within
the row by calling mysql_fetch_field_direct(). The current field cursor position may
be changed by calling mysql_field_seek(). Setting the field cursor affects
subsequent calls to mysql_fetch_field(). You can also get information for
fields all at once by calling mysql_fetch_fields().

mysql_store_result() and mysql_use_result()都允许你获取结果集的字段信息。（字段号，他们的名字，和类型等等）。你可以连续的取得一个行中的字段信息通过重复调用mysql_fetch_field()或者通过调用指定行中的字段号调用mysql_fetch_field_direct()。mysql_field_seek()可能改变当前字段光标的位置。设置字段光标会影响后来对mysql_fetch_field()函数的调用。你也可以通过调用mysql_fetch_fields()来一次性获得所有字段的信息。

For detecting and reporting errors, MySQL provides access
to error information by means of the mysql_errno() and mysql_error() functions. These return the error code
or error message for the most recently invoked function that can succeed or
fail, enabling you to determine when an error occurred and what it was.

对于检查和汇报错误，mysql提供mysql_errno() 和 mysql_error()的方法来取得错误信息。他们会返回不论成功与否的最后一次调用的函数的错误代码和错误消息，这可以让你检查出一个错误是否发生并知道错误是什么。