MySQL :: MySQL 8.0 C API Developer Guide :: 5.4.54 mysql_options() (original) (raw)

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, usemysql_get_option().

Call mysql_options() aftermysql_init() and beforemysql_connect() ormysql_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 inSection 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 indicatearg is unused, its value is irrelevant; it is conventional to pass 0.

For example, to explicitly disable local data loading except for files located in the/my/local/data directory, invokemysql_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 themysql 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 (seeMySQL 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.

The client group is always read if you useMYSQL_READ_DEFAULT_FILE orMYSQL_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 tomysql_real_connect(). See Section 5.4.58, “mysql_real_connect()”.
local-infile[={0|1}] If no argument or nonzero argument, enable use ofLOAD 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
return-found-rows Tell mysql_info() to return found rows instead of updated rows when usingUPDATE.
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 byconnect-timeout, buttimeout 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));
}