MySQL 5.6 C API Developer Guide
int mysql_options(MYSQL *mysql, enum mysql_option option, const void *arg)
Can be used to set extra connect options and affect behavior for a connection. This function may be called multiple times to set several options.
Call mysql_options()
after
mysql_init()
and before
mysql_connect()
or
mysql_real_connect()
.
The option
argument is the option that you
want to set; the arg
argument is the value
for the option. If the option is an integer, specify a pointer
to the value of the integer as the arg
argument.
Options for information such as SSL certificate and key files are used to establish an encrypted connection if such connections are available, but do not enforce any requirement that the connection obtained be encrypted. To require an encrypted connection, use the technique described in Chapter 15, C API Support for Encrypted Connections.
The following list describes the possible options, their
effect, and how arg
is used for each
option. For option descriptions that indicate
arg
is unused, its value is irrelevant; it
is conventional to pass 0. Several of the options apply only
when the application is linked against the
libmysqld
embedded server library and are
unused for applications linked against the
libmysqlclient
client library.
MYSQL_DEFAULT_AUTH
(argument type:
char *
)
The name of the authentication plugin to use.
MYSQL_ENABLE_CLEARTEXT_PLUGIN
(argument
type: my_bool *
)
Enable the mysql_clear_password
cleartext authentication plugin. See
Client-Side Cleartext Pluggable Authentication.
MYSQL_INIT_COMMAND
(argument type:
char *
)
SQL statement to execute when connecting to the MySQL server. Automatically re-executed if reconnection occurs.
MYSQL_OPT_BIND
(argument: char
*
)
The network interface from which to connect to the server. This is used when the client host has multiple network interfaces. The argument is a host name or IP address (specified as a string).
MYSQL_OPT_CAN_HANDLE_EXPIRED_PASSWORDS
(argument type: my_bool *
)
Indicate whether the client can handle expired passwords. See Server Handling of Expired Passwords.
MYSQL_OPT_COMPRESS
(argument: not used)
Compress all information sent between the client and the server if possible. See Connection Compression Control.
MYSQL_OPT_CONNECT_ATTR_DELETE
(argument
type: char *
)
Given a key name, this option deletes a key-value pair from the current set of connection attributes to pass to the server at connect time. The argument is a pointer to a null-terminated string naming the key. Comparison of the key name with existing keys is case-sensitive.
See also the description for the
MYSQL_OPT_CONNECT_ATTR_RESET
option, as
well as the description for the
MYSQL_OPT_CONNECT_ATTR_ADD
option in
the description of the
mysql_options4()
function.
That function description also includes a usage example.
The Performance Schema exposes connection attributes
through the
session_connect_attrs
and
session_account_connect_attrs
tables. See
Performance Schema Connection Attribute Tables.
MYSQL_OPT_CONNECT_ATTR_RESET
(argument
not used)
This option resets (clears) the current set of connection attributes to pass to the server at connect time.
See also the description for the
MYSQL_OPT_CONNECT_ATTR_DELETE
option,
as well as the description for the
MYSQL_OPT_CONNECT_ATTR_ADD
option in
the description of the
mysql_options4()
function.
That function description also includes a usage example.
The Performance Schema exposes connection attributes
through the
session_connect_attrs
and
session_account_connect_attrs
tables. See
Performance Schema Connection Attribute Tables.
MYSQL_OPT_CONNECT_TIMEOUT
(argument
type: unsigned int *
)
The connect timeout in seconds.
MYSQL_OPT_GUESS_CONNECTION
(argument:
not used)
For an application linked against the
libmysqld
embedded server library, this
option enables the library to guess whether to use the
embedded server or a remote server. “Guess”
means that if the host name is set and is not
localhost
, it uses a remote server.
This behavior is the default.
MYSQL_OPT_USE_EMBEDDED_CONNECTION
and
MYSQL_OPT_USE_REMOTE_CONNECTION
can be
used to override it. This option is ignored for
applications linked against the
libmysqlclient
client library.
MYSQL_OPT_LOCAL_INFILE
(argument type:
optional pointer to unsigned int
)
This option affects client-side LOCAL
capability for LOAD DATA
operations. By default, LOCAL
capability is determined by the default compiled into the
MySQL client library. To control this capability
explicitly, invoke
mysql_options()
to enable
or disable the MYSQL_OPT_LOCAL_INFILE
option:
To enable LOCAL
data loading, set
the pointer to point to an unsigned
int
that has a nonzero value, or omit the
pointer argument.
To disable LOCAL
data loading, set
the pointer to point to an unsigned
int
that has a zero value.
The ENABLED_LOCAL_INFILE
CMake option controls the client
library default for local data loading (see
MySQL Source-Configuration Options).
Successful use of LOCAL
load operations
by a client also requires that the server permits local
loading; see Security Considerations for LOAD DATA LOCAL
MYSQL_OPT_NAMED_PIPE
(argument: not
used)
Use a named pipe to connect to the MySQL server on Windows, if the server permits named-pipe connections.
MYSQL_OPT_PROTOCOL
(argument type:
unsigned int *
)
Transport protocol to use for connection. Specify one of
the enum values of mysql_protocol_type
defined in mysql.h
.
MYSQL_OPT_READ_TIMEOUT
(argument type:
unsigned int *
)
The timeout in seconds for each attempt to read from the
server. There are retries if necessary, so the total
effective timeout value is three times the option value.
You can set the value so that a lost connection can be
detected earlier than the TCP/IP
Close_Wait_Timeout
value of 10 minutes.
Implementation of this timeout uses mechanisms that may not be available on all platforms. On such a platform, a client that issues a read call might under certain circumstances wait without timing out. For example, a client might not time out if the server is not responding because it is waiting for a “disk full” condition to clear.
MYSQL_OPT_RECONNECT
(argument type:
my_bool *
)
Enable or disable automatic reconnection to the server if the connection is found to have been lost. Reconnect is off by default; this option provides a way to set reconnection behavior explicitly. See Chapter 20, C API Automatic Reconnection Control.
MYSQL_OPT_RETRY_COUNT
(argument type:
unsigned int *
)
The retry count for I/O-related system calls that are interrupted while connecting to the server or communicating with it. If this option is not specified, the default value is 1 (1 retry if the initial call is interrupted for 2 tries total).
This option can be used only by clients that link against a C client library compiiled with NDB Cluster support. It is available as of MySQL NDB Cluster 7.4.11.
MYSQL_OPT_SSL_CA
(argument type:
char *
)
The path name of the Certificate Authority (CA) certificate file. This option, if used, must specify the same certificate used by the server.
MYSQL_OPT_SSL_CAPATH
(argument type:
char *
)
The path name of the directory that contains trusted SSL CA certificate files.
MYSQL_OPT_SSL_CERT
(argument type:
char *
)
The path name of the client public key certificate file.
MYSQL_OPT_SSL_CIPHER
(argument type:
char *
)
The list of permissible ciphers for SSL encryption.
MYSQL_OPT_SSL_CRL
(argument type:
char *
)
The path name of the file containing certificate revocation lists.
MYSQL_OPT_SSL_CRLPATH
(argument type:
char *
)
The path name of the directory that contains files containing certificate revocation lists.
MYSQL_OPT_SSL_KEY
(argument type:
char *
)
The path name of the client private key file.
MYSQL_OPT_SSL_MODE
(argument type:
unsigned int *
)
The security state to use for the connection to the
server. The only permitted arument value is
SSL_MODE_REQUIRED
(require an encrypted
connection). If set, this option causes
mysql_real_connect()
to
fail if an encrypted connection cannot be obtained,
without falling back to an unencrypted connection. Thus,
mysql_real_connect()
returns an error if the server does not support SSL or the
client is not configured to use SSL. For more information
about the security states, see the description of
--ssl-mode
in
Command Options for Encrypted Connections.
To require an encrypted connection in MySQL
5.6, the standard MySQL client programs call
mysql_options()
to set
MYSQL_OPT_SSL_MODE
if the
--ssl-mode=REQUIRED
command-line option was specified. Third-party
applications that must be able to require encrypted
connections can use the technique described in
Chapter 15, C API Support for Encrypted Connections.
This option was added in MySQL 5.6.36.
MYSQL_OPT_SSL_VERIFY_SERVER_CERT
(argument type: my_bool *
)
Enable or disable verification of the server's Common Name identity in its certificate against the host name used when connecting to the server. The connection is rejected if there is a mismatch. For encrypted connections, this feature can be used to prevent man-in-the-middle attacks. Identity verification is disabled by default.
MYSQL_OPT_USE_EMBEDDED_CONNECTION
(argument: not used)
For an application linked against the
libmysqld
embedded server library, this
option forces the use of the embedded server for the
connection. It is ignored for applications linked against
the libmysqlclient
client library.
MYSQL_OPT_USE_REMOTE_CONNECTION
(argument: not used)
For an application linked against the
libmysqld
embedded server library, this
option forces the use of a remote server for the
connection. It is ignored for applications linked against
the libmysqlclient
client library.
MYSQL_OPT_USE_RESULT
(argument: not
used)
This option is unused.
MYSQL_OPT_WRITE_TIMEOUT
(argument type:
unsigned int *
)
The timeout in seconds for each attempt to write to the server. There is a retry if necessary, so the total effective timeout value is two times the option value.
MYSQL_PLUGIN_DIR
(argument type:
char *
)
The directory in which to look for client plugins.
MYSQL_READ_DEFAULT_FILE
(argument type:
char *
)
Read options from the named option file instead of from
my.cnf
.
MYSQL_READ_DEFAULT_GROUP
(argument
type: char *
)
Read options from the named group from
my.cnf
or the file specified with
MYSQL_READ_DEFAULT_FILE
.
MYSQL_REPORT_DATA_TRUNCATION
(argument
type: my_bool *
)
Enable or disable reporting of data truncation errors for
prepared statements using the error
member of MYSQL_BIND
structures.
(Default: enabled.)
MYSQL_SECURE_AUTH
(argument type:
my_bool *
)
Whether to connect to a server that does not support the password hashing used in MySQL 4.1.1 and later. This option is enabled by default.
MYSQL_SERVER_PUBLIC_KEY
(argument type:
char *
)
The path name to a file in PEM format containing a
client-side copy of the public key required by the server
for RSA key pair-based password exchange. This option
applies to clients that connect to the server using an
account that authenticates with the
sha256_password
authentication plugin.
This option is ignored for accounts that do not
authenticate with one of those plugins. It is also ignored
if RSA-based password exchange is not used, as is the case
when the client connects to the server using a secure
connection.
For information about the
sha256_password
plugin, see
SHA-256 Pluggable Authentication.
MYSQL_SET_CHARSET_DIR
(argument type:
char *
)
The path name of the directory that contains character set definition files.
MYSQL_SET_CHARSET_NAME
(argument type:
char *
)
The name of the character set to use as the default
character set. The argument can be
MYSQL_AUTODETECT_CHARSET_NAME
to cause
the character set to be autodetected based on the
operating system setting (see
Connection Character Sets and Collations).
MYSQL_SET_CLIENT_IP
(argument type:
char *
)
For an application linked against the
libmysqld
embedded server library (when
libmysqld
is compiled with
authentication support), this option means that the user
is considered to have connected from the specified IP
address (specified as a string) for authentication
purposes. It is ignored for applications linked against
the libmysqlclient
client library.
MYSQL_SHARED_MEMORY_BASE_NAME
(argument
type: char *
)
The name of the shared-memory object for communication to
the server on Windows, if the server supports
shared-memory connections. Specify the same value as used
for the
shared_memory_base_name
system variable. of the mysqld server
you want to connect to.
The client
group is always read if you use
MYSQL_READ_DEFAULT_FILE
or
MYSQL_READ_DEFAULT_GROUP
.
The specified group in the option file may contain the following options.
Option | Description |
---|---|
character-sets-dir= |
The directory where character sets are installed. |
compress |
Use the compressed client/server protocol. |
connect-timeout= |
The connect timeout in seconds. On Linux this timeout is also used for waiting for the first answer from the server. |
database= |
Connect to this database if no database was specified in the connect command. |
debug |
Debug options. |
default-character-set= |
The default character set to use. |
disable-local-infile |
Disable use of LOAD DATA
LOCAL . |
enable-cleartext-plugin |
Enable the mysql_clear_password cleartext
authentication plugin. |
host= |
Default host name. |
init-command= |
Statement to execute when connecting to MySQL server. Automatically re-executed if reconnection occurs. |
interactive-timeout= |
Same as specifying CLIENT_INTERACTIVE to
mysql_real_connect() .
See Section 7.53, “mysql_real_connect()”. |
local-infile[={0|1}] |
If no argument or nonzero argument, enable use of
LOAD DATA
LOCAL ; otherwise disable. |
max_allowed_packet= |
Maximum size of packet that client can read from server. |
multi-queries , multi-results |
Enable multiple result sets from multiple-statement executions or stored procedures. |
multi-statements |
Enable the client to send multiple statements in a single string
(separated by ; characters). |
password= |
Default password. |
pipe |
Use named pipes to connect to a MySQL server on Windows. |
port= |
Default port number. |
protocol={TCP|SOCKET|PIPE|MEMORY} |
The protocol to use when connecting to the server. |
return-found-rows |
Tell mysql_info() to return found rows
instead of updated rows when using
UPDATE . |
shared-memory-base-name= |
Shared-memory name to use to connect to server. |
socket={ |
Default socket file. |
ssl-ca= |
Certificate Authority file. |
ssl-capath= |
Certificate Authority directory. |
ssl-cert= |
Certificate file. |
ssl-cipher= |
Permissible SSL ciphers. |
ssl-key= |
Key file. |
timeout= |
Like connect-timeout . |
user |
Default user. |
timeout
has been replaced by
connect-timeout
, but
timeout
is still supported for backward
compatibility.
For more information about option files used by MySQL programs, see Using Option Files.
The following mysql_options()
calls request the use of compression in the client/server
protocol, cause options to be read from the
[odbc]
group in option files, and disable
transaction autocommit mode:
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));
}