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