23.8.7.53 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_real_connect() は、有効な MYSQL 接続ハンドル構造を必要とするほかの任意の API 関数を実行する前に、正常に完了している必要があります。

パラメータは次のように指定します。

• 最初のパラメータで、既存の MYSQL 構造のアドレスを指定します。mysql_real_connect() を呼び出す前に、mysql_init() を呼び出して、MYSQL 構造を初期化します。mysql_options() の呼び出しによって、多くの接続オプションを変更できます。セクション23.8.7.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 では、現在のユーザー名を明示的に指定する必要があります。第23章「Connector および API」の Connector/ODBC のセクションを参照してください。

• passwdパラメータには、user のパスワードが含まれます。passwd が NULL である場合、ブランク (空) のパスワードフィールドを持つユーザーの user テーブル内のエントリのみが一致をチェックされます。これにより、データベース管理者は、ユーザーがパスワードを指定しているかどうかに応じて、ユーザーが異なる権限を取得するような MySQL 権限システムをセットアップできます。

  注記

  mysql_real_connect() を呼び出す前に、パスワードを暗号化しようとしないでください。パスワードの暗号化はクライアント API によって自動的に処理されます。

• user および passwd パラメータは、MYSQL オブジェクトに構成されている文字セットを使用します。デフォルトでこれは latin1 ですが、接続の前に mysql_options(mysql, MYSQL_SET_CHARSET_NAME, "charset_name") を呼び出すことによって変更できます。

• db はデータベース名です。db が NULL でない場合、接続はデフォルトのデータベースをこの値に設定します。

• port が 0 でない場合、値は TCP/IP 接続のポート番号として使用されます。host パラメータによって、接続の種類が決まります。

• unix_socket が NULL でない場合、文字列は使用するソケットまたは名前付きパイプを指定します。host パラメータによって、接続の種類が決まります。

• client_flag の値は通常 0 ですが、特定の機能を有効にするために、次のフラグの組み合わせに設定できます。

  フラグ名	フラグの説明
  CAN_HANDLE_EXPIRED_PASSWORDS	クライアントは期限切れのパスワードを処理できます。詳細については、セクション6.3.6「パスワードの期限切れとサンドボックスモード」を参照してください。このオプションは MySQL 5.6.10 で追加されました。
  CLIENT_COMPRESS	圧縮プロトコルを使用します。
  CLIENT_FOUND_ROWS	変更された行の数ではなく、見つかった (一致した) 行の数を返します。
  CLIENT_IGNORE_SIGPIPE	クライアントライブラリの SIGPIPE シグナルハンドラのインストールを妨げます。これは、アプリケーションがすでにインストールしているハンドラとの競合を避けるために使用できます。
  CLIENT_IGNORE_SPACE	関数名のあとのスペースを許可します。すべての関数名を予約語にします。
  CLIENT_INTERACTIVE	接続を閉じるまで、interactive_timeout 秒 (wait_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	使用されません。
  CLIENT_SSL	SSL (暗号化プロトコル) を使います。アプリケーションプログラム内にこのオプションを設定しないでください。それはクライアントライブラリに内部で設定されます。代わりに、mysql_real_connect() を呼び出す前に、mysql_ssl_set() を使用します。
  CLIENT_REMEMBER_OPTIONS	mysql_options() への呼び出しに指定したオプションを覚えておきます。このオプションを使用しないと、mysql_real_connect() が失敗した場合、再度接続を試みる前に、mysql_options() 呼び出しを繰り返す必要があります。このオプションを使用すると、mysql_options() 呼び出しを繰り返す必要がありません。

プログラムで CALL ステートメントを使用して、ストアドプロシージャーを実行する場合、CLIENT_MULTI_RESULTS フラグが有効になっている必要があります。これは、各 CALL によって、プロシージャー内で実行されるステートメントによって返される可能性のある結果セットに加えて、呼び出しステータスを示すための結果が返されるためです。CALL は複数の結果を返すことができるため、mysql_next_result() を呼び出すループを使用して、それらを処理し、それ以上の結果があるかどうかを判断します。

CLIENT_MULTI_RESULTS は、mysql_real_connect() を呼び出すときに、CLIENT_MULTI_RESULTS フラグ自体を渡すことによって明示的に、または CLIENT_MULTI_STATEMENTS を渡すことによって暗黙的に有効にする (これによって CLIENT_MULTI_RESULTS も有効になります) ことができます。MySQL 5.6 では、CLIENT_MULTI_RESULTS はデフォルトで有効にされています。

CLIENT_MULTI_STATEMENTS または CLIENT_MULTI_RESULTS を有効にした場合、それ以上の結果があるかどうかを判断するために mysql_next_result() を呼び出すループを使用して、mysql_query() または mysql_real_query() へのすべての呼び出しの結果を処理します。例については、セクション23.8.17「複数ステートメント実行の C 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 に対して、0 の値を指定します。

• 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

  異なるプロトコルバージョンを使用するクライアントライブラリによるサーバーへの接続の試みから発生したプロトコルの不一致。

• CR_NAMEDPIPEOPEN_ERROR

  Windows で名前付きパイプの作成に失敗しました。

• CR_NAMEDPIPEWAIT_ERROR

  Windows で名前付きパイプの待機に失敗しました。

• CR_NAMEDPIPESETSTATE_ERROR

  Windows でパイプハンドラの取得に失敗しました。

• CR_SERVER_LOST

  connect_timeout > 0 で、サーバーに接続するために connect_timeout 秒より長くかかった場合、または init-command の実行中にサーバーが停止した場合。

• CR_ALREADY_CONNECTED

  MYSQL 接続ハンドルはすでに接続されています。

例

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_options() に MYSQL_OPT_RECONNECT オプションを使用して、再接続動作を制御できます。