MySQL :: MySQL 5.6 リファレンスマニュアル

version 5.6

8.0 English
5.7 English
5.6 English
5.5 English

MySQL 5.6 リファレンスマニュアル / ... / mysql_options()

23.8.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.8.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 セクションから追加のオプションを読み取ります。

PREV HOME UP NEXT

User Comments

Posted by Rupert Peddle on December 15, 2008

When retrying a connection, I used mysql_options() to set a connection timeout then called mysql_real_connect in a while loop:

mysql_options(...);

while(!mysql_real_connect(...))
{
nanosleep(...);
}

Doing this, it appears that the connection timeout was lost after the first iteration. I had to re-set the connection timeout after every attempt:

mysql_options(...);

while(!mysql_real_connect(...))
{
nanosleep(...);
mysql_options(...);
}

Don't know if this is the case for other options....

Posted by Uros Reljic on April 23, 2009

Set flag CLIENT_REMEMBER_OPTIONS in client_flag when you calling mysql_real_connect().
Without this flag, if mysql_real_connect() fails, you must repeat the mysql_options() calls before trying to connect again.

Speco

Posted by Gary Wallis on April 15, 2010

Here is some example code that can provide usec timeout for mysql_real_connect(), is based on a non blocking test connection before doing the actual mysql_real_connect().

You can find the complete example here: http://venus.openisp.net/openisp/unxsVZ/browser/trunk/unxsBind/mysqlping.c

if(DBIP1!=NULL)
{
if((iSock=socket(AF_INET,SOCK_STREAM,IPPROTO_TCP))<0)
{
printf("Could not create socket\n");
exit(1);
}
// Set non-blocking
lFcntlArg=fcntl(iSock,F_GETFL,NULL);
lFcntlArg|=O_NONBLOCK;
fcntl(iSock,F_SETFL,lFcntlArg);

//Fallback to DBIP1
memset(&sockaddr_inMySQLServer,0,sizeof(sockaddr_inMySQLServer));
sockaddr_inMySQLServer.sin_family=AF_INET;
sockaddr_inMySQLServer.sin_addr.s_addr=inet_addr(DBIP1);
sockaddr_inMySQLServer.sin_port=htons(atoi(cPort));
iConRes=connect(iSock,(struct sockaddr *)&sockaddr_inMySQLServer,sizeof(sockaddr_inMySQLServer));
if(iConRes<0)
{
if(errno==EINPROGRESS)
{
tv.tv_sec=0;
tv.tv_usec=SELECT_TIMEOUT_USEC;
FD_ZERO(&myset);
FD_SET(iSock,&myset);
if(select(iSock+1,NULL,&myset,NULL,&tv)>0)
{
lon=sizeof(int);
getsockopt(iSock,SOL_SOCKET,SO_ERROR,(void*)(&valopt),&lon);
if(valopt)
{
printf("Error in connection() %d - %s\n",valopt,strerror(valopt));
}
else
{
//Valid fast connection
close(iSock);//Don't need anymore.
mysql_init(&gMysql);
if(mysql_real_connect(&gMysql,DBIP1,DBLOGIN,DBPASSWD,
DBNAME,DBPORT,DBSOCKET,0))
{
printf("Connected to %s:%s\n",(char *)DBIP1,cPort);
mysql_close(&gMysql);
exit(0);
}
}
}
else
{
printf("DBIP1 else if select()\n");
}
}
else
{
printf("DBIP1 else if errno==EINPROGRESS\n");
}
}
close(iSock);//Don't need anymore.
}