23.2.3.52 mysql_real

23.2.3.52. `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()はhost上で運転されるMySQLデータベースエンジンに接続を確立しようと努めます。mysql_real_connect()は、有効なMYSQL接続ハンドル構造を必要とする他のAPI機能が実行可能になる前に、うまく完了されなければなりません。

パラメータは次のように規定されます：

最初のパラメータは既存のMYSQL構造にすべきです。mysql_real_connect()を呼び出す前に、mysql_init()を呼び出してMYSQL構造を初期化しなければなりません。mysql_options()を呼び出して、多くの接続オプションを変更することができます。項23.2.3.49. 「mysql_options()」を参照してください。
(この場合)hostの値をホスト名かIPアドレスにすることができます。hostがNULLまたはストリング"localhost"である場合、ローカルホストへの接続と仮定します:Windowsに対して、サーバが共有メモリー接続を有効にしている場合、クライアントはメモリー接続を使って接続します。さもなければ、TCP/IPが使われます。Unixの場合、クライアントはUnix専用のソケットファイルを使って接続します。ローカル接続の場合、mysql_options()に対してMYSQL_OPT_PROTOCOLオプションもしくはMYSQL_OPT_NAMED_PIPEオプションと一緒に使う接続のタイプに影響を及ぼすこともできます。接続のタイプはサーバによってサポートされなくければなりません。Windows上の"." のhost値に対して、クライアントは指定パイプを使って接続します。指定パイプによる接続が有効化されていないと、エラーが発生します。
userパラメータには、ユーザーのMySQLログインIDが含まれています。userがNULLまたは空ストリング""である場合、現在のユーザーを想定します。Unixでは、これは現在のログイン名です。Windows ODBCでは、現在のユーザ名を明確に規定しなければなりません。章 24. MySQL コネクタのMyODBCセクションをご参照ください。
passwdパラメータには、userに対するパスワードが含まれています。passwdがNULLである場合、ブランク(空の)パスワードフィールドを持つユーザーのために行ったuser テーブルへの入力だけがマッチするかチェックされます。これは、データベース管理者がMySQL特権システムを、ユーザーがパスワードを規定したか否かによって、異なった特権を取得するようにセットすることを可能にします。

注:mysql_real_connect()を呼び出す前に、パスワードを暗号化しようとしてはなりません。パスワードの暗号化はクライアントAPIによって自動的に取り扱われます。
dbはデータベース名です。dbがNULLでない場合、接続はこの値にデフォルトデータベースを設定します。
portが0でない場合、値はTCP/IP接続のためのポートナンバーとして使用されます。hostパラメータが接続のタイプを決めることにご注目ください。
unix_socketがNULLでない場合、ストリングは使用すべきソケットまたは指定パイプを規定します。hostパラメータが接続のタイプを決めることにご注目ください。

client_flagの値は通常0ですが、次のフラグを組み合わせてセットすると、ある種の機能を有効にすることができます:

フラグ名	フラグの説明
`CLIENT_COMPRESS`	圧縮プロトコルの使用。
`CLIENT_FOUND_ROWS`	変更した行の数でなく、検出され(マッチした)行の数を戻す。
`CLIENT_IGNORE_SPACE`	機能名の後にスペースを取ることを許します。全ての機能名を予約されたワードにします。
`CLIENT_INTERACTIVE`	接続を閉じる前に(`wait_timeout`秒の代わりに)、`interactive_timeout`秒間停止します。クライアントのセッション`wait_timeout`変数は、セッション`interactive_timeout`変数の値にセットされます。
`CLIENT_LOCAL_FILES`	は`LOAD DATA LOCAL`ハンドリングを有効化します。
`CLIENT_MULTI_RESULTS`	サーバに、クライアントはマルチ結果セットをマルチステートメントの実効から処理できることを通知します。`CLIENT_MULTI_STATEMENTS`がセットされる場合、自動的にセットされます。フラグの詳細については、このテーブルの後にあるノートをご参照ください。
`CLIENT_MULTI_STATEMENTS`	サーバに、クライアントは、(‘`;`’によって隔離された)シングルストリングの中にマルチステートメントを送ることができることを通知します。このフラグがセットされないと、マルチステートメントの実効は不能になります。フラグの詳細については、このテーブルの後にあるノートをご参照ください。
`CLIENT_NO_SCHEMA`	`db_name.tbl_name.col_name`構文の使用を許しません｡これはODBCのためのものです。幾つかODBCプログラム中でバグを捕えるのに役立つあの構文を使うと、それが、パーサーがエラーを生成する原因を引き起こします。
`CLIENT_ODBC`	クライアントはODBCクライアントです。これはmysqldをODBCにもっと優しくなるように変更します。
`CLIENT_SSL`	SSL(暗号化されたプロトコル)を使います｡このオプションはアプリケーションプログラムによってセットされるべきではありません。これはクライアントライブラリ内部でセットされます。その代わりに、`mysql_real_connect()`を呼び出す前に、`mysql_ssl_set()`を使ってください。

プログラムが結果セットを生成する記憶された手順を実行するために、CALLSQLステートメントを使用する場合、あなたは、mysql_real_connect()を呼び出すとき、CLIENT_MULTI_STATEMENTSをセットすることによって、CLIENT_MULTI_RESULTSフラグを明示的もしくは黙示的にセットしなければなりません。このような記憶された手順は各々、複数の結果を生成するので、これを実行しなければなりません。手順の中で実行された命令文によって戻された結果の組並びに呼び出しのステータスを示す結果。

CLIENT_MULTI_STATEMENTSまたはCLIENT_MULTI_RESULTSを有効にした場合、mysql_next_result()を呼び出して、更に結果があるか否かを査定するループを使用することによって、mysql_query()またはmysql_real_query()に対する全ての呼び出しの結果を処理すべきです。(例については、項23.2.9. 「マルチプルステートメントを実行するＣ APIハンドリング」をご覧ください。)

幾つかのパラメータをmysql_real_connect()の呼び出文中の明確な値からでなく、オプションファイルかた取らせせることが可能です。これを行うため、mysql_real_connect()を呼び出す前に、MYSQL_READ_DEFAULT_FILEまたはMYSQL_READ_DEFAULT_GROUPと一緒に、mysql_options()を呼び出してください。その後、各パラメータがオプションファイルから読み取られるように、mysql_real_connect()の呼び出しに、「no-value」値を規定してください。

hostに対して、NULLまたは空のストリング("")の値を規定してください。
userに対して、NULLまたは空のストリングの値を規定してください。
passwdに対して、NULLの値を規定してください。(パスワードに対して、mysql_real_connect()コール中の空ストリングの値がオプションファイルに入るのを禁止することはできません。なぜなら、空のストリングは、MySQLアカウントには空のパスワードが含まれていなければならないことを明示しているからです。)
dbに対して、NULLまたは空のストリングの値を規定してください。
portに対して、ゼロの値を規定してください。
unix_socketに対して、NULLの値を規定してください。

パラメータのためのオプションファイル中に値が見つからない場合、このセクションの始めの部分で説明したように、そのデフォルト値が使われます。

戻り値

接続が成功した場合MYSQL*接続ハンドル。接続が不成功であった場合 NULL。接続が成功した場合、戻り値は最初のパラメータの値と同じになります。

エラー

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ライブラリは、誰かが非標準的な方法でMySQLをセットした場合でも、プログラムが作動することを確認するmy.cnfファイル中の[client]セクションおよび[your_prog_name]セクションを読み取ります。

接続と同時に、mysql_real_connect()は、reconnect フラグ(MYSQL構造の一部)を、バージョンが5.0.3より古いAPI中にある1の値または0の値にセットすることにご注目ください。このフラグに対する1の値は、ステートメントが失われた接続のために実効できない場合、実効を諦める前にサーバに再び接続しようとすることを示します。MYSQL_OPT_RECONNECTオプションをmysql_options()に対して、再接続行動を制御するのに使用することができます。

23.2.3.52. mysql_real_connect()

23.2.3.52. `mysql_real_connect()`