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() を使ってください。 |
プログラムが結果セットを生成する記憶された手順を実行するために、CALL
SQLステートメントを使用する場合、あなたは、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. 「マルチプルステートメントを実行する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
に対して、ゼロの値を規定してください。
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()
に対して、再接続行動を制御するのに使用することができます。