C API函数描述(G-N)

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()不返回正确的值，直至检索了结果集中的所有行为止。

返回值

结果集中的行数。

错误

无。