my_ulonglong mysql_affected_rows(MYSQL *mysql)

描述

返回上次UPDATE更改的行数，上次DELETE删除的行数，或上 次INSERT语句插入的行数。对于UPDATE、DELETE或INSERT语 句，可在mysql_query()后立刻调用。对于SELECT语句，mysql_affected_rows()的 工作方式与mysql_num_rows()类似。

返回值

大于0的整数表明受影响或检索的行数。“0”表示UPDATE语 句未更新记录，在查询中没有与WHERE匹配的行，或未执行查询。“-1” 表示查询返回错误，或者，对于SELECT查询，在调用mysql_store_result()之 前调用了mysql_affected_rows()。由于mysql_affected_rows()返 回无符号值，通过比较返回值和“(my_ulonglong)-1”或等效的“(my_ulonglong)~0”， 检查是否为“-1”。

错误

无。

示例：

mysql_query(&mysql,"UPDATE products SET cost=cost*1.25 WHERE group=10");

printf("%ld products updated",(long) mysql_affected_rows(&mysql));

如果在连接至mysqld时指定了标志CLIENT_FOUND_ROWS， 对于UPDATE语句，mysql_affected_rows()将 返回WHERE语句匹配的行数。

注意，使用REPLACE命令时，如果新行替代了旧行，mysql_affected_rows()返 回2。这是因为，在该情况下，删除了重复行后插入了1行。

如果使用“INSERT ... ON DUPLICATE KEY UPDATE”来插入行，如果行是作为新行插入的，mysql_affected_rows()返 回1，如果是更新了已有的行，返回2。

my_bool mysql_autocommit(MYSQL *mysql, my_bool mode)

描述

如果模式为“1”，启用autocommit模式；如果模式为“0”， 禁止autocommit模式。

返回值

如果成功，返回0，如果出现错误，返回非0值。

错误

无。

my_bool mysql_change_user(MYSQL *mysql, const char *user, const char *password, const char *db)

描述

更改用户，并使由db指定的数据库成为由mysql指定的连接上的默认数据库 （当前数据库）。在后续查询中，对于不包含显式数据库区分符的表引用，该数据库是默认数据库。

如果不能确定已连接的用户或用户不具有使用数据库的权限，mysql_change_user()将 失败。在这种情况下，不会改变用户和数据库。

如果不打算拥有默认数据库，可将db参数设置为NULL。

该命令总是会执行活动事务的ROLLBACK操作，关闭所有的临时表，解锁所有的锁定表，并复位状态，就像 进行了新连接那样。即使未更改用户，也会出现该情况。

返回值

0表示成功，非0值表示出现错误。

错误

与从mysql_real_connect()获得的相同。

·         CR_COMMANDS_OUT_OF_SYNC

以不恰当的顺序执行了命令。

·         CR_SERVER_GONE_ERROR

MySQL服务器不可用。

·         CR_SERVER_LOST

在查询过程中丢失了与服务器的连接。

·         CR_UNKNOWN_ERROR

出现未知错误。

·         ER_UNKNOWN_COM_ERROR

MySQL服务器未实施该命令（或许是较低版本的服务器）。

·         ER_ACCESS_DENIED_ERROR

用户或密码错误。

·         ER_BAD_DB_ERROR

数据库不存在。

·         ER_DBACCESS_DENIED_ERROR

用户没有访问数据库的权限。

·         ER_WRONG_DB_NAME

数据库名称过长。

示例：

if (mysql_change_user(&mysql, "user", "password", "new_database"))

{

   fprintf(stderr, "Failed to change user.  Error: %s\n",

           mysql_error(&mysql));

}

const char *mysql_character_set_name(MYSQL *mysql)

描述

为当前连接返回默认的字符集。

返回值

默认字符集。

错误

无。

void mysql_close(MYSQL *mysql)

描述

关闭前面打开的连接。如果句柄是由mysql_init()或mysql_connect()自 动分配的，mysql_close()还将解除分配由mysql指向的 连接句柄。

返回值

无。

错误

无。

my_bool mysql_commit(MYSQL *mysql)

描述

提交当前事务。

该函数的动作受completion_type系统变量的值控制。尤其是，如果completion_type的 值为2，终结事务并关闭客户端连接后，服务器将执行释放操作。客户端程序应调用mysql_close()， 从客户端一侧关闭连接。

返回值

如果成功，返回0，如果出现错误，返回非0值。

错误

无。

MYSQL *mysql_connect(MYSQL *mysql, const char *host, const char *user, const char *passwd)

描述

该函数已过时。最好使用mysql_real_connect()取而代之。

mysql_connect()试图建立与运行在主机上的MySQL数据库引擎 的连接。在能够执行任何其他API函数之前，mysql_connect()必须成 功完成，但mysql_get_client_info()例外。

这些参数的意义与mysql_real_connect()的对应参数的意义相同，差别在于 连接参数可以为NULL。在这种情况下，C API将自动为连接结构分配内存，并当调用mysql_close()时 释放分配的内存。该方法的缺点是，如果连接失败，你无法检索错误消息。要想从mysql_errno()或mysql_error()获 得错误消息，必须提供有效的MYSQL指针。

返回值

与mysql_real_connect()的相同。

错误

与mysql_real_connect()的相同。

int mysql_create_db(MYSQL *mysql, const char *db)

描述

创建由db参数命名的数据库。

该函数已过时。最好使用mysql_query()来发出SQL CREATE DATABASE语句。

返回值

如果数据库已成功创建，返回0，如果出现错误，返回非0值。

错误

·         CR_COMMANDS_OUT_OF_SYNC

以不恰当的顺序执行了命令。

·         CR_SERVER_GONE_ERROR

MySQL服务器不可用。

·         CR_SERVER_LOST

在查询过程中，与服务器的连接丢失。

·         CR_UNKNOWN_ERROR

出现未知错误。

示例：

if(mysql_create_db(&mysql, "my_database"))

{

   fprintf(stderr, "Failed to create new database.  Error: %s\n",

           mysql_error(&mysql));

}

void mysql_data_seek(MYSQL_RES *result, my_ulonglong offset)

描述

在查询结果集中寻找任意行。偏移值为行号，范围从0到mysql_num_rows(result)-1。

该函数要求结果集结构包含查询的所有结果，因此，so mysql_data_seek()仅 应与mysql_store_result()联合使用，而不是与mysql_use_result()。

返回值

无。

错误

无。

void mysql_debug(const char *debug)

描述

用给定的字符串执行DBUG_PUSH。mysql_debug()采用Fred Fish调试库。要想使用该函数，必须编译客户端库，使之支持调试功能。请参见E.1节，“调试MySQL服务器”。请参见E.2节，“调试MySQL客户端”。

返回值

无。

错误

无。

示例：

这里给出的调用将使客户端库在客户端机器的/tmp/client.trace中生成1个 跟踪文件。

mysql_debug("d:t:O,/tmp/client.trace");

int mysql_drop_db(MYSQL *mysql, const char *db)

描述

撤销由db参数命名数据库。

该函数已过时。最好使用mysql_query()来发出SQL DROP DATABASE语句

返回值

如果成功撤销了数据库，返回0。如果出现错误，返回非0值。

错误

·         CR_COMMANDS_OUT_OF_SYNC

以不恰当的顺序执行了命令。

·         CR_SERVER_GONE_ERROR

MySQL服务器不可用。

·         CR_SERVER_LOST

在查询过程中，与服务器的连接丢失。

·         CR_UNKNOWN_ERROR

出现未知错误。

示例：

if(mysql_drop_db(&mysql, "my_database"))

  fprintf(stderr, "Failed to drop the database: Error: %s\n",

          mysql_error(&mysql));

int mysql_dump_debug_info(MYSQL *mysql)

描述

指示服务器将一些调试信息写入日志。要想使之工作，已连接的用户必须具有SUPER权限。

返回值

如果命令成功，返回0。如果出现错误，返回非0值。

错误

·         CR_COMMANDS_OUT_OF_SYNC

以不恰当的顺序执行了命令。

·         CR_SERVER_GONE_ERROR

MySQL服务器不可用。

·         CR_SERVER_LOST

在查询过程中，与服务器的连接丢失。

·         CR_UNKNOWN_ERROR

出现未知错误。

my_bool mysql_eof(MYSQL_RES *result)

描述

该函数已过时。应使用mysql_errno()或mysql_error()取而代之。

mysql_eof()确定是否已读取了结果集的最后1行。

如果通过成功调用mysql_store_result()获得了结果集，客户端将在1次 操作中收到整个结果集。在该情况下，从mysql_fetch_row()返回的NULL总 表示已到达结果集末尾，而且没必要调用mysql_eof()。与mysql_store_result()一 起使用时，mysql_eof()总返回“真”。

另一方面，如果你使用mysql_use_result()来初始化结果集检索，当重复调用mysql_fetch_row()时， 将逐个地从服务器获取结果集的行。由于在该过程中，可能出现连接上的错误，从mysql_fetch_row()返回的NULL值 不一定表示已正常地抵达结果集末尾。在该情况下，可以使用mysql_eof()来判定出现了什么 情况。如果抵达结果集末尾，mysql_eof()返回非0值，如果出现错误，返回0。

从历史的角度上看，mysql_eof()在日期上早于标准的MySQL错 误函数mysql_errno()和mysql_error()。由于这类错误函数提供了相同的信 息，它们优先于已过时的mysql_eof()。事实上，它们提供了更多信息，这是因为，mysql_eof()仅 返回布尔值，错误函数能够在出现错误时指明错误的原因。

返回值

如果未出现错误，返回0。如果抵达结果集的末尾，返回非0值。

错误

无。

示例：

在下面的示例中，介绍了使用mysql_eof()的方法：

mysql_query(&mysql,"SELECT * FROM some_table");

result = mysql_use_result(&mysql);

while((row = mysql_fetch_row(result)))

{

    // do something with data

}

if(!mysql_eof(result))  // mysql_fetch_row() failed due to an error

{

    fprintf(stderr, "Error: %s\n", mysql_error(&mysql));

}

但是，你也能使用标准的MySQL错误函数实现相同的结果：

mysql_query(&mysql,"SELECT * FROM some_table");

result = mysql_use_result(&mysql);

while((row = mysql_fetch_row(result)))

{

    // do something with data

}

if(mysql_errno(&mysql))  // mysql_fetch_row() failed due to an error

{

    fprintf(stderr, "Error: %s\n", mysql_error(&mysql));

}

unsigned int mysql_errno(MYSQL *mysql)

描述

对于由mysql指定的连接，mysql_errno()返回最 近调用的API函数的错误代码，该函数调用可能成功也可能失败。“0”返回值表示未出现错误。在MySQL errmsg.h头文件中，列出了客户端错误消息编号。在附录B：错误代码和消息中，也列出了这些 错误。

注意，如果成功，某些函数，如mysql_fetch_row()等，不会设置mysql_errno()。

经验规则是，如果成功，所有向服务器请求信息的函数均会复位mysql_errno()。

返回值

如果失败，返回上次mysql_xxx()调用的错误代码。“0”表 示未出现错误。

错误

无。

const char *mysql_error(MYSQL *mysql)

描述

对于由mysql指定的连接，对于失败的最近调用的API函数，mysql_error()返 回包含错误消息的、由Null终结的字符串。如果该函数未失败，mysql_error()的 返回值可能是以前的错误，或指明无错误的空字符串。

经验规则是，如果成功，所有向服务器请求信息的函数均会复位mysql_error()。

对于复位mysql_errno()的函数，下述两个测试是等效的：

if(mysql_errno(&mysql))

{

    // an error occurred

}

if(mysql_error(&mysql)[0] != '\0')

{

    // an error occurred

}

通过重新编译MySQL客户端库，可以更改客户端错误消息的语言。目前，能够选择数种语言显示错误消息，请参见5.10.2节，“设置错误消息语言”。

返回值

返回描述错误的、由Null终结的字符串。如果未出现错误，返回空字符串。

错误

无。

应使用mysql_real_escape_string()取而代之！

该函数与mysql_real_escape_string()等同，但mysql_real_escape_string()会 将连接处理程序作为其第1个参量，并按照当前字符集对字符串进行转义处理。mysql_escape_string()不 采用连接参量，而且不考虑当前字符集设置。

MYSQL_FIELD *mysql_fetch_field(MYSQL_RES *result)

描述

返回采用MYSQL_FIELD结构的结果集的列。重复调用该函数，以检索关于结果集中所有 列的信息。未剩余字段时，mysql_fetch_field()返回NULL。

每次执行新的SELECT查询时，将复位mysql_fetch_field()， 以返回关于第1个字段的信息。调用mysql_field_seek()也会影响mysql_fetch_field()返 回的字段。

如果调用了mysql_query()以在表上执行SELECT，但 未调用mysql_store_result()，如果调用了mysql_fetch_field()以 请求BLOB字段的长度，MySQL将返回默认的Blob长 度（8KB）。之所以选择8KB是因为MySQL不知道BLOB的 最大长度。应在日后使其成为可配置的。一旦检索了结果集，field->max_length将 包含特定查询中该列的最大值的长度。

返回值

当前列的MYSQL_FIELD结构。如果未剩余任何列，返回NULL。

错误

无。

示例：

MYSQL_FIELD *field;

while((field = mysql_fetch_field(result)))

{

    printf("field name %s\n", field->name);

}

MYSQL_FIELD *mysql_fetch_field_direct(MYSQL_RES *result, unsigned int fieldnr)

描述

给定结果集内某1列的字段编号fieldnr，以MYSQL_FIELD结 构形式返回列的字段定义。可以使用该函数检索任意列的定义。Fieldnr的值应在从0到mysql_num_fields(result)-1的 范围内。

返回值

对于指定列，返回MYSQL_FIELD结构。

错误

无。

示例：

unsigned int num_fields;

unsigned int i;

MYSQL_FIELD *field;

num_fields = mysql_num_fields(result);

for(i = 0; i < num_fields; i++)

{

    field = mysql_fetch_field_direct(result, i);

    printf("Field %u is %s\n", i, field->name);

}

MYSQL_FIELD *mysql_fetch_fields(MYSQL_RES *result)

描述

对于结果集，返回所有MYSQL_FIELD结构的数组。每个结构提供了结果集中1列的字段 定义。

返回值

关于结果集所有列的MYSQL_FIELD结构的数组。

错误

无。

示例：

unsigned int num_fields;

unsigned int i;

MYSQL_FIELD *fields;

num_fields = mysql_num_fields(result);

fields = mysql_fetch_fields(result);

for(i = 0; i < num_fields; i++)

{

   printf("Field %u is %s\n", i, fields[i].name);

}

unsigned long *mysql_fetch_lengths(MYSQL_RES *result)

描述

返回结果集内当前行的列的长度。如果打算复制字段值，该长度信息有助于优化，这是因为，你能避免调用strlen()。 此外，如果结果集包含二进制数据，必须使用该函数来确定数据的大小，原因在于，对于包含Null字符的任何字 段，strlen()将返回错误的结果。

对于空列以及包含NULL值的列，其长度为0。要想了解区分这两类情况的方法，请参见关于mysql_fetch_row()的 介绍。

返回值

无符号长整数的数组表示各列的大小（不包括任何终结NULL字符）。如果出现错误，返回NULL。

错误

mysql_fetch_lengths()仅对结果集的当前行有效。如果在调用mysql_fetch_row()之 前或检索了结果集中的所有行后调用了它，将返回NULL。

示例：

MYSQL_ROW row;

unsigned long *lengths;

unsigned int num_fields;

unsigned int i;

row = mysql_fetch_row(result);

if (row)

{

    num_fields = mysql_num_fields(result);

    lengths = mysql_fetch_lengths(result);

    for(i = 0; i < num_fields; i++)

    {

         printf("Column %u is %lu bytes in length.\n", i, lengths[i]);

    }

}

MYSQL_ROW mysql_fetch_row(MYSQL_RES *result)

描述

检索结果集的下一行。在mysql_store_result()之后使用时，如果没有要检索的行，mysql_fetch_row()返 回NULL。在mysql_use_result()之后使用时，如果没有要检索的行 或出现了错误，mysql_fetch_row()返回NULL。

行内值的数目由mysql_num_fields(result)给出。如果行中保存了调用mysql_fetch_row()返 回的值，将按照row[0]到row[mysql_num_fields(result)-1]， 访问这些值的指针。行中的NULL值由NULL指针指明。

可以通过调用mysql_fetch_lengths()来获得行中字段值的长度。对于空字段以及包含NULL的 字段，长度为0。通过检查字段值的指针，能够区分它们。如果指针为NULL，字段为NULL， 否则字段为空。

返回值

下一行的MYSQL_ROW结构。如果没有更多要检索的行或出现了错误，返回NULL。

错误

注意，在对mysql_fetch_row()的两次调用之间，不会复位错误。

·         CR_SERVER_LOST

在查询过程中，与服务器的连接丢失。

·         CR_UNKNOWN_ERROR

出现未知错误。

示例：

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("\n");

}

unsigned int mysql_field_count(MYSQL *mysql)

描述

返回作用在连接上的最近查询的列数。

该函数的正常使用是在mysql_store_result()返回NULL（因 而没有结果集指针）时。在这种情况下，可调用mysql_field_count()来判定mysql_store_result()是 否应生成非空结果。这样，客户端就能采取恰当的动作，而无需知道查询是否是SELECT（或类似SELECT的） 语句。在这里给出的示例中，演示了完成它的方法。

请参见25.2.13.1 节，“为什么在mysql_query()返回成功后，mysql_store_result()有时会返回NULL”.

返回值

表示结果集中列数的无符号整数。

错误

无。

示例：

MYSQL_RES *result;

unsigned int num_fields;

unsigned int num_rows;

if (mysql_query(&mysql,query_string))

{

    // error

}

else // query succeeded, process any data returned by it

{

    result = mysql_store_result(&mysql);

    if (result)  // there are rows

    {

        num_fields = mysql_num_fields(result);

        // retrieve rows, then call mysql_free_result(result)

    }

    else  // mysql_store_result() returned nothing; should it have?

    {

        if(mysql_field_count(&mysql) == 0)

        {

            // query does not return data

            // (it was not a SELECT)

            num_rows = mysql_affected_rows(&mysql);

        }

        else // mysql_store_result() should have returned data

        {

            fprintf(stderr, "Error: %s\n", mysql_error(&mysql));

        }

    }

}

另一种可选的方法是，用mysql_errno(&mysql)替换mysql_field_count(&mysql)调 用。在该情况下，无论语句是否是SELECT，你将直接从mysql_store_result()查 找错误，而不是从mysql_field_count()的值进行推断。

MYSQL_FIELD_OFFSET mysql_field_seek(MYSQL_RES *result, MYSQL_FIELD_OFFSET offset)

描述

将字段光标设置到给定的偏移处。对mysql_fetch_field()的下一次调用将检索与该偏移相关 的列定义。

要想查找行的开始，请传递值为0的偏移量。

返回值

字段光标的前一个值。

错误

无。

MYSQL_FIELD_OFFSET mysql_field_tell(MYSQL_RES *result)

描述

返回上一个mysql_fetch_field()所使用的字段光标的定义。该值可用作mysql_field_seek()的 参量。

返回值

字段光标的当前偏移量。

错误

无。

void mysql_free_result(MYSQL_RES *result)

描述

释放由mysql_store_result()、mysql_use_result()、mysql_list_dbs()等 为结果集分配的内存。完成对结果集的操作后，必须调用mysql_free_result()释放 结果集使用的内存。

释放完成后，不要尝试访问结果集。

返回值

无。

错误

无。

void mysql_get_character_set_info(MYSQL *mysql, MY_CHARSET_INFO *cs)

描述

该函数提供了关于默认客户端字符集的信息。可以使用mysql_set_character_set()函 数更改默认的字符集。

该函数是在MySQL 5.0.10中增加的。

示例：

if (!mysql_set_character_set(&mysql, "utf8"))

{

    MY_CHARSET_INFO cs;

    mysql_get_character_set_info(&mysql, &cs);

    printf("character set information:\n");

    printf("character set name: %s\n", cs.name);

    printf("collation name: %s\n", cs.csname);

    printf("comment: %s\n", cs.comment);

    printf("directory: %s\n", cs.dir);

    printf("multi byte character min. length: %d\n", cs.mbminlen);

    printf("multi byte character max. length: %d\n", cs.mbmaxlen);

}

char *mysql_get_client_info(void)

描述

返回表示客户端库版本的字符串。

返回值

表示MySQL客户端库版本的字符串。

错误

无。

unsigned long mysql_get_client_version(void)

描述

返回表示客户端库版本的整数。该值的格式是XYYZZ，其中X是 主版本号，YY是发布级别，ZZ是发布级别内的版本号。例如，值40102表 示客户端库的版本是4.1.2。

返回值

表示MySQL客户端库版本的整数。

错误

无。

char *mysql_get_host_info(MYSQL *mysql)

描述

返回描述了所使用连接类型的字符串，包括服务器主机名。

返回值

代表服务器主机名和连接类型的字符串。

错误

无。

unsigned int mysql_get_proto_info(MYSQL *mysql)

描述

返回当前连接所使用的协议版本。

返回值

代表当前连接所使用协议版本的无符号整数。

错误

无。

char *mysql_get_server_info(MYSQL *mysql)

描述

返回代表服务器版本号的字符串。

返回值

代表服务器版本号的字符串。

错误

无。

unsigned long mysql_get_server_version(MYSQL *mysql)

描述

以整数形式返回服务器的版本号。

返回值

表示MySQL服务器版本的数值，格式如下：

major_version*10000 + minor_version *100 + sub_version

例如，对于5.0.12，返回500012。

在客户端程序中，为了快速确定某些与版本相关的服务器功能是否存在，该函数很有用。

错误

无。

unsigned long mysql_hex_string(char *to, const char *from, unsigned long length)

描述

该函数用于创建可用在SQL语句中的合法SQL字符串。请参见9.1.1 节，“字符串”。

该字符串从形式上编码为十六进制格式，每个字符编码为2个十六进制数。结果被置入其中，并添加1个 终结Null字节。

“from”所指向的字符串必须是长度字节“long”。必须为“to” 分配缓冲区，缓冲区至少为length*2+1字节长。当mysql_hex_string()返 回时，“to”的内容为由Null终结的字符串。返回值是编码字符串的长度，不包括 终结用Null字符。

可采用0xvalue或X'value'格式将返 回值置于SQL语句中。但是，返回值不包括0x或X'...'。 调用者必须提供所希望的格式是何种。

示例：

char query[1000],*end;

end = strmov(query,"INSERT INTO test_table values(");

end = strmov(end,"0x");

end += mysql_hex_string(end,"What's this",11);

end = strmov(end,",0x");

end += mysql_hex_string(end,"binary data: \0\r\n",16);

*end++ = ')';

if (mysql_real_query(&mysql,query,(unsigned int) (end - query)))

{

   fprintf(stderr, "Failed to insert row, Error: %s\n",

           mysql_error(&mysql));

}

示例中所使用的strmov()函数包含在mysqlclient库中，它 的工作方式类似于strcpy()，但返回指向第1个参数终结Null的 指针。

返回值

置于“to”中的值的长度，不包括终结用Null字符。

错误

无。

char *mysql_info(MYSQL *mysql)

描述

检索字符串，该字符串提供了关于最近执行查询的信息，但仅对这里列出的语句有效。对于其他语句，mysql_info()返 回NULL。字符串的格式取决于查询的类型，如本节所述。数值仅是说明性的，字符串包含与查询相适应的值。

·         INSERT INTO ... SELECT ...

字符串格式：记录，100；副本，0；警告，0

·         INSERT INTO ... VALUES (...),(...),(...)...

字符串格式：记录，3；副本，0；警告，0

·         LOAD DATA INFILE ...

字符串格式：记录，1；删除，0；跳过，0；警告，0

·         ALTER TABLE

字符串格式：记录，3；副本，0；警告，0

·         UPDATE

字符串格式：匹配行，40；更改，40；警告，0

注意，mysql_info()为INSERT ... VALUES返回非NULL值，INSERT ... VALUES仅用于多行形式的语句（也就是说，仅当指定了多个值列表时）。

返回值

字符串，它表示最近所执行查询的额外信息。如果该查询无可用信息，返回NULL。

错误

无。

MYSQL *mysql_init(MYSQL *mysql)

描述

分配或初始化与mysql_real_connect()相适应的MYSQL对 象。如果mysql是NULL指针，该函数将分配、初始 化、并返回新对象。否则，将初始化对象，并返回对象的地址。如果mysql_init()分配了新的对象，当调用mysql_close()来 关闭连接时。将释放该对象。

返回值

初始化的MYSQL*句柄。如果无足够内存以分配新的对象，返回NULL。

错误

在内存不足的情况下，返回NULL。

my_ulonglong mysql_insert_id(MYSQL *mysql)

描述

返回由以前的INSERT或UPDATE语句为AUTO_INCREMENT列 生成的值。在包含AUTO_INCREMENT字段的表中执行了INSERT语句后，应使用该函 数。

更准确地讲，将在下述条件下更新mysql_insert_id()：

·         将值保存到AUTO_INCREMENT列中的INSERT语句。无 论值是通过在列中存储特殊值NULL或0自动生成的，还是确切的非特殊值，都成立。

·         在 有多行INSERT语句的情况下，mysql_insert_id()返回第1个 自动生成的AUTO_INCREMENT值，如果未生成这类值，将返回插入在AUTO_INCREMENT列 中的最后1个确切值。

·         通过将LAST_INSERT_ID(expr)插入到任意列中以生成AUTO_INCREMENT值 的INSERT语句。

·         通过更新任意列至LAST_INSERT_ID(expr)以生成AUTO_INCREMENT值 的INSERT语句。

·         mysql_insert_id()的值不受诸如SELECT等返回 结果集的语句的影响。

·         如 果前面的语句返回了错误，mysql_insert_id()的值将是不确定的。

注意，如果前面的语句未使用AUTO_INCREMENT，mysql_insert_id()返 回0。如果需要保存值，在生成值的语句后，务必立刻调用mysql_insert_id()。

mysql_insert_id()的值仅受在当前客户端连接内发出的语句的影响。不受由其他客户端发出的 语句的影响。

请参见12.9.3节，“信息函数”。

此外还应注意，SQL LAST_INSERT_ID()函数的值总包含最近生成的AUTO_INCREMENT值， 而且在语句之间不会被复位，原因在于该函数的值是在服务器中维护的。另一个区别是，如果设置了AUTO_INCREMENT列 来指定非特殊值，不会更新LAST_INSERT_ID()。

LAST_INSERT_ID()不同于mysql_insert_id()的 原因在于，LAST_INSERT_ID()在脚本中很容易使用，而mysql_insert_id()则 试图提供关于在AUTO_INCREMENT列中出现情况的更准确信息。

返回值

在前面的讨论中予以了介绍。

错误

无。

int mysql_kill(MYSQL *mysql, unsigned long pid)

描述

请求服务器杀死由pid指定的线程。

返回值

0表示成功，非0值表示出现错误。

错误

·         CR_COMMANDS_OUT_OF_SYNC

以不恰当的顺序执行了命令。

·         CR_SERVER_GONE_ERROR

MySQL服务器不可用。

·         CR_SERVER_LOST

在查询过程中，与服务器的连接丢失。

·         CR_UNKNOWN_ERROR

出现未知错误。

void mysql_library_end(void)

描述

它是mysql_server_end()函数的同义词。

关于具体的用法，请参见25.2.2节，“C API函数概述”。

int mysql_library_init(int argc, char **argv, char **groups)

描述

这是mysql_server_init()函数的同义词。

关于具体的用法，请参见25.2.2节，“C API函数概述”。

MYSQL_RES *mysql_list_dbs(MYSQL *mysql, const char *wild)

描述

返回由服务器上的数据库名称组成的结果集，该服务器与由通配符参数指定的简单正则表达式匹配。通配符参数可以包含通配符“%” 或“_”，也可以是NULL指针，以便与所有的数据库匹配。调用mysql_list_dbs()的 方法类似于执行查询SHOW database [LIKE wild]。

必须用mysql_free_result()释放结果集。

返回值

成功后返回MYSQL_RES结果集。如果出现错误，返回NULL。

错误

·         CR_COMMANDS_OUT_OF_SYNC

以不恰当的顺序执行了命令。

·         CR_OUT_OF_MEMORY

内存溢出。

·         CR_SERVER_GONE_ERROR

MySQL服务器不可用。

·         CR_SERVER_LOST

在查询过程中，与服务器的连接丢失。

·         CR_UNKNOWN_ERROR

出现未知错误。

MYSQL_RES *mysql_list_fields(MYSQL *mysql, const char *table, const char *wild)

描述

返回由给定表中的字段名称组成的结果集，给定表与由通配符参数指定的简单正则表达式匹配。通配符参数可以包含通配符“%” 或“_”，也可以是NULL指针，以便与所有的字段匹配。调用mysql_list_fields()的 方法类似于执行查询SHOW COLUMNS FROM tbl_name [LIKE wild]。

注意，建议使用SHOW COLUMNS FROM tbl_name，而不是mysql_list_fields()。

必须用mysql_free_result()释放结果集。

返回值

如果成功，返回MYSQL_RES结果集。如果出现错误，返回NULL。

错误

·         CR_COMMANDS_OUT_OF_SYNC

以不恰当的顺序执行了命令。

·         CR_SERVER_GONE_ERROR

MySQL服务器不可用。

·         CR_SERVER_LOST

在查询过程中，与服务器的连接丢失。

·         CR_UNKNOWN_ERROR

出现未知错误。

MYSQL_RES *mysql_list_processes(MYSQL *mysql)

描述

返回描述当前服务器线程的结果集。该类信息与mysqladmin processlist或SHOW PROCESSLIST查询给出的信息相同。

必须用mysql_free_result()释放结果集。

返回值

如果成功，返回MYSQL_RES结果集。如果出现错误，返回NULL。

错误

·         CR_COMMANDS_OUT_OF_SYNC

以不恰当的顺序执行了命令。

·         CR_SERVER_GONE_ERROR

MySQL服务器不可用。

·         CR_SERVER_LOST

在查询过程中，与服务器的连接丢失。

·         CR_UNKNOWN_ERROR

出现未知错误。

MYSQL_RES *mysql_list_tables(MYSQL *mysql, const char *wild)

描述

返回由当前数据库内的表名组成的结果集，当前数据库与由通配符参数指定的简单正则表达式匹配。通配符参数可以包含通配符“%” 或“_”，也可以是NULL指针，以便与所有的表匹配。调用mysql_list_tables()的 方法类似于执行查询HOW tables [LIKE wild]。

必须用mysql_free_result()释放结果集。

返回值

如果成功，返回MYSQL_RES结果集。 如果出现错误，返回NULL。

错误

·         CR_COMMANDS_OUT_OF_SYNC

以不恰当的顺序执行了命令。

·         CR_SERVER_GONE_ERROR

MySQL服务器不可用。

·         CR_SERVER_LOST

在查询过程中，与服务器的连接丢失。

·         CR_UNKNOWN_ERROR

出现未知错误。

my_bool mysql_more_results(MYSQL *mysql)

描述

如果当前执行的查询存在多个结果，返回“真”，而且应用程序必须调用mysql_next_result()来 获取结果。

返回值

如果存在多个结果，返回“真”（1），如果不存在多 个结果，返回“假”（0）。

在大多数情况下，可调用mysql_next_result()来测试是否存在多个结果，如果存在多个结果，对检索进行 初始化操作。

请参见25.2.9节，“多查询 执行的C API处理”。请参见25.2.3.45节，“mysql_next_result()”。

错误

无。

int mysql_next_result(MYSQL *mysql)

描述

如果存在多个查询结果，mysql_next_result()将读取下一个查询结果，并将状态返回给应用 程序。

如果前面的查询返回了结果集，必须为其调用mysql_free_result()。

调用了mysql_next_result()后，连接状态就像你已为下一查询调用了mysql_real_query()或mysql_query()时 的一样。这意味着你能调用mysql_store_result()、mysql_warning_count()、mysql_affected_rows()等 等。

如果mysql_next_result()返回错误，将不执行任何其他语句，也不会获取任何更多的结果，

请参见25.2.9节，“多查询 执行的C API处理”。

返回值

错误

·         CR_COMMANDS_OUT_OF_SYNC

以不恰当的顺序执行了命令。例如，没有为前面的结果集调用mysql_use_result()。

·         CR_SERVER_GONE_ERROR

MySQL服务器不可用。

·         CR_SERVER_LOST

在查询过程中，与服务器的连接丢失。

·         CR_UNKNOWN_ERROR

出现未知错误。

unsigned int mysql_num_fields(MYSQL_RES *result)

要想传递MYSQL*参量取而代之，请使用无符号整数mysql_field_count(MYSQL *mysql)。

描述

返回结果集中的行数。

注意，你可以从指向结果集的指针或指向连接句柄的指针获得行数。如果mysql_store_result()或mysql_use_result()返 回NULL，应使用连接句柄（因而没有结果集指针）。在该情况下，可调用mysql_field_count()来 判断mysql_store_result()是否生成了非空结果。这样，客户端程序就能采取恰当的行动，而不需要知道查询是 否是SELECT语句（或类似SELECT的语句）。在下面的示例中， 介绍了执行该操作的方式。

请参见25.2.13.1 节，“为什么在mysql_query()返回成功后，mysql_store_result()有时会返回NULL”。

返回值

表示结果集中行数的无符号整数。

错误

无。

示例：

MYSQL_RES *result;

unsigned int num_fields;

unsigned int num_rows;

if (mysql_query(&mysql,query_string))

{

    // error

}

else // query succeeded, process any data returned by it

{

    result = mysql_store_result(&mysql);

    if (result)  // there are rows

    {

        num_fields = mysql_num_fields(result);

        // retrieve rows, then call mysql_free_result(result)

    }

    else  // mysql_store_result() returned nothing; should it have?

    {

        if (mysql_errno(&mysql))

        {

           fprintf(stderr, "Error: %s\n", mysql_error(&mysql));

        }

        else if (mysql_field_count(&mysql) == 0)

        {

            // query does not return data

            // (it was not a SELECT)

            num_rows = mysql_affected_rows(&mysql);

        }

    }

}

另一种可选方式是（如果你知道你的查询应返回结果集），使用检查“mysql_field_count(&mysql) is = 0”来替换mysql_errno(&mysql)调 用。仅当出错时才应使用它。

my_ulonglong mysql_num_rows(MYSQL_RES *result)

描述

返回结果集中的行数。

mysql_num_rows()的使用取决于是否采用了mysql_store_result()或mysql_use_result()来 返回结果集。如果使用了mysql_store_result()，可以立刻调用mysql_num_rows()。 如果使用了mysql_use_result()，mysql_num_rows()不返回正确的 值，直至检索了结果集中的所有行为止。

返回值

结果集中的行数。

错误

无。

int mysql_options(MYSQL *mysql, enum mysql_option option, const char *arg)

描述

可用于设置额外的连接选项，并影响连接的行为。可多次调用该函数来设置数个选项。

应在mysql_init()之后、以及mysql_connect()或mysql_real_connect()之 前调用mysql_options()。

选项参量指的是你打算设置的选项。Arg参量是选项的值。如果选项是整数，那么arg应 指向整数的值。

可能的选项值：

注意，如果使用了MYSQL_READ_DEFAULT_FILE或MYSQL_READ_DEFAULT_GROUP， 总会读取客户端组。

选项文件中指定的组可能包含下述选项：

注意，“timeout”（超时）已被“connect-timeout”（连 接超时）取代，但为了保持向后兼容，在MySQL 5.1.2-alpha中仍支持“timeout”（超 时）。

关于选项文件的更多信息，请参见4.3.2节，“使用选项文件”。

返回值

成功时返回0。如果使用了未知选项，返回非0值。

示例：

MYSQL mysql;

mysql_init(&mysql);

mysql_options(&mysql,MYSQL_OPT_COMPRESS,0);

mysql_options(&mysql,MYSQL_READ_DEFAULT_GROUP,"odbc");

if (!mysql_real_connect(&mysql,"host","user","passwd","database",0,NULL,0))

{

    fprintf(stderr, "Failed to connect to database: Error: %s\n",

          mysql_error(&mysql));

}

该代码请求客户端使用压缩客户端／服务器协议，并从my.cnf文件的obdc部 分读取额外选项。

int mysql_ping(MYSQL *mysql)

描述

检查与服务器的连接是否工作。如果连接丢失，将自动尝试再连接。

该函数可被闲置了较长时间的客户端使用，用以检查服务器是否已关闭了连接，并在必要时再次连接。

返回值

如果与服务器的连接有效返回0。如果出现错误，返回非0值。返回的非0值 不表示MySQL服务器本身是否已关闭，连接可能因其他原因终端，如网络问题等。

错误

·         CR_COMMANDS_OUT_OF_SYNC

以不恰当的顺序执行了命令。

·         CR_SERVER_GONE_ERROR

MySQL服务器不可用。

·         CR_UNKNOWN_ERROR

出现未知错误。

int mysql_query(MYSQL *mysql, const char *query)

描述

执行由“Null终结的字符串”查询指向的SQL查询。正常情况下，字符串必须包含1条SQL语 句，而且不应为语句添加终结分号（‘;’）或“\g”。如果允许多语句执行，字 符串可包含多条由分号隔开的语句。请参见25.2.9节，“多查询 执行的C API处理”。

mysql_query()不能用于包含二进制数据的查询，应使用mysql_real_query()取 而代之（二进制数据可能包含字符‘\0’，mysql_query()会将该字符解释 为查询字符串结束）。

如果希望了解查询是否应返回结果集，可使用mysql_field_count()进行检查。请参见25.2.3.22节，“mysql_field_count()”。

返回值

如果查询成功，返回0。如果出现错误，返回非0值。

错误

·         CR_COMMANDS_OUT_OF_SYNC

以不恰当的顺序执行了命令。

·         CR_SERVER_GONE_ERROR

MySQL服务器不可用。

·         CR_SERVER_LOST

在查询过程中，与服务器的连接丢失。

·         CR_UNKNOWN_ERROR

出现未知错误。

MYSQL *mysql_real_connect(MYSQL *mysql, const char *host, const char *user, const char *passwd, const char *db, unsigned int port, const char *unix_socket, unsigned long client_flag)

描述

mysql_real_connect()尝试与运行在主机上的MySQL数据库引擎建立 连接。在你能够执行需要有效MySQL连接句柄结构的任何其他API函数之前，mysql_real_connect()必 须成功完成。

参数的指定方式如下：

·         第1个 参数应是已有MYSQL结构的地址。调用mysql_real_connect()之 前，必须调用mysql_init()来初始化MYSQL结构。通过mysql_options()调 用，可更改多种连接选项。请参见25.2.3.48节，“mysql_options()”。

·         “host” 的值必须是主机名或IP地址。如果“host”是NULL或 字符串"localhost"，连接将被视为与本地主机的连接。如果操作系统支持套接字（Unix） 或命名管道（Windows），将使用它们而不是TCP/IP连接到服务器。

·         “user”参 数包含用户的MySQL登录ID。如果“user”是NULL或 空字符串""，用户将被视为当前用户。在UNIX环境下，它是当前的登录名。在Windows ODBC下，必须明确指定当前用户名。请参见26.1.9.2节，“在 Windows上配置MyODBC DSN”。

·         “passwd”参 数包含用户的密码。如果“passwd”是NULL，仅 会对该用户的（拥有1个空密码字段的）用户表中的条目进行匹配检查。这样，数据库管理员就能按特定的方式设置MySQL权 限系统，根据用户是否拥有指定的密码，用户将获得不同的权限。

注释：调用mysql_real_connect()之 前，不要尝试加密密码，密码加密将由客户端API自动处理。

·         “db”是 数据库名称。如果db为NULL，连接会将默认的数据库设为该值。

·         如 果“port”不是0，其值将用作TCP/IP连 接的端口号。注意，“host”参数决定了连接的类型。

·         如 果unix_socket不是NULL，该字符串描述了应使用的套接字或命名管道。注意，“host” 参数决定了连接的类型。

·         client_flag的值通常为0，但是，也能将其设置为下述标志 的组合，以允许特定功能：

对于某些参数，能够从选项文件获得取值，而不是取得mysql_real_connect()调用中的确切 值。为此，在调用mysql_real_connect()之前，应与MYSQL_READ_DEFAULT_FILE或MYSQL_READ_DEFAULT_GROUP选 项一起调用mysql_options()。随后，在mysql_real_connect()调 用中，为准备从选项文件读取值的每个参数指定“无值”值：

·         对 于host，指定NULL值或空字符串("")。

·         对 于user，指定NULL值或空字符串。

·         对 于passwd，指定NULL值。（对于密码，mysql_real_connect()调 用中的空字符串的值不能被选项文件中的字符串覆盖，这是因为，空字符串明确指明MySQL账户必须有空密码）。

·         对 于db，指定NULL值或空字符串

·         对 于port，指定“0”值。

·         对 于unix_socket，指定NULL值。

对于某一参数，如果在选项文件中未发现值，将使用它的默认值，如本节前面介绍的那样。

返回值

如果连接成功，返回MYSQL*连接句柄。如果连接失败，返回NULL。对于成 功的连接，返回值与第1个参数的值相同。

错误

·         CR_CONN_HOST_ERROR

无法连接到MySQL服务器。

·         CR_CONNECTION_ERROR

无法连接到本地MySQL服务器。

·         CR_IPSOCK_ERROR

无法创建IP套接字。

·         CR_OUT_OF_MEMORY

内存溢出。

·         CR_SOCKET_CREATE_ERROR

无法创建Unix套接字。

·         CR_UNKNOWN_HOST

无法找到主机名的IP地址。

·         CR_VERSION_ERROR

协议不匹配，起因于：试图连接到具有特定客户端库（该客户端库使用了不同的协议版本）的服务器。如果使用很早的客户端库来建立与较新的服务器（未使用“--old-protocol” 选项开始的）的连接，就会出现该情况。

·         CR_NAMEDPIPEOPEN_ERROR

无法在Windows平台下创建命名管道。

·         CR_NAMEDPIPEWAIT_ERROR

在Windows平台下等待命名管道失败。

·         CR_NAMEDPIPESETSTATE_ERROR

在Windows平台下获取管道处理程序失败。

·         CR_SERVER_LOST

如果connect_timeout > 0，而且在连接服务器时所用时间长于connect_timeout秒， 或在执行init-command时服务器消失。

示例：

MYSQL mysql;

mysql_init(&mysql);

mysql_options(&mysql,MYSQL_READ_DEFAULT_GROUP,"your_prog_name");

if (!mysql_real_connect(&mysql,"host","user","passwd","database",0,NULL,0))

{

    fprintf(stderr, "Failed to connect to database: Error: %s\n",

          mysql_error(&mysql));

}

通过使用mysql_options()，MySQL库将读取my.cnf文 件的[client]和[your_prog_name]部分，以确保程序工作，即 使某人以某种非标准的方式设置MySQL也同样。

注意，一旦建立了连接，mysql_real_connect()将设置再连接标志（MYSQL结 构的组成部份）的值，在低于5.0.3版的API中，将其设为“1”， 在较新的版本中，将其设为“0”。对于该标志，值“1”表示，如果因连接丢失而无法执行语句，放弃 前，将尝试再次连接到服务器。从MySQL 5.0.13开始，可以对mysql_options()使 用MYSQL_OPT_RECONNECT选项，对再连接行为进行控制。

unsigned long mysql_real_escape_string(MYSQL *mysql, char *to, const char *from, unsigned long length)

注意，mysql必须是有效的开放式连接。之所以需要它是因为，转义功能取决于服务器使用的 字符集。

描述

该函数用于创建可在SQL语句中使用的合法SQL字符串。请参见9.1.1 节，“字符串”。

按照连接的当前字符集，将“from”中的字符串编码为转义SQL字符串。将结果置于“to”中， 并添加1个终结用NULL字节。编码的字符为NUL (ASCII 0)、‘\n’、‘\r’、‘\’、‘'’、 ‘"’、以及Control-Z（请参见9.1 节，“文字值”）。（严格地讲，MySQL仅需要反斜杠和引号字符，用于引用转义查询中的字符串。该函数能引用其他字 符，从而使得它们在日志文件中具有更好的可读性）。

“from”指向的字符串必须是长度字节“long”。必须为“to” 缓冲区分配至少length*2+1字节。在最坏的情况下，每个字符或许需要使用2个 字节进行编码，而且还需要终结Null字节。当mysql_real_escape_string()返 回时，“to”的内容是由Null终结的字符串。返回值是编码字符串的长度，不包括 终结用Null字符。

如果需要更改连接的字符集，应使用mysql_set_character_set()函数，而不是执行SET NAMES (或SET CHARACTER SET)语 句。mysql_set_character_set()的工作方式类似于SET NAMES， 但它还能影响mysql_real_escape_string()所使用的字符集，而SET NAMES则 不能。

示例：

char query[1000],*end;

end = strmov(query,"INSERT INTO test_table values(");

*end++ = '\'';

end += mysql_real_escape_string(&mysql, end,"What's this",11);

*end++ = '\'';

*end++ = ',';

*end++ = '\'';

end += mysql_real_escape_string(&mysql, end,"binary data: \0\r\n",16);

*end++ = '\'';

*end++ = ')';

if (mysql_real_query(&mysql,query,(unsigned int) (end - query)))

{

   fprintf(stderr, "Failed to insert row, Error: %s\n",

           mysql_error(&mysql));

}

该示例中使用的strmov()函数包含在mysqlclient库中，工作方 式与strcpy()类似，但会返回指向第1个参数终结用Null的 指针。

返回值

置于“to”中的值的长度，不包括终结用Null字符。

错误

无。

int mysql_real_query(MYSQL *mysql, const char *query, unsigned long length)

描述

执行由“query”指向的SQL查询，它应是字符串长度字节“long”。 正常情况下，字符串必须包含1条SQL语句，而且不应为语句添加终结分 号（‘;’）或“\g”。如果允许多语句执行，字符串可包含由分号隔开的多条语句。请参见25.2.9节，“多查询 执行的C API处理”。

对于包含二进制数据的查询，必须使用mysql_real_query()而不是mysql_query()， 这是因为，二进制数据可能会包含‘\0’字符。此外，mysql_real_query()比mysql_query()快， 这是因为它不会在查询字符串上调用strlen()。

如果希望知道查询是否应返回结果集，可使用mysql_field_count()进行检查25.2.3.22节，“mysql_field_count()”。

返回值

如果查询成功，返回0。如果出现错误，返回非0值。

错误

·         CR_COMMANDS_OUT_OF_SYNC

以不恰当的顺序执行了命令。

·         CR_SERVER_GONE_ERROR

MySQL服务器不可用。

·         CR_SERVER_LOST

在查询过程中，与服务器的连接丢失。

·         CR_UNKNOWN_ERROR

出现未知错误。

int mysql_refresh(MYSQL *mysql, unsigned int options)

描述

该函数用于刷新表或高速缓冲，或复位复制服务器信息。连接的用户必须具有RELOAD权限。

“options”参量是一种位掩码，由下述值的任意组合构成。能够以“Or” （或）方式将多个值组合在一起，用一次调用执行多项操作。

·         REFRESH_GRANT

刷新授权表，与FLUSH PRIVILEGES类似。

·         REFRESH_LOG

刷新日志，与FLUSH LOGS类似。

·         REFRESH_TABLES

刷新表高速缓冲，与FLUSH TABLES类似。

·         REFRESH_HOSTS

刷新主机高速缓冲，与FLUSH HOSTS类似。

·         REFRESH_STATUS

复位状态变量，与FLUSH STATUS类似。

·         REFRESH_THREADS

刷新线程高速缓冲。

·         REFRESH_SLAVE

在从复制服务器上，复位主服务器信息，并重新启动从服务器，与RESET SLAVE类似。

·         REFRESH_MASTER

在主复制服务器上，删除二进制日志索引中列出的二进制日志文件，并截短索引文件，与RESET MASTER类似。

返回值

0表示成功，非0值表示出现错误。

错误

·         CR_COMMANDS_OUT_OF_SYNC

以不恰当的顺序执行了命令。

·         CR_SERVER_GONE_ERROR

MySQL服务器不可用。

·         CR_SERVER_LOST

在查询过程中，与服务器的连接丢失。

·         CR_UNKNOWN_ERROR

出现未知错误。

int mysql_reload(MYSQL *mysql)

描述

请求MySQL服务器重新加载授权表。连接的用户必须具有RELOAD权限。

该函数已过时。最好使用mysql_query()来发出SQL FLUSH PRIVILEGES语句。

返回值

0表示成功，非0值表示出现错误。

错误

·         CR_COMMANDS_OUT_OF_SYNC

以不恰当的顺序执行了命令。

·         CR_SERVER_GONE_ERROR

MySQL服务器不可用。

·         CR_SERVER_LOST

在查询过程中，与服务器的连接丢失。

·         CR_UNKNOWN_ERROR

出现未知错误。

my_bool mysql_rollback(MYSQL *mysql)

描述

回滚当前事务。

该函数的动作取决于completion_type系统变量的值。尤其是，如果completion_type的 值为“2”，终结事务后，服务器将执行释放操作，并关闭客户端连接。客户端程序应调用mysql_close()，从 客户端一侧关闭连接。

返回值

如果成功，返回0，如果出现错误，返回非0值。

错误

无。

MYSQL_ROW_OFFSET mysql_row_seek(MYSQL_RES *result, MYSQL_ROW_OFFSET offset)

描述

将行光标置于查询结果集中的任意行。“offset”值是行偏移量，它应是从mysql_row_tell()或mysql_row_seek()返 回的值。该值不是行编号，如果你打算按编号查找结果集中的行，请使用mysql_data_seek()。

该函数要求在结果集的结构中包含查询的全部结果，因此，mysql_row_seek()仅应与mysql_store_result()一 起使用，而不是与mysql_use_result()。

返回值

行光标的前一个值。该值可传递给对mysql_row_seek()的后续调用。

错误

无。

MYSQL_ROW_OFFSET mysql_row_tell(MYSQL_RES *result)

描述

对于上一个mysql_fetch_row()，返回行光标的当前位置。该值可用作mysql_row_seek()的 参量。

仅应在mysql_store_result()之后，而不是mysql_use_result()之 后使用mysql_row_tell()。

返回值

行光标的当前偏移量。

错误

无。

int mysql_select_db(MYSQL *mysql, const char *db)

描述

使由db指定的数据库成为由mysql指定的连接上的默认数据库 （当前数据库）。在后续查询中，该数据库将是未包含明确数据库区分符的表引用的默认数据库。

除非已连接的用户具有使用数据库的权限，否则mysql_select_db()将失败。

返回值

0表示成功，非0值表示出现错误。

错误

·         CR_COMMANDS_OUT_OF_SYNC

以不恰当的顺序执行了命令。

·         CR_SERVER_GONE_ERROR

MySQL服务器不可用。

·         CR_SERVER_LOST

在查询过程中，与服务器的连接丢失。

·         CR_UNKNOWN_ERROR

出现未知错误。

int mysql_set_character_set(MYSQL *mysql, char *csname)

描述

该函数用于为当前连接设置默认的字符集。字符串csname指定了1个有效的字符集名称。连 接校对成为字符集的默认校对。该函数的工作方式与SET NAMES语句类似，但它还能设置mysql->charset的 值，从而影响了由mysql_real_escape_string()设置的字符集。

该函数是在MySQL 5.0.7中增加的。

返回值

0表示成功，非0值表示出现错误。

示例：

MYSQL mysql;

mysql_init(&mysql);

if (!mysql_real_connect(&mysql,"host","user","passwd","database",0,NULL,0))

{

    fprintf(stderr, "Failed to connect to database: Error: %s\n",

          mysql_error(&mysql));

}

if (!mysql_set_charset_name(&mysql, "utf8")) 

{

    printf("New client character set: %s\n", mysql_character_set_name(&mysql));

}

int mysql_set_server_option(MYSQL *mysql, enum enum_mysql_set_option option)

描述

允许或禁止连接的选项。选项可以取下述值之一：

返回值

0表示成功，非0值表示出现错误。

错误

·         CR_COMMANDS_OUT_OF_SYNC

以不恰当的顺序执行了命令。

·         CR_SERVER_GONE_ERROR

MySQL服务器不可用。

·         CR_SERVER_LOST

在查询过程中，与服务器的连接丢失。

·         ER_UNKNOWN_COM_ERROR

服务器不支持mysql_set_server_option()（当服务器版本低于4.1.1时）， 或服务器不支持试图设置的选项。

int mysql_shutdown(MYSQL *mysql, enum enum_shutdown_level shutdown_level)

描述

请求数据库服务器关闭。已连接的用户必须具有SHUTDOWN权限。MySQL 5.1服务 器仅支持1种关闭类型，shutdown_level必须等效于 SHUTDOWN_DEFAULT。设计规划了额外的关闭级别，以便能够选择所需的级别。对于用旧版本libmysqlclient头 文件编译并调用mysql_shutdown()的动态链接可执行程序，需要与旧版的libmysqlclient动 态库一起使用。

在5.5节，“MySQL服务器关机进程”中， 介绍了关机进程。

返回值

0表示成功，非0值表示出现错误。

错误

·         CR_COMMANDS_OUT_OF_SYNC

以不恰当的顺序执行了命令。

·         CR_SERVER_GONE_ERROR

MySQL服务器不可用。

·         CR_SERVER_LOST

在查询过程中，与服务器的连接丢失。

·         CR_UNKNOWN_ERROR

出现未知错误。

const char *mysql_sqlstate(MYSQL *mysql)

描述

返回由Null终结的字符串，该字符串包含关于上次错误的SQLSTATE错误代码。错误代 码包含5个字符。'00000'表示无错误。其值由ANSI SQL和ODBC指定。关于可能取值的列表，请参见附录B：错误代码和消息。

注意，并非所有的MySQL错误均会被映射到SQLSTATE错误代码。值'HY000'（一 般错误）用于未映射的错误。

返回值

包含SQLSTATE错误码的、由Null终结的字符串。

另请参见：

请参见25.2.3.14 节，“mysql_errno()”。请参见25.2.3.15节，“mysql_error()”。请参见25.2.7.26节， “mysql_stmt_sqlstate()”。

int mysql_ssl_set(MYSQL *mysql, const char *key, const char *cert, const char *ca, const char *capath, const char *cipher)

描述

使用mysql_ssl_set()，可采用SSL建立安全连接。必须在mysql_real_connect()之 前调用它。

除非在客户端库中允许了OpenSSL支持，否则mysql_ssl_set()不 作任何事。

Mysql是从mysql_init()返回的连接处理程序。其 他参数的指定如下：

·         key是key文 件的路径名。

·         cert是 证书文件的路径名。

·         ca是 证书授权文件的路径名。

·         capath是指向目录的路径名，该目录中包含以pem格式给出的受信任SSL CA证书。

·         cipher是允许密码的列表，用于SSL加密。

对于任何未使用的SSL参数，可为其给定NULL。

返回值

该函数总返回0。如果SSL设置不正确，当你尝试连接时，mysql_real_connect()将 返回错误。

char *mysql_stat(MYSQL *mysql)

描述

返回包含特定信息的字符串，该信息与mysqladmin status命令提供的 信息类似。包括以秒为单位的正常运行时间，以及运行线程的数目，问题数，再加载次数，以及打开的表数目。

返回值

描述服务器状态的字符集。如果出现错误，返回NULL。

错误

·         CR_COMMANDS_OUT_OF_SYNC

以不恰当的顺序执行了命令。

·         CR_SERVER_GONE_ERROR

MySQL服务器不可用。

·         CR_SERVER_LOST

在查询过程中，与服务器的连接丢失。

·         CR_UNKNOWN_ERROR

出现未知错误。

MYSQL_RES *mysql_store_result(MYSQL *mysql)

描述

对于成功检索了数据的每个查询（SELECT、SHOW、DESCRIBE、EXPLAIN、CHECK TABLE等），必须调用mysql_store_result()或mysql_use_result() 。

对于其他查询，不需要调用mysql_store_result()或mysql_use_result()， 但是如果在任何情况下均调用了mysql_store_result()，它也不会导致任何伤害或 性能降低。通过检查mysql_store_result()是否返回0，可检测查询 是否没有结果集（以后会更多）。

如果希望了解查询是否应返回结果集，可使用mysql_field_count()进行检查。请参见25.2.3.22节，“mysql_field_count()”。

mysql_store_result()将查询的全部结果读取到客户端，分配1个MYSQL_RES结 构，并将结果置于该结构中。

如果查询未返回结果集，mysql_store_result()将返回Null指 针（例如，如果查询是INSERT语句）。

如果读取结果集失败，mysql_store_result()还会返回Null指 针。通过检查mysql_error()是否返回非空字符串，mysql_errno()是 否返回非0值，或mysql_field_count()是否返回0， 可以检查是否出现了错误。

如果未返回行，将返回空的结果集。（空结果集设置不同于作为返回值的空指针）。

一旦调用了mysql_store_result()并获得了不是Null指针 的结果，可调用mysql_num_rows()来找出结果集中的行数。

可以调用mysql_fetch_row()来获取结果集中的行，或调用mysql_row_seek()和mysql_row_tell()来 获取或设置结果集中的当前行位置。

一旦完成了对结果集的操作，必须调用mysql_free_result()。

请参见25.2.13.1 节，“为什么在mysql_query()返回成功后，mysql_store_result()有时会返回NULL”.

返回值

具有多个结果的MYSQL_RES结果集合。如果出现错误，返回NULL。

错误

如果成功，mysql_store_result()将复位mysql_error()和mysql_errno()。

·         CR_COMMANDS_OUT_OF_SYNC

以不恰当的顺序执行了命令。

·         CR_OUT_OF_MEMORY

内存溢出。

·         CR_SERVER_GONE_ERROR

MySQL服务器不可用。

·         CR_SERVER_LOST

在查询过程中，与服务器的连接丢失。

·         CR_UNKNOWN_ERROR

出现未知错误。

unsigned long mysql_thread_id(MYSQL *mysql)

描述

返回当前连接的线程ID。该值可用作mysql_kill()的参量以杀死线 程。

如果连接丢失，并使用mysql_ping()进行了再连接，线程ID将 改变。这意味着你不应获取线程ID并保存它供以后使用。应在需要时获取它。

返回值

当前连接的线程ID。

错误

无。

MYSQL_RES *mysql_use_result(MYSQL *mysql)

描述

对于成功检索数据的每个查询（SELECT、SHOW、DESCRIBE、EXPLAIN）， 必须调用mysql_store_result()或mysql_use_result()。

mysql_use_result()将初始化结果集检索，但并不像mysql_store_result()那 样将结果集实际读取到客户端。它必须通过对mysql_fetch_row()的调用，对每一行分 别进行检索。这将直接从服务器读取结果，而不会将其保存在临时表或本地缓冲区内，与mysql_store_result()相 比，速度更快而且使用的内存也更少。客户端仅为当前行和通信缓冲区分配内存，分配的内存可增加到max_allowed_packet字 节。

另一方面，如果你正在客户端一侧为各行进行大量的处理操作，或者将输出发送到了用户可能会键入“^S”（停止滚动）的屏 幕，就不应使用mysql_use_result()。这会绑定服务器，并阻止其他线程更新任何表（数据从这类表获得）。

使用mysql_use_result()时，必须执行mysql_fetch_row()， 直至返回NULL值，否则，未获取的行将作为下一个检索的一部分返回。C API给 出命令不同步错误，如果忘记了执行该操作，将不能运行该命令。

不应与从mysql_use_result()返回的结果一起使用mysql_data_seek()、mysql_row_seek()、mysql_row_tell()、mysql_num_rows()或mysql_affected_rows()， 也不应发出其他查询，直至mysql_use_result()完成为止。（但是，提取了所有行后，mysql_num_rows()将 准确返回提取的行数）。

一旦完成了对结果集的操作，必须调用mysql_free_result()。

使用libmysqld嵌入式服务器时，由于在调用mysql_free_result()之 前，内存使用将随着每个检索的行增加，内存效益将基本丧失。

返回值

MYSQL_RES结果结构。如果出现错误，返回NULL。

错误

如果成功，mysql_use_result()将复位mysql_error()和mysql_errno()。

·         CR_COMMANDS_OUT_OF_SYNC

以不恰当的顺序执行了命令。

·         CR_OUT_OF_MEMORY

内存溢出。

·         CR_SERVER_GONE_ERROR

MySQL服务器不可用。

·         CR_SERVER_LOST

在查询过程中，与服务器的连接丢失。

·         CR_UNKNOWN_ERROR

出现未知错误。