MySQL API

MySql5.1 C API函數描述

[1] mysql_affected_rows()

定義函數    my_ulonglong mysql_affected_rows(MYSQL *mysql)

功能     返回sql執行後影響到的行數。

返回值   影響或檢索的行數。

錯誤     無。

示例：

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

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

[2] mysql_autocommit()

定義函數    my_bool mysql_autocommit(MYSQL *mysql, my_bool mode)

功能        若是模式爲「1」，啓用autocommit模式；若是模式爲「0」，禁止autocommit模式。

返回值      若是返回0，錯誤返回非0值。

[3] mysql_change_user()

定義函數    my_bool mysql_change_user(MYSQL *mysql, const char *user, const char *password, const char *db)

功能        更改用戶，並使由db指定的數據庫成爲由mysql指定的鏈接上的默認數據庫（當前數據庫）。

返回值      0表示成功，非0值表示出現錯誤。

示例：

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

{

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

           mysql_error(&mysql));

}

[4] mysql_character_set_name()

定義函數    const char *mysql_character_set_name(MYSQL *mysql)

功能        爲當前鏈接返回默認的字符集。

返回值      默認字符集。

[5] mysql_close()

void mysql_close(MYSQL *mysql)

功能      關閉前面打開的鏈接。若是句柄是由mysql_init()或mysql_connect()自動分配的，mysql_close()還將解除分配由mysql指向的鏈接句柄。

返回值     無。

[6] mysql_commit()

定義函數    my_bool mysql_commit(MYSQL *mysql)

功能      提交當前事務。

返回值   成功返回0，錯誤返回非0值。

[7] mysql_connect()

定義函數    MYSQL *mysql_connect(MYSQL *mysql, const char *host, const char *user, const char *passwd)

功能      該函數已過期。最好使用mysql_real_connect()取而代之。

返回值   與mysql_real_connect()的相同。

[8] mysql_create_db()

定義函數    int mysql_create_db(MYSQL *mysql, const char *db)

功能      建立db參數命名的數據庫。該函數過期。最好用mysql_query()來發出CREATE DATABASE語句。

返回值   成功返回0，錯誤返回非0值。

示例：

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

{

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

           mysql_error(&mysql));

}

[9] mysql_data_seek()

定義函數    void mysql_data_seek(MYSQL_RES *result, my_ulonglong offset)

功能      在查詢結果集中尋找任意行。偏移值爲行號，範圍從0到mysql_num_rows(result)-1。

返回值    無。

[10] mysql_debug()

定義函數    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");

 

[11] mysql_drop_db()

定義函數    int mysql_drop_db(MYSQL *mysql, const char *db)

功能      撤銷由db參數命名數據庫。 該函數已過期。最好用mysql_query()來刪除數據庫

返回值    若是成功撤銷了數據庫，返回0。若是出現錯誤，返回非0值。

示例：

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

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

          mysql_error(&mysql));

[12] mysql_dump_debug_info()

定義函數    int mysql_dump_debug_info(MYSQL *mysql)

功能       指示服務器將一些調試信息寫入日誌。要想使之工做，已鏈接的用戶必須具備SUPER權限。

返回值     若是命令成功，返回0。若是出現錯誤，返回非0值。

[13] mysql_eof()

定義函數    my_bool mysql_eof(MYSQL_RES *result)

功能      mysql_eof()肯定是否讀取到結果集最後1行。該函數已過期。應使用mysql_errno()或mysql_error()取而代之。

函數說明  

若是經過成功調用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。

返回值    錯誤返回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));

}

[14] mysql_errno()

定義函數    unsigned int mysql_errno(MYSQL *mysql)

功能    mysql_errno()返回最近調用的API函數的錯誤代碼，該函數調用可能成功也可能失敗。「0」返回值表示未出現錯誤。在MySQL errmsg.h頭文件中，列出了客戶端錯誤消息編號。

注意   若是成功，某些函數，如mysql_fetch_row()等，不會設置mysql_errno()。

經驗規則是，若是成功，全部向服務器請求信息的函數均會復位mysql_errno()。

返回值   失敗，返回上次mysql_xxx()調用的錯誤代碼。「0」表示未出現錯誤。

[15] mysql_error()

定義函數    const char *mysql_error(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

}

返回值

返回描述錯誤的、由Null終結的字符串。若是未出現錯誤，返回空字符串。

[16] mysql_escape_string()

應使用mysql_real_escape_string()取而代之！

該函數與mysql_real_escape_string()等同，但mysql_real_escape_string()會將鏈接處理程序做爲其第1個參量，並按照當前字符集對字符串進行轉義處理。mysql_escape_string()不採用鏈接參量，並且不考慮當前字符集設置。

[17] mysql_fetch_field()

定義函數    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_FIELD結構。若是未剩餘任何列，返回NULL。

示例：

MYSQL_FIELD *field;

 

while((field = mysql_fetch_field(result)))

{

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

}

[18] mysql_fetch_field_direct()

定義函數    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);

}

[19] mysql_fetch_fields()

定義函數    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);

}

[20] mysql_fetch_lengths()

定義函數    unsigned long *mysql_fetch_lengths(MYSQL_RES *result)

功能    返回結果集內當前行的列的長度。若是打算複製字段值，該長度信息有助於優化，這是由於，你能避免調用strlen()。此外，若是結果集包含二進制數據，必須使用該函數來肯定數據的大小，緣由在於，對於包含Null字符的任何字段，strlen()將返回錯誤的結果。

對於空列以及包含NULL值的列，其長度爲0。要想了解區分這兩類狀況的方法，請參見關於mysql_fetch_row()的介紹。

返回值  無符號長整數的數組表示各列的大小（不包括任何終結NULL字符）。若是出現錯誤，返回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]);

    }

}

 

[21] mysql_fetch_row()

定義函數    MYSQL_ROW mysql_fetch_row(MYSQL_RES *result)

功能   檢索結果集的下一行。

返回值 下一行的MYSQL_ROW結構。若是沒有更多要檢索的行或出現了錯誤，返回NULL。

示例：

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");

}

[22] mysql_field_count()

定義函數    unsigned int mysql_field_count(MYSQL *mysql)

功能   返回做用在鏈接上的最近查詢的列數。

函數說明 該函數的正常使用是在mysql_store_result()返回NULL（於是沒有結果集指針）時。在這種狀況下，可調用mysql_field_count()來斷定mysql_store_result()是否應生成非空結果。這樣，客戶端就能採起恰當的動做，而無需知道查詢是不是SELECT（或相似SELECT的）語句。在這裏給出的示例中，演示了完成它的方法。

返回值  表示結果集中列數的無符號整數。

示例：

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()的值進行推斷。

[23] mysql_field_seek()

定義函數    MYSQL_FIELD_OFFSET mysql_field_seek(MYSQL_RES *result, MYSQL_FIELD_OFFSET offset)

功能   將字段光標設置到給定的偏移處

返回值

字段光標的前一個值。

[24] mysql_field_tell()

MYSQL_FIELD_OFFSET mysql_field_tell(MYSQL_RES *result)

功能   返回上一個mysql_fetch_field()所使用的字段光標的定義。該值可用做mysql_field_seek()的參量。

返回值 字段光標的當前偏移量。

[25] mysql_free_result()

定義函數    void mysql_free_result(MYSQL_RES *result)

功能   釋放由mysql_store_result()、mysql_use_result()、mysql_list_dbs()等爲結果集分配的內存。完成對結果集的操做後，必須調用mysql_free_result()釋放結果集使用的內存。

釋放完成後，不要嘗試訪問結果集。

返回值  無。

[26] mysql_get_character_set_info()

定義函數    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);

}

[27] mysql_get_client_info()

定義函數    char *mysql_get_client_info(void)

功能   返回表示客戶端庫版本的字符串。

返回值 表示MySQL客戶端庫版本的字符串。

[28] mysql_get_client_version()

定義函數    unsigned long mysql_get_client_version(void)

功能   返回表示客戶端庫版本的整數。該值的格式是XYYZZ，其中X是主版本號，YY是發佈級別，ZZ是發佈級別內的版本號。例如，值40102表示客戶端庫的版本是4.1.2。

返回值 表示MySQL客戶端庫版本的整數。

[29] mysql_get_host_info()

char *mysql_get_host_info(MYSQL *mysql)

功能   返回描述了所使用鏈接類型的字符串，包括服務器主機名。

返回值 表明服務器主機名和鏈接類型的字符串。

[30] mysql_get_proto_info()

定義函數    unsigned int mysql_get_proto_info(MYSQL *mysql)

功能   返回當前鏈接所使用的協議版本。

返回值 表明當前鏈接所使用協議版本的無符號整數。

[31] mysql_get_server_info()

char *mysql_get_server_info(MYSQL *mysql)

功能   返回表明服務器版本號的字符串。

返回值 表明服務器版本號的字符串。

[32] mysql_get_server_version()

定義函數    unsigned long mysql_get_server_version(MYSQL *mysql)

功能   以整數形式返回服務器的版本號。

返回值 表示MySQL服務器版本的數值，格式以下：

major_version*10000 + minor_version *100 + sub_version

例如，對於5.0.12，返回500012。

在客戶端程序中，爲了快速肯定某些與版本相關的服務器功能是否存在，該函數頗有用。

[33] mysql_hex_string()

定義函數    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字符。

[34] mysql_info()

定義函數    char *mysql_info(MYSQL *mysql)

功能   檢索字符串，該字符串提供了關於最近執行查詢的信息，但僅對這裏列出的語句有效。對於其餘語句，mysql_info()返回NULL。字符串的格式取決於查詢的類型，如本節所述。數值僅是說明性的，字符串包含與查詢相適應的值。

返回值  字符串，它表示最近所執行查詢的額外信息。若是該查詢無可用信息，返回NULL。

[35] mysql_init()

定義函數    MYSQL *mysql_init(MYSQL *mysql)

功能   分配或初始化與mysql_real_connect()相適應的MYSQL對象。

返回值 初始化的MYSQL*句柄。若是無足夠內存以分配新的對象，返回NULL。

[36] mysql_insert_id()

定義函數    my_ulonglong mysql_insert_id(MYSQL *mysql)

功能   返回由之前的INSERT或UPDATE語句爲AUTO_INCREMENT列生成的值。在包含AUTO_INCREMENT字段的表中執行了INSERT語句後，應使用該函數。

返回值  在前面的討論中予以了介紹。

[37] mysql_kill()

定義函數    int mysql_kill(MYSQL *mysql, unsigned long pid)

功能   請求服務器殺死由pid指定的線程。

返回值 0表示成功，非0值表示出現錯誤。

[38] mysql_library_end()

定義函數    void mysql_library_end(void)

功能  

它是mysql_server_end()函數的同義詞。

[39] mysql_library_init()

定義函數    int mysql_library_init(int argc, char **argv, char **groups)

功能   這是mysql_server_init()函數的同義詞。

[40] mysql_list_dbs()

定義函數    MYSQL_RES *mysql_list_dbs(MYSQL *mysql, const char *wild)

功能   返回由服務器上的數據庫名稱組成的結果集，該服務器與由通配符參數指定的簡單正則表達式匹配。通配符參數能夠包含通配符「%」或「_」，也能夠是NULL指針，以便與全部的數據庫匹配。調用mysql_list_dbs()的方法相似於執行查詢SHOW database [LIKE wild]。

必須用mysql_free_result()釋放結果集。

返回值  成功後返回MYSQL_RES結果集。若是出現錯誤，返回NULL。

[41] mysql_list_fields()

定義函數    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_RES結果集。若是出現錯誤，返回NULL。

[42] mysql_list_processes()

定義函數    MYSQL_RES *mysql_list_processes(MYSQL *mysql)

功能    返回描述當前服務器線程的結果集。必須用mysql_free_result()釋放結果集。

返回值  若是成功，返回MYSQL_RES結果集。若是出現錯誤，返回NULL。

[43] mysql_list_tables()

定義函數    MYSQL_RES *mysql_list_tables(MYSQL *mysql, const char *wild)

功能    返回由當前數據庫內的表名組成的結果集，當前數據庫與由通配符參數指定的簡單正則表達式匹配。通配符參數能夠包含通配符「%」或「_」，也能夠是NULL指針，以便與全部的表匹配。調用mysql_list_tables()的方法相似於執行查詢HOW tables [LIKE wild]。

說明  必須用mysql_free_result()釋放結果集。

返回值 若是成功返回MYSQL_RES結果集。 若是出現錯誤，返回NULL。

[44] mysql_more_results()

定義函數    my_bool mysql_more_results(MYSQL *mysql)

功能    若是當前執行的查詢存在多個結果，返回「真」，並且應用程序必須調用mysql_next_result()來獲取結果。

返回值  若是存在多個結果，返回「真」（1），若是不存在多個結果，返回「假」（0）。

[45] mysql_next_result()

定義函數    int mysql_next_result(MYSQL *mysql)

功能    若是存在多個查詢結果，mysql_next_result()將讀取下一個查詢結果，並將狀態返回給應用程序。

若是前面的查詢返回告終果集，必須爲其調用mysql_free_result()。

返回值  0 成功並有多個結果。-1   成功但沒有多個結果。>0 出錯

[46] mysql_num_fields()

定義函數    unsigned int mysql_num_fields(MYSQL_RES *result)

功能    返回結果集中的行數。

返回值  表示結果集中行數的無符號整數。

示例：  同22

[47] mysql_num_rows()

定義函數    my_ulonglong mysql_num_rows(MYSQL_RES *result)

功能    返回結果集中的行數。

返回值  結果集中的行數。

[48] mysql_options()

定義函數    int mysql_options(MYSQL *mysql, enum mysql_option option, const char *arg)

功能    可用於設置額外的鏈接選項，並影響鏈接的行爲。可屢次調用該函數來設置數個選項。

應在mysql_init()以後、以及mysql_connect()或mysql_real_connect()以前調用mysql_options()。

返回值  成功時返回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));

}

[49] mysql_ping()

定義函數    int mysql_ping(MYSQL *mysql)

功能    檢查與服務器的鏈接是否工做。若是鏈接丟失，將自動嘗試再鏈接。該函數可被閒置了較長時間的客戶端使用，用以檢查服務器是否已關閉了鏈接，並在必要時再次鏈接。

返回值   若是與服務器的鏈接有效返回0。若是出現錯誤，返回非0值。返回的非0值不表示MySQL服務器自己是否已關閉，鏈接可能因其餘緣由終端，如網絡問題等。

[50] mysql_query()

定義函數    int mysql_query(MYSQL *mysql, const char *query)

功能    執行由「Null終結的字符串」查詢指向的SQL查詢。若是但願瞭解查詢是否應返回結果集，可以使用mysql_field_count()進行檢查。請參見25.2.3.22節，「mysql_field_count()」。

返回值   若是查詢成功，返回0。若是出現錯誤，返回非0值。

 

[51] mysql_real_connect()

定義函數    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()調用，可更改多種鏈接選項。

·         「host」的值必須是主機名或IP地址。

·         「user」參數包含用戶的MySQL登陸ID。

·         「passwd」參數包含用戶的密碼。

·         「db」是數據庫名稱。若是db爲NULL，鏈接會將默認的數據庫設爲該值。

·        若是「port」不是0，其值將用做TCP/IP鏈接的端口號。注意，「host」參數決定了鏈接的類型。

·        若是unix_socket不是NULL，該字符串描述了應使用的套接字或命名管道。注意，「host」參數決定了鏈接的類型。

·         client_flag的值一般爲0，可是，也能將其設置爲下述標誌的組合，以容許特定功能。具體參數值請查看相關資料。

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

·        對於user，指定NULL值或空字符串。

·        對於passwd，指定NULL值。（對於密碼，mysql_real_connect()調用中的空字符串的值不能被選項文件中的字符串覆蓋，這是由於，空字符串明確指明MySQL帳戶必須有空密碼）。

·        對於db，指定NULL值或空字符串

·        對於port，指定「0」值。

·        對於unix_socket，指定NULL值。

對於某一參數，若是在選項文件中未發現值，將使用它的默認值，如本節前面介紹的那樣。

返回值    若是鏈接成功，返回MYSQL*鏈接句柄。若是鏈接失敗，返回NULL。

示例：

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));

}

 

[52] mysql_real_escape_string()

定義函數    unsigned long mysql_real_escape_string(MYSQL *mysql, char *to, const char *from, unsigned long length)

功能    該函數用於建立可在SQL語句中使用的合法SQL字符串。

示例：

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字符。

 

[53] mysql_real_query()

定義函數    int mysql_real_query(MYSQL *mysql, const char *query, unsigned long length)

功能    執行由「query」指向的SQL查詢，它應是字符串長度字節「long」。正常狀況下，字符串必須包含1條SQL語句，並且不該爲語句添加終結分號（‘;’）或「\g」。若是容許多語句執行，字符串可包含由分號隔開的多條語句。對於包含二進制數據的查詢，必須使用mysql_real_query()而不是mysql_query()，這是由於，二進制數據可能會包含‘\0’字符。此外，mysql_real_query()比mysql_query()快，這是由於它不會在查詢字符串上調用strlen()。

返回值  若是查詢成功，返回0。若是出現錯誤，返回非0值。

 

[54] mysql_refresh()

定義函數    int mysql_refresh(MYSQL *mysql, unsigned int options)

功能    該函數用於刷新表或高速緩衝，或復位複製服務器信息。鏈接的用戶必須具備RELOAD權限。

返回值   0表示成功，非0值表示出現錯誤。

 

[55] mysql_reload()

定義函數    int mysql_reload(MYSQL *mysql)

功能    請求MySQL服務器從新加載受權表。鏈接的用戶必須具備RELOAD權限。該函數已過期。最好使用mysql_query()來發出SQL FLUSH PRIVILEGES語句。

返回值  0表示成功，非0值表示出現錯誤。

 

[56] mysql_rollback()

定義函數    my_bool mysql_rollback(MYSQL *mysql)

功能    回滾當前事務。

返回值  若是成功返回0，若是出現錯誤，返回非0值。

 

[57] mysql_row_seek()

定義函數    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()的後續調用。

 

[58] mysql_row_tell()

定義函數    MYSQL_ROW_OFFSET mysql_row_tell(MYSQL_RES *result)

功能    對於上一個mysql_fetch_row()，返回行光標的當前位置。該值可用做mysql_row_seek()的參量。

僅應在mysql_store_result()以後，而不是mysql_use_result()以後使用mysql_row_tell()。

返回值   行光標的當前偏移量。

 

[59] mysql_select_db()

定義函數    int mysql_select_db(MYSQL *mysql, const char *db)

功能    使由db指定的數據庫成爲由mysql指定的鏈接上的默認數據庫（當前數據庫）。

返回值  0表示成功，非0值表示出現錯誤。

 

[60] mysql_set_character_set()

定義函數    int mysql_set_character_set(MYSQL *mysql, char *csname)

功能    該函數用於爲當前鏈接設置默認的字符集。

返回值  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));

}

 

[61] mysql_set_server_option()

int mysql_set_server_option(MYSQL *mysql, enum enum_mysql_set_option option)

功能    容許或禁止鏈接的選項。

返回值  0表示成功，非0值表示出現錯誤。

 

[62] mysql_shutdown()

定義函數    int mysql_shutdown(MYSQL *mysql, enum enum_shutdown_level shutdown_level)

功能    請求數據庫服務器關閉。

返回值  0表示成功，非0值表示出現錯誤。

 

[63] mysql_sqlstate()

定義函數    const char *mysql_sqlstate(MYSQL *mysql)

功能    返回由Null終結的字符串，該字符串包含關於上次錯誤的SQLSTATE錯誤代碼。

返回值  包含SQLSTATE錯誤碼的、由Null終結的字符串。

 

[64] mysql_ssl_set()

定義函數    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()將返回錯誤。

 

[65] mysql_stat()

定義函數    char *mysql_stat(MYSQL *mysql)

功能    返回包含特定信息的字符串，該信息與mysqladmin status命令提供的信息相似。包括以秒爲單位的正常運行時間，以及運行線程的數目，問題數，再加載次數，以及打開的表數目。

返回值   描述服務器狀態的字符集。若是出現錯誤，返回NULL。

 

[66] mysql_store_result()

定義函數    MYSQL_RES *mysql_store_result(MYSQL *mysql)

功能    對於成功檢索了數據的每一個查詢（SELECT、SHOW、DESCRIBE、EXPLAIN、CHECK TABLE等），必須調用mysql_store_result()或mysql_use_result() 。

返回值  具備多個結果的MYSQL_RES結果集合。若是出現錯誤，返回NULL。

 

[67] mysql_thread_id()

定義函數    unsigned long mysql_thread_id(MYSQL *mysql)

功能    返回當前鏈接的線程ID。該值可用做mysql_kill()的參量以殺死線程。

若是鏈接丟失，並使用mysql_ping()進行了再鏈接，線程ID將改變。這意味着你不該獲取線程ID並保存它供之後使用。應在須要時獲取它。

返回值       當前鏈接的線程ID。

 

[68] mysql_use_result()

定義函數    MYSQL_RES *mysql_use_result(MYSQL *mysql)

功能    對於成功檢索數據的每一個查詢（SELECT、SHOW、DESCRIBE、EXPLAIN），必須調用mysql_store_result()或mysql_use_result()。

返回值  MYSQL_RES結果結構。若是出現錯誤，返回NULL。

 

[69] mysql_warning_count()

定義函數    unsigned int mysql_warning_count(MYSQL *mysql)

返回值   告警計數。