23.7.7.49 mysql_options()

int mysql_options(MYSQL *mysql, enum mysql_option option, const void *arg)

説明

追加の接続オプションを設定し、接続の動作に影響を与えるために使うことができます。この関数を複数回呼び出して、複数のオプションを設定できます。

mysql_init() のあとと mysql_connect() または mysql_real_connect() の前に mysql_options() を呼び出します。

option 引数は、設定するオプションです。arg 引数はそのオプションの値です。オプションが整数の場合、arg 引数として、整数の値へのポインタを指定します。

次のリストに、可能なオプション、それらの効果、および各オプションの arg の使用方法を示します。オプションのいくつかは、アプリケーションが libmysqld 組み込みサーバーライブラリに対してリンクされている場合にのみ適用され、libmysqlclient クライアントライブラリに対してリンクされているアプリケーションには使用されません。arg が使用されないことを示すオプションの説明では、その値は関係ありません。慣例として 0 を渡します。

• MYSQL_DEFAULT_AUTH (引数の型: char *)

  使用する認証プラグインの名前。

• MYSQL_ENABLE_CLEARTEXT_PLUGIN (引数の型: my_bool *)

  mysql_clear_password 平文認証プラグインを有効にします。(セクション6.3.8.7「クライアント側のクリアテキスト認証プラグイン」を参照してください。)このオプションは MySQL 5.6.7 で追加されました。

• MYSQL_INIT_COMMAND (引数の型: char *)

  MySQL サーバーへの接続時に実行する SQL ステートメント。再接続が行われる場合に自動的に再実行されます。

• MYSQL_OPT_BIND (引数: char *)

  サーバーに接続するためのネットワークインタフェース。これはクライアントホストに複数のネットワークインタフェースがある場合に使用されます。引数はホスト名または IP アドレス (文字列として指定) です。このオプションは MySQL 5.6.1 で追加されました。

• MYSQL_OPT_CAN_HANDLE_EXPIRED_PASSWORDS (引数の型: my_bool *)

  クライアントが期限切れのパスワードを処理できるかどうかを示します。詳細については、セクション6.3.6「パスワードの期限切れとサンドボックスモード」を参照してください。このオプションは MySQL 5.6.10 で追加されました。

• MYSQL_OPT_COMPRESS (引数: 使用なし)

  圧縮されたクライアント/サーバープロトコルを使用します。

• MYSQL_OPT_CONNECT_ATTR_DELETE (引数の型: char *)

  キー名を指定すると、このオプションは、接続時にサーバーに渡される現在の接続属性のセットから、キー/値ペアを削除します。引数はこのキーを指定する NULL 終端文字列へのポインタです。既存のキーとのキー名の比較は大文字と小文字が区別されます。

  mysql_options4() 関数の説明の MYSQL_OPT_CONNECT_ATTR_ADD オプションの説明に加えて、MYSQL_OPT_CONNECT_ATTR_RESET オプションの説明も参照してください。この関数の説明には、使用例も含まれています。これらのオプションは MySQL 5.6.6 で追加されました。

  接続属性は、session_connect_attrs および session_account_connect_attrs パフォーマンススキーマテーブル経由で公開されます。セクション22.9.8「パフォーマンススキーマ接続属性テーブル」を参照してください。

• MYSQL_OPT_CONNECT_ATTR_RESET (引数は使用されません)

  このオプションは、接続時にサーバーに渡される現在の接続属性のセットをリセット (クリア) します。

  mysql_options4() 関数の説明の MYSQL_OPT_CONNECT_ATTR_ADD オプションの説明に加えて、MYSQL_OPT_CONNECT_ATTR_DELETE オプションの説明も参照してください。この関数の説明には、使用例も含まれています。これらのオプションは MySQL 5.6.6 で追加されました。

  接続属性は、session_connect_attrs および session_account_connect_attrs パフォーマンススキーマテーブル経由で公開されます。セクション22.9.8「パフォーマンススキーマ接続属性テーブル」を参照してください。

• MYSQL_OPT_CONNECT_TIMEOUT (引数の型: unsigned int *)

  秒単位の接続タイムアウト。

• MYSQL_OPT_GUESS_CONNECTION (引数は使用されません)

  libmysqld 組み込みサーバーライブラリに対してリンクされたアプリケーションの場合、これにより、ライブラリは組み込みサーバーを使用するか、リモートサーバーを使用するかを推測できます。「推測」とは、ホスト名が設定されていて、localhost でない場合、リモートサーバーを使用することを意味します。この動作はデフォルトです。MYSQL_OPT_USE_EMBEDDED_CONNECTION および MYSQL_OPT_USE_REMOTE_CONNECTION を使用して、それをオーバーライドできます。このオプションは、libmysqlclient クライアントライブラリに対してリンクされたアプリケーションに対しては無視されます。

• MYSQL_OPT_LOCAL_INFILE (引数の型: unsigned int へのオプションのポインタ)

  ポインタが指定されていないか、ポインタがゼロ以外の値を持つ unsigned int を指している場合、LOAD LOCAL INFILE ステートメントが有効にされます。

• MYSQL_OPT_NAMED_PIPE (引数: 使用されません)

  MySQL サーバーが名前付きパイプ接続を許可する場合に、Windows でサーバーに接続するために、名前付きパイプを使用します。

• MYSQL_OPT_PROTOCOL (引数の型: unsigned int *)

  使用するプロトコルの種類。mysql.h に定義されている mysql_protocol_type の列挙値のいずれかを指定します。

• MYSQL_OPT_READ_TIMEOUT (引数の型: unsigned int *)

  サーバーからの読み取りの試みごとの秒単位でのタイムアウト。必要に応じて再試行があるため、実際の合計タイムアウト値は、オプションの値の 3 倍です。10 分の TCP/IP Close_Wait_Timeout 値より早く、失われた接続を検出できるように値を設定できます。

  このタイムアウトの実装は、すべてのプラットフォームで使用できるとは限らないメカニズムを使用しています。そのようなプラットフォームでは、読み取り呼び出しを発行するクライアントが、特定の環境において、タイムアウトせずに待機することがあります。たとえば、サーバーが「ディスク領域不足」状況がクリアされるまで待機しているために応答しない場合、クライアントはタイムアウトしない可能性があります。

• MYSQL_OPT_RECONNECT (引数の型: my_bool *)

  接続が失われていることが検出された場合に、サーバーへの自動再接続を有効または無効にします。再接続はデフォルトでオフにされますが、このオプションは明示的に再接続動作を設定する方法を提供します。

• MYSQL_OPT_SSL_CA (引数の型: char *)

  信頼された SSL CA のリストを含むファイルへのパス。このオプションは MySQL 5.6.3 で追加されました。

• MYSQL_OPT_SSL_CAPATH (引数の型: char *)

  PEM 形式の信頼された SSL CA 証明書を格納するディレクトリのパス。このオプションは MySQL 5.6.3 で追加されました。

• MYSQL_OPT_SSL_CERT (引数の型: char *)

  セキュアな接続を確立するために使用する SSL 証明書ファイルの名前。このオプションは MySQL 5.6.3 で追加されました。

• MYSQL_OPT_SSL_CIPHER (引数の型: char *)

  SSL 暗号化に使用する許可されている暗号のリスト。このオプションは MySQL 5.6.3 で追加されました。

• MYSQL_OPT_SSL_CRL (引数の型: char *)

  PEM 形式での証明書失効リストを含むファイルへのパス。このオプションは MySQL 5.6.3 で追加されました。

• MYSQL_OPT_SSL_CRLPATH (引数の型: char *)

  PEM 形式での証明書失効リストを含むファイルを格納するディレクトリへのパス。このオプションは MySQL 5.6.3 で追加されました。

• MYSQL_OPT_SSL_KEY (引数の型: char *)

  セキュアな接続を確立するために使用する SSL 鍵ファイルの名前。このオプションは MySQL 5.6.3 で追加されました。

• MYSQL_OPT_SSL_VERIFY_SERVER_CERT (引数の型: my_bool *)

  サーバーの証明書内のサーバーの一般名値の、サーバーへの接続時に使用されるホスト名に対する検証を有効または無効にします。不一致があった場合、接続は拒否されます。この機能は、中間者攻撃を防ぐために使用できます。検証はデフォルトで無効です。

• MYSQL_OPT_USE_EMBEDDED_CONNECTION (引数: 使用されません)

  libmysqld 組み込みサーバーライブラリに対してリンクされたアプリケーションの場合、これにより、接続に組み込みサーバーの使用が強制されます。このオプションは、libmysqlclient クライアントライブラリに対してリンクされたアプリケーションに対しては無視されます。

• MYSQL_OPT_USE_REMOTE_CONNECTION (引数: 使用されません)

  libmysqld 組み込みサーバーライブラリに対してリンクされたアプリケーションの場合、これにより、接続にリモートサーバーの使用が強制されます。このオプションは、libmysqlclient クライアントライブラリに対してリンクされたアプリケーションに対しては無視されます。

• MYSQL_OPT_USE_RESULT (引数: 使用されません)

  このオプションは使用されません。

• MYSQL_OPT_WRITE_TIMEOUT (引数の型: unsigned int *)

  サーバーへの書き込みの試みごとの秒単位でのタイムアウト。必要に応じて再試行があるため、実際の合計タイムアウト値は、オプションの値の 2 倍です。

• MYSQL_PLUGIN_DIR (引数の型: char *)

  クライアントプラグインを検索するディレクトリ。

• MYSQL_READ_DEFAULT_FILE (引数の型: char *)

  my.cnf の代わりに、指定したオプションファイルからオプションを読み取ります。

• MYSQL_READ_DEFAULT_GROUP (引数の型: char *)

  my.cnf の指定したグループまたは MYSQL_READ_DEFAULT_FILE によって指定されたファイルから、オプションを読み取ります。

• MYSQL_REPORT_DATA_TRUNCATION (引数の型: my_bool *)

  MYSQL_BIND 構造の error メンバーを使用して、プリペアドステートメントのデータ切り捨てエラーのレポートを有効または無効にします。(デフォルト: 有効。)

• MYSQL_SECURE_AUTH (引数の型: my_bool *)

  MySQL 4.1.1 以降で使用されているパスワードハッシュをサポートしていないサーバーに接続するかどうか。MySQL 5.6.7 以降、このオプションはデフォルトで有効にされています。

• MYSQL_SERVER_PUBLIC_KEY (引数の型: char *)

  サーバー RSA 公開鍵を含むファイルへのパス名。ファイルは PEM 形式である必要があります。公開鍵は、sha256_password プラグインによって認証するアカウントを使用して、サーバーへの接続を作成するためのクライアントパスワードの RSA 暗号化に使用されます。このオプションは、そのプラグインによって認証しないクライアントアカウントに対しては無視されます。さらに、クライアントが SSL 接続を使用して、サーバーに接続する場合のように、パスワード暗号化が必要でない場合も無視されます。

  サーバーは必要に応じて公開鍵をクライアントに送信するため、RSA パスワードの暗号化が行われるように、このオプションを使う必要はありません。そうすることで、サーバーは鍵を送信する必要がないため、効率が向上します。

  RSA 公開鍵の取得方法を含め、sha256_password プラグインの使用に関する追加の説明については、セクション6.3.8.4「SHA-256 認証プラグイン」を参照してください。

  このオプションは MySQL 5.6.6 で追加されました。

• MYSQL_SET_CHARSET_DIR (引数の型: char *)

  文字セット定義ファイルを格納するディレクトリのパス名。

• MYSQL_SET_CHARSET_NAME (引数の型: char *)

  デフォルトの文字セットとして使用する文字セットの名前。引数を MYSQL_AUTODETECT_CHARSET_NAME にして、オペレーティングシステム設定に基づいて、文字セットを自動検出させることができます (セクション10.1.4「接続文字セットおよび照合順序」を参照してください)。

• MYSQL_SET_CLIENT_IP (引数の型: char *)

  libmysqld 組み込みサーバーライブラリに対してリンクされたアプリケーションの場合 (libmysqld が認証サポート付きでコンパイルされている場合)、これは、ユーザーが認証のために指定された IP アドレス (文字列として指定) から接続しているとみなされることを意味します。このオプションは、libmysqlclient クライアントライブラリに対してリンクされたアプリケーションに対しては無視されます。

• MYSQL_SHARED_MEMORY_BASE_NAME (引数の型: char *)

  サーバーが共有メモリー接続をサポートしている場合、Windows 上のサーバーとの通信のための共有メモリーオブジェクトの名前。接続先の mysqld サーバーに使用されている --shared-memory-base-name オプションと同じ値を指定します。

MYSQL_READ_DEFAULT_FILE または MYSQL_READ_DEFAULT_GROUP を使用する場合、client グループが常に読み取られます。

オプションファイル内の指定されたグループには、次のオプションが含まれることがあります。

オプション	説明
character-sets-dir=path	文字セットがインストールされているディレクトリ。
compress	圧縮されたクライアント/サーバープロトコルを使用します。
connect-timeout=seconds	秒単位の接続タイムアウト。Linux では、このタイムアウトはサーバーからの最初の回答を待機する場合にも使います。
database=db_name	接続コマンドにデータベースが指定されていなかった場合、このデータベースに接続します。
debug	デバッグオプション。
default-character-set=charset_name	使用するデフォルトの文字セット。
disable-local-infile	LOAD DATA LOCAL の使用を無効にします。
enable-cleartext-plugin	mysql_clear_password 平文認証プラグインを有効にします。MySQL 5.6.7 で追加されました。
host=host_name	デフォルトのホスト名。
init-command=stmt	MySQL サーバーへの接続時に実行するステートメント。再接続が行われる場合に自動的に再実行されます。
interactive-timeout=seconds	mysql_real_connect() に CLIENT_INTERACTIVE を指定する場合と同じ。セクション23.7.7.53「mysql_real_connect()」を参照してください。
local-infile[={0|1}]	引数がないか、ゼロ以外の引数の場合、LOAD DATA LOCAL の使用を有効にします。それ以外の場合は無効にします。
max_allowed_packet=bytes	クライアントがサーバーから読み取ることができるパケットの最大サイズ。
multi-queries、multi-results	複数ステートメントの実行またはストアドプロシージャーからの複数の結果セットを可能にします。
multi-statements	クライアントが複数のステートメントを単一の文字列 (「;」 で区切られた) で送信できるようにします。
password=password	デフォルトパスワード。
pipe	Windows で MySQL サーバーに接続するために、名前付きパイプを使用します。
port=port_num	デフォルトのポート番号。
protocol={TCP|SOCKET|PIPE|MEMORY}	サーバーに接続する場合に使用するプロトコル。
return-found-rows	UPDATE を使う場合、更新された行の代わりに見つかった行を返すように、mysql_info() に伝えます。
shared-memory-base-name=name	サーバーに接続するために使用する共有メモリー名。
socket=path	デフォルトのソケットファイル。
ssl-ca=file_name	認証局ファイル。
ssl-capath=path	認証局ディレクトリ。
ssl-cert=file_name	証明書ファイル。
ssl-cipher=cipher_list	許容される SSL 暗号。
ssl-key=file_name	鍵ファイル。
timeout=seconds	connect-timeout に似ています。
user	デフォルトユーザー。

timeout は connect-timeout によって置き換えられましたが、timeout は下位互換性のため、MySQL 5.6 で引き続きサポートされています。

MySQL プログラムによって使用されるオプションファイルの詳細については、セクション4.2.6「オプションファイルの使用」を参照してください。

戻り値

成功の場合はゼロ。不明なオプションを指定した場合はゼロ以外。

例

次の mysql_options() 呼び出しは、クライアント/サーバープロトコルでの圧縮の使用を要求し、オプションファイルの [odbc] グループからオプションを読み取らせ、トランザクション自動コミットモードを無効にします。

MYSQL mysql;

mysql_init(&mysql);
mysql_options(&mysql,MYSQL_OPT_COMPRESS,0);
mysql_options(&mysql,MYSQL_READ_DEFAULT_GROUP,"odbc");
mysql_options(&mysql,MYSQL_INIT_COMMAND,"SET autocommit=0");
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));
}

このコードは、クライアントが圧縮されたクライアント/サーバープロトコルを使用し、my.cnf ファイルの odbc セクションから追加のオプションを読み取ります。