5.4.54 mysql_options()

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



Description
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. To retrieve option values, use mysql_get_option().

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 Section
3.6.1, “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.


MYSQL_DEFAULT_AUTH (argument type: char *)
The name of the authentication plugin to use.


MYSQL_ENABLE_CLEARTEXT_PLUGIN (argument type: 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: 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.

As of MySQL 8.0.18, MYSQL_OPT_COMPRESS becomes a legacy option, due to the
introduction of the MYSQL_OPT_COMPRESSION_ALGORITHMS option for more control
over connection compression (see Configuring Connection Compression). The
meaning of MYSQL_OPT_COMPRESS depends on whether 
MYSQL_OPT_COMPRESSION_ALGORITHMS is specified:


When MYSQL_OPT_COMPRESSION_ALGORITHMS is not specified, enabling
MYSQL_OPT_COMPRESS is equivalent to specifying a client-side algorithm set
of zlib,uncompressed.

When MYSQL_OPT_COMPRESSION_ALGORITHMS is specified, enabling
MYSQL_OPT_COMPRESS is equivalent to specifying an algorithm set of zlib and
the full client-side algorithm set is the union of zlib plus the algorithms
specified by MYSQL_OPT_COMPRESSION_ALGORITHMS. For example, with
MYSQL_OPT_COMPRESS enabled and MYSQL_OPT_COMPRESSION_ALGORITHMS set to
zlib,zstd, the permitted-algorithm set is zlib plus zlib,zstd; that is,
zlib,zstd. With MYSQL_OPT_COMPRESS enabled and MYSQL_OPT_COMPRESSION_ALGORITHMS 
set to zstd,uncompressed, the permitted-algorithm set is zlib plus zstd,
uncompressed; that is, zlib, zstd, uncompressed.


 As of MySQL 8.0.18, MYSQL_OPT_COMPRESS is deprecated. It is subject to
removal in a future MySQL version. See Configuring Legacy Connection
Compression.
MYSQL_OPT_COMPRESSION_ALGORITHMS (argument type: const char *)

 The permitted compression algorithms for connections to the server. The
available algorithms are the same as for the protocol_compression_algorithms
system variable. If this option is not specified, the default value is
uncompressed.

 For more information, see Connection Compression Control.

 This option was added in MySQL 8.0.18. For asynchronous operations, the
option has no effect until MySQL 8.0.21.
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_GET_SERVER_PUBLIC_KEY (argument type: bool *)

 Enables the client to request from the server the public key required for
RSA key pair-based password exchange. This option applies to clients that
authenticate with the caching_sha2_password authentication plugin. For that
plugin, the server does not send the public key unless requested. This
option is ignored for accounts that do not authenticate with that plugin. 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.

 If MYSQL_SERVER_PUBLIC_KEY is given and specifies a valid public key file,
it takes precedence over MYSQL_OPT_GET_SERVER_PUBLIC_KEY.

 For information about the caching_sha2_password plugin, see Caching SHA-2
Pluggable Authentication.

MYSQL_OPT_LOAD_DATA_LOCAL_DIR (argument type: char *)

 This option affects the client-side LOCAL capability for LOAD DATA
operations. It specifies the directory in which files named in LOAD DATA
LOCAL statements must be located. The effect of MYSQ
L_OPT_LOAD_DATA_LOCAL_DIR depends on whether LOCAL data loading is enabled
or disabled:


If LOCAL data loading is enabled, either by default in the MySQL client
library or by explicitly enabling MYSQL_OPT_LOCAL_INFILE, the
MYSQL_OPT_LOAD_DATA_LOCAL_DIR option has no effect.
If LOCAL data loading is disabled, either by default in the MySQL client
library or by explicitly disabling MYSQL_OPT_LOCAL_INFILE, the
MYSQL_OPT_LOAD_DATA_LOCAL_DIR option can be used to designate a permitted
directory for locally loaded files. In this case, LOCAL data loading is
permitted but restricted to files located in the designated directory.
Interpretation of the MYSQL_OPT_LOAD_DATA_LOCAL_DIR value is as follows:
	

If the value is the null pointer (the default), it names no directory, with
the result that no files are permitted for LOCAL data loading.

If the value is a directory path name, LOCAL data loading is permitted but
restricted to files located in the named directory. Comparison of the
directory path name and the path name of files to be loaded is case
-sensitive regardless of the case-sensitivity of the underlying file
system.


 For example, to explicitly disable local data loading except for files
located in the /my/local/data directory, invoke mysql_options() like this:
	unsigned int i = 0;
mysql_options( &mysql, MYSQL_OPT_LOCAL_INFILE, &i);
mysql_options( &mysql, MYSQL_OPT_LOAD_DATA_LOCAL_DIR, "/my/local/data");

The MYSQL_OPT_LOAD_DATA_LOCAL_DIR option can be set any time during the life of
the mysql connection handler. Once set, the value applies to all subsequent 
LOCAL load operations until such time as the value is changed.

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

 The MYSQL_OPT_LOAD_DATA_LOCAL_DIR option was added in MySQL 8.0.21.

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.


 If LOCAL capability is disabled, the MYSQL_OPT_LOAD_DATA_LOCAL_DIR option
can be used to permit restricted local loading of files located in a
designated directory.

 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_MAX_ALLOWED_PACKET (argument: unsigned long *)

 This option sets the client-side maximum size of the buffer for
client/server communication. If the mysql argument is non-NULL, the call
sets the option value for that session. If mysql is NULL, the call sets the
option value globally for all subsequent sessions for which a session
-specific value is not specified.

 Because it is possible to set a session or global maximum buffer size,
depending on whether the mysql argument is non-NULL or NULL,
mysql_get_option() similarly returns the session or global value depending
on its mysql argument.

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_NET_BUFFER_LENGTH (argument: unsigned long *)

 This option sets the client-side buffer size for TCP/IP and socket
communication.

MYSQL_OPT_OPTIONAL_RESULTSET_METADATA (argument type: bool *)

 This flag makes result set metadata optional. It is an alternative to
setting the CLIENT_OPTIONAL_RESULTSET_METADATA connection flag for the
mysql_real_connect() function. For details about managing result set
metadata transfer, see Section 3.6.7, “Optional Result Set Metadata”.

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.

MYSQL_OPT_RECONNECT (argument type: bool *)
	Note
The MYSQL_OPT_RECONNECT option is still available but is deprecated; expect
it to be removed in a future version of MySQL.

 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 Section 3.6.8, “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 compiled with NDB Cluster support.

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_FIPS_MODE (argument type: unsigned int *)

 The MYSQL_OPT_SSL_FIPS_MODE option is deprecated as of MySQL 8.0.34 and is
subject to removal in a future version of MySQL.

 Controls whether to enable FIPS mode on the client side. The
MYSQL_OPT_SSL_FIPS_MODE option differs from other MYSQL_OPT_SSL_xxx options
in that it is not used to establish encrypted connections, but rather to
affect which cryptographic operations to permit. See FIPS Support.

 Permitted option values are SSL_FIPS_MODE_OFF, SSL_FIPS_MODE_ON, and
SSL_FIPS_MODE_STRICT.
	Note
If the OpenSSL FIPS Object Module is not available, the only permitted
value for MYSQL_OPT_SSL_FIPS_MODE is SSL_FIPS_MODE_OFF. In this case,
setting MYSQL_OPT_SSL_FIPS_MODE to SSL_FIPS_MODE_ON or SSL_FIPS_MODE_STRICT
causes the client to produce a warning at startup and to operate in non-FIPS
mode.

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:
SSL_MODE_DISABLED, SSL_MODE_PREFERRED, SSL_MODE_REQUIRED,
SSL_MODE_VERIFY_CA, SSL_MODE_VERIFY_IDENTITY. If this option is not
specified, the default is SSL_MODE_PREFERRED. These modes are the permitted
values of the mysql_ssl_mode enumeration defined in mysql.h. For more
information about the security states, see the description of --ssl-mode in
Command Options for Encrypted Connections.

MYSQL_OPT_SSL_SESSION_DATA (argument type: void *)

 The session data to use for session reuse when establishing the next
encrypted connection. It should be set before mysql_real_connect() and after
mysql_init(). It expects the PEM session data as returned by
mysql_get_ssl_session_data() and copies the result into the MYSQL handle. It
is reset to nullptr (the default) after mysql_real_connect(), unless
specified otherwise through the CLIENT_REMEMBER_OPTIONS flag.

 If specified, an attempt is made to reuse the session at TLS establishment
time. mysql_get_option() returns the handle set by mysql_options(), if any,
and it does not increase the number reference counts.

 This option was added in MySQL 8.0.29.

MYSQL_OPT_TLS_CIPHERSUITES (argument type: char *)

 Which ciphersuites the client permits for encrypted connections that use
TLSv1.3. The value is a list of one or more colon-separated ciphersuite
names. The ciphersuites that can be named for this option depend on the SSL
library used to compile MySQL. For details, see Encrypted Connection TLS
Protocols and Ciphers.

 This option was added in MySQL 8.0.16.

MYSQL_OPT_TLS_VERSION (argument type: char *)

 Which protocols the client permits for encrypted connections. The value is
a list of one or more comma-separated protocol versions. The protocols that
can be named for this option depend on the SSL library used to compile
MySQL. For details, see Encrypted Connection TLS Protocols and Ciphers.

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_OPT_ZSTD_COMPRESSION_LEVEL (argument type: unsigned int *)

 The compression level to use for connections to the server that use the
zstd compression algorithm. The permitted levels are from 1 to 22, with
larger values indicating increasing levels of compression. If this option is
not specified, the default zstd compression level is 3. The compression
level setting has no effect on connections that do not use zstd
compression.

 For more information, see Connection Compression Control.

 This option was added in MySQL 8.0.18. For asynchronous operations, the
option has no effect until MySQL 8.0.21.

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: bool *)

 Enable or disable reporting of data truncation errors for prepared
statements using the error member of MYSQL_BIND structures. (Default:
enabled.)

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 authenticate with the sha256_password or
caching_sha2_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.

 If MYSQL_SERVER_PUBLIC_KEY is given and specifies a valid public key file,
it takes precedence over MYSQL_OPT_GET_SERVER_PUBLIC_KEY.

 For information about the sha256_password and caching_sha2_password
plugins, see SHA-256 Pluggable Authentication, and Caching SHA-2 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_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=dir_name 
The directory where character sets are installed.
compress 
Use the compressed client/server protocol.
connect-timeout=seconds 
The connect timeout in seconds. On Linux this
timeout is also used for waiting for the first answer from the server.
database=db_name 
Connect to this database if no database was specified in
the connect command.
debug 
Debug options.
default-character-set=charset_name 
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=host_name 
Default host name.
init-command=stmt 
Statement to execute when connecting to MySQL server.
Automatically re-executed if reconnection occurs.
interactive-timeout=seconds 
Same as specifying CLIENT_INTERACTIVE to
mysql_real_connect(). See Section 5.4.58, “mysql_real_connect()”.
local-infile[={0|1}] 
If no argument or nonzero argument, enable use of LOAD
DATA LOCAL; otherwise disable.
max_allowed_packet=bytes 
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=password 
Default password.
pipe 
Use named pipes to connect to a MySQL server on Windows.
port=port_num 
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=name 
Shared-memory name to use to connect to
server.
socket={file_name|pipe_name} 
Default socket file.
ssl-ca=file_name 
Certificate Authority file.
ssl-capath=dir_name 
Certificate Authority directory.
ssl-cert=file_name 
Certificate file.
ssl-cipher=cipher_list 
Permissible SSL ciphers.
ssl-key=file_name 
Key file.
timeout=seconds 
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.


Return Values
Zero for success. Nonzero if you specify an unknown option.



Example
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 ));
}