mysql_options()|V2.0.0|OceanBase Connector/C

You can call the mysql_options() function to set extra connect options and affect the behavior for a connection.

Syntax

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

Arguments

option: the option to be set.
arg: the value of the option. If the option is an integer, specify a pointer to the value of the integer as the arg argument.

Return values

0 is returned for an execution success, and a non-zero value is returned if an unknown option is specified.

Notes

You can call this function multiple times to set several options.

Call mysql_options() after mysql_init() and before mysql_connect() or mysql_real_connect().

Options for information such as SSL certificates and key files are used to establish encrypted connections if such connections are available. However, it is not mandatory to encrypt the connections.

The following describes the available options for mysql_options() and how arg is used for each option. For options that do not use arg, 0 is assigned.

MYSQL_DEFAULT_AUTH (argument type: char *): the name of the authentication plug-in to use.
MYSQL_ENABLE_CLEARTEXT_PLUGIN (argument type: my_bool *): enables the mysql_clear_password plaintext authentication plug-in.
MYSQL_INIT_COMMAND (argument type: char *): the SQL statement to execute when connecting to the OBServer. The statement is automatically re-executed if reconnection occurs.
MYSQL_OPT_BIND (argument type: char *): the network interface used to connect to the server. This parameter 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 *): indicates whether the client can handle expired passwords.
MYSQL_OPT_COMPRESS (argument type: not used): compresses all information sent between the client and the server.
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 the key name to the server when the connection is created. The argument is a pointer to a null-terminated string naming the key. Comparison of the key name with existing keys is case-sensitive.
MYSQL_OPT_CONNECT_ATTR_RESET (argument not used): resets (clears) the current set of connection attributes to pass to the server when the connection is created.
MYSQL_OPT_CONNECT_TIMEOUT (argument type: unsigned int *): the connection timeout in seconds.
MYSQL_OPT_LOCAL_INFILE (argument type: optional pointer to an unsigned integer): This option affects client-side LOCAL capability for LOAD DATA operations. By default, LOCAL capability is determined by the default value compiled into the OceanBase client library. To control this capability explicitly, call 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 non-zero value, or omit the pointer argument.
- To disable LOCAL data loading, set the pointer to point to an unsigned int whose value is 0.
MYSQL_OPT_NAMED_PIPE (argument type: not used): uses a named pipe to connect to the OBServer on Windows, if the server allows for named-pipe connections.
MYSQL_OPT_PROTOCOL (argument type: unsigned int *): Transport protocol used for connections. Specify one of the enumerated values of mysql_protocol_type defined in mysql.h.
MYSQL_OPT_READ_TIMEOUT (argument type: unsigned int *): the timeout period in seconds for each attempt to read from the server. Retries are performed if necessary. Therefore, the total effective timeout period is three times the option value. You can set the value so that a lost connection can be detected 10 minutes earlier than the TCP/IP Close_Wait_Timeout value.
MYSQL_OPT_RECONNECT (argument type: my_bool *): enables or disables automatic reconnection to the server if the connection is found to have been lost. Reconnection is disabled by default. This option provides a way to explicitly set reconnection behavior.
MYSQL_OPT_RETRY_COUNT (argument type: unsigned int *): the retry count for I/O-related system calls that are interrupted while connecting to or communicating with the server. If this option is not specified, the default value is 1 (1 retry if the initial call is interrupted 2 times).

This option can be used only by clients that link to 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 supported passwords for SSL encryption.
MYSQL_OPT_SSL_CRL (argument type: char *): the path name of the file 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 used for the connection to the server. The only supported value is SSL_MODE_REQUIRED (encrypted connection required). After this argument is specified, if an encrypted connection cannot be obtained, this option will cause mysql_real_connect() to fail instead of rolling back to the unencrypted connection. Therefore, if the server does not support SSL or the client is not configured to use SSL, mysql_real_connect() will return an error.
MYSQL_OPT_SSL_VERIFY_SERVER_CERT (argument type: my_bool *): enables or disables verification of the common name identity of the server in its certificate against the host name used for connecting to the server. The connection is rejected if the common name identity and the host name do not match. For encrypted connections, this feature can be used to prevent man-in-the-middle attacks. By default, identity verification is disabled.
MYSQL_OPT_USE_RESULT (argument type: not used): This option is not used.
MYSQL_OPT_WRITE_TIMEOUT (argument type: unsigned int *): the timeout period in seconds for each attempt to write to the server. Retries are performed if necessary. Therefore, the total effective timeout period is twice the option value.
MYSQL_PLUGIN_DIR (argument type: char *): the directory to search for client plug-ins.
MYSQL_READ_DEFAULT_FILE (argument type: char *): reads options from the named option file instead of from my.cnf.
MYSQL_READ_DEFAULT_GROUP (argument type: char *): reads options from the named group from my.cnf or the file specified by MYSQL_READ_DEFAULT_FILE.
MYSQL_REPORT_DATA_TRUNCATION (argument type: my_bool *): enables or disables reporting of data truncation errors for prepared statements by using the error member of MYSQL_BIND structures.
MYSQL_SECURE_AUTH (argument type: my_bool *): whether to connect to a server that does not support password hashing. 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 authenticate by using the sha256_password authentication plug-in. This option is ignored for accounts that do not authenticate by using one of those plug-ins. It is also ignored if RSA-based password exchange is not used, as is the case when the client connects to the server by using a secure connection.
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 used as the default character set. The argument can be MYSQL_AUTODETECT_CHARSET_NAME to cause the character set to be automatically detected based on the operating system settings.
MYSQL_SHARED_MEMORY_BASE_NAME (argument type: char *): the name of the shared-memory object for communication with the server on Windows, if the server supports shared-memory connections. Specify the same value as the shared_memory_base_name system variable.

The client group is always read if you use MYSQL_READ_DEFAULT_FILE or MYSQL_READ_DEFAULT_GROUP. The following table describes the options that the specified group in the option file may contain.

Option	Description
character-sets-dir=dir_name	The directory where character sets are installed.
compress	Uses the compressed client/server protocol.
connect-timeout=seconds	The connection timeout period in seconds. On Linux, this timeout period is also used for waiting for the first response from the server.
database=db_name	Connects to this database if no database was specified in the connection command.
debug	Debug options.
default-character-set=charset_name	The default character set to use.
disable-local-infile	Disables the use of `LOAD DATA LOCAL`.
enable-cleartext-plugin	Enables the `mysql_clear_password` plaintext authentication plug-in.
host=host_name	The default host name.
init-command=stmt	The statement to be executed when connecting to the OBServer. The statement is automatically re-executed if reconnection occurs.
interactive-timeout=seconds	Same as setting `CLIENT_INTERACTIVE` to `mysql_real_connect()`.
local-infile[={01}]	Enables `LOAD DATA LOCAL` if no argument or non-zero argument is available, or disables the use of it if otherwise.
max_allowed_packet=bytes	The maximum size of packets that the client can read from the server.
multi-queries, multi-results	Enables multiple result sets from multiple-statement executions or stored procedures.
multi-statements	Enables the client to send multiple statements in a single string. The statements are separated with semicolons (`;`).
password=password	The default password.
pipe	Uses named pipes to connect to an OBServer on Windows.
port=port_num	The default port number.
protocol={TCPSOCKETPIPEMEMORY}	The protocol used for connecting to the server.
return-found-rows	Instructs `mysql_info()` to return found rows instead of updated rows when `UPDATE` is used.
shared-memory-base-name=name	The shared-memory name used to connect to the server.
socket={file_namepipe_name}	The default socket file.
ssl-ca=file_name	The CA certificate file.
ssl-capath=dir_name	The directory of the CA certificate file.
ssl-cert=file_name	The certificate file.
ssl-cipher=cipher_list	The allowed SSL passwords.
ssl-key=file_name	The key file.
timeout=seconds	The connection timeout period.
user	The default user.

Note

timeout has been replaced by connect-timeout, but timeout is still supported for backward compatibility.

Customer Stories

Documentation

mysql_options()

Syntax

Return values

Notes