1mysql_optionsv(3) MariaDB Connector/C mysql_optionsv(3)
2 Name
6 mysql_optionsv - Used to set extra connect options and affect behavior
7 of a connection
8 Synopsis
10 #include <mysql.h>
11 int mysql_optionsv(MYSQL * mysql,
13 enum mysql_option,
14 const void * arg,
15 ...);
16 Description
18 Used to set extra connect options and affect behavior for a connection.
19 This function may be called multiple times to set several options.
20 mysql_optionsv() should be called after mysql_init(3).
21 Options
23 The following table shows which variable type to use for each option.
24 Variable Type Values
26 ──────────────────────────────────────────────────────────────────────────
27 my_bool MYSQL_OPT_RECONNECT, MYSQL_SE‐
28 CURE_AUTH, MYSQL_REPORT_DATA_TRUN‐
29 CATION, MYSQL_OPT_SSL_ENFORCE,
30 MYSQL_OPT_SSL_VERIFY_SERVER_CERT
31 unsigned int MYSQL_OPT_PORT, MYSQL_OPT_LOCAL_IN‐
32 FILE, MYSQL_OPT_CONNECT_TIMEOUT,
33 MYSQL_OPT_PROTOCOL,
34 MYSQL_OPT_READ_TIMEOUT,
35 MYSQL_OPT_WRITE_TIMEOUT
36 unsigned long MYSQL_OPT_NET_BUFFER_LENGTH,
37 MYSQL_OPT_MAX_ALLOWED_PACKET
38 const char * MYSQL_INIT_COMMAND, MARI‐
39 ADB_OPT_UNIXSOCKET, MARI‐
40 ADB_OPT_PASSWORD , MARIADB_OPT_US‐
41 ER, MARIADB_OPT_HOST, MARI‐
42 ADB_OPT_SCHEMA, MYSQL_OPT_SSL_KEY,
43 MYSQL_OPT_SSL_CERT,
44 MYSQL_OPT_SSL_CA, MYSQL_OPT_SSL_CA‐
45 PATH, MYSQL_SET_CHARSET_NAME,
46 MYSQL_SET_CHARSET_DIR,
47 MYSQL_OPT_SSL_CIPHER,
48 MYSQL_SHARED_MEMORY_BASE_NAME,
49 MYSQL_PLUGIN_DIR, MYSQL_DE‐
50 FAULT_AUTH, MARIADB_OPT_SSL_FP,
51 MARIADB_OPT_SSL_FP_LIST, MARI‐
52 ADB_OPT_TLS_PASSPHRASE, MARI‐
53 ADB_OPT_TLS_VERSION,
54 MYSQL_OPT_BIND, MYSQL_OPT_CON‐
55 NECT_ATTR_DELETE, MYSQL_OPT_CON‐
56 NECT_ATTR_ADD, MARIADB_OPT_CONNEC‐
57 TION_HANDLER, MYSQL_SERVER_PUB‐
58 LIC_KEY, MARIADB_OPT_RESTRICT‐
59 ED_AUTH
60 - MYSQL_OPT_CONNECT_ATTR_RESET
61 void * MARIADB_OPT_PROXY_HEADER
62 • MYSQL_INIT_COMMAND
64 Command(s) which will be executed when connecting and reconnecting to
65 the server.
66 • MYSQL_OPT_COMPRESS
68 Use the compressed protocol for client server communication. If the
69 server doesn’t support compressed protocol, the default protocol will
70 be used.
71 • MYSQL_OPT_CONNECT_TIMEOUT
73 Connect timeout in seconds. This value will be passed as an unsigned
74 ##int## parameter.
75 • MYSQL_OPT_LOCAL_INFILE
77 Enable or disable the use of LOAD DATA LOCAL INFILE
78 • MYSQL_OPT_NAMED_PIPE
80 For Windows operating systems only: Use named pipes for client/server
81 communication.
82 • MYSQL_PROGRESS_CALLBACK
84 Specifies a callback function which will be able to visualize the
85 progress of certain long running statements (i.e. LOAD DATA LOCAL IN‐
86 FILE or ALTER TABLE). The callback function must be defined as fol‐
87 lowed:
88 static void report_progress(const MYSQL *mysql __attribute__((unused)),
90 uint stage, uint max_stage,
91 double progress __attribute__((unused)),
92 const char *proc_info __attribute__((unused)),
93 uint proc_info_length __attribute__((unused)))
94 • MYSQL_OPT_PROTOCOL
96 Specify the type of client/server protocol. Possible values are:
97 MYSQL_PROTOCOL_TCP, MYSQL_PROTOCOL_SOCKET, MYSQL_PROTOCOL_PIPE and
98 MYSQL_PROTOCOL_MEMORY.
99 • MYSQL_OPT_RECONNECT
101 Enable or disable automatic reconnect.
102 • MYSQL_OPT_READ_TIMEOUT
104 Specifies the timeout in seconds for reading packets from the server.
105 • MYSQL_OPT_WRITE_TIMEOUT
107 Specifies the timeout in seconds for sending packets to the server.
108 • MYSQL_READ_DEFAULT_FILE
110 Read options from named configuration file. To read from default
111 my.cnf configuration file, a NULL pointer has to be passed with option
112 MYSQL_READ_DEFAULT_GROUP. Note: MariaDB Connector/C will not read the
113 configuration by default. If MYSQL_READ_DEFAULT_FILE is specified the
114 following sections will be always processed:
115 • [client]
117 • [client-server]
119 • [client-mariadb]
121 • MYSQL_READ_DEFAULT_GROUP
123 Read options from the named group from default configuration file (con‐
124 fig_files) or the file specified with MYSQL_READ_DEFAULT_FILE.
125 • MYSQL_REPORT_DATA_TRUNCATION
127 Enable or disable reporting data truncation errors for prepared state‐
128 ments.
129 • MYSQL_OPT_BIND
131 Specify the network interface from which to connect to MariaDB Server.
132 • MYSQL_PLUGIN_DIR
134 Specify the location of client plugins.
135 • MYSQL_OPT_NONBLOCK
137 Specify stack size for non blocking operations. The argument for
138 MYSQL_OPT_NONBLOCK is the size of the stack used to save the state of a
139 non-blocking operation while it is waiting for I/O and the application
140 is doing other processing. Normally, applications will not have to
141 change this, and it can be passed as zero to use the default value.
142 • MARIADB_OPT_CONNECTION_HANDLER
144 Specify the name of a connection handler plugin.
145 • MARIADB_OPT_USERDATA
147 Bundle user data to the current connection, e.g. for use in connection
148 handler plugins. This option requires 4 parameters: connection, op‐
149 tion, key and value:
150 mysql_optionsv(mysql, MARIADB_OPT_USERDATA, (void *)"ssh_user", (void *)ssh_user);
152 • MARIADB_OPT_CONNECTION_READ_ONLY
154 This option is used by connection handler plugins and indicates that
155 the current connection will be used for read operations only.
156 • MYSQL_OPT_CAN_HANDLE_EXPIRED_PASSWORDS
158 If this option is set, the client indicates that it will be able to
159 handle expired passwords by setting the CLIENT_CAN_HANDLE_EXPIRED_PASS‐
160 WORDS capability flag. If the password has expired and CLIENT_CAN_HAN‐
161 DLE_EXPIRED_PASSWORDS is set, the server will not return an error when
162 connecting, but put the connection in sandbox mode, where all commands
163 will return error 1820 (ER_MUST_CHANGE_PASSWORD) unless a new password
164 was set. This option was added in MariaDB Connector/C 3.0.4
165 TLS/SSL and Security options
167 • MYSQL_OPT_SSL_KEY
168 Specify the name of a key for a secure connection. If the key is pro‐
169 tected with a passphrase, the passphrase needs to be specified with
170 MARIADB_OPT_PASSPHRASE option.
171 • MYSQL_OPT_SSL_CERT
173 Specify the name of a certificate for a secure connection.
174 • MYSQL_OPT_SSL_CA
176 Specify the name of a file which contains one or more trusted CAs.
177 • MYSQL_OPT_SSL_CAPATH
179 Specify the path which contains trusted CAs.
180 • MYSQL_OPT_SSL_CIPHER
182 Specify one or more (SSLv3, TLSv1.0 or TLSv1.2) cipher suites for TLS
183 encryption. Even if Connector/C supports TLSv1.3 protocol, it is not
184 possible yet to specify TLSv1.3 cipher suites.
185 • MYSQL_OPT_SSL_CRL
187 Specify a file with a certificate revocation list.
188 • MYSQL_OPT_SSL_CRLPATH
190 Specify a directory with contains files with certificate revocation
191 lists.
192 • MARIADB_OPT_SSL_FP
194 Specify the SHA1 fingerprint of a server certificate for validation
195 during the TLS handshake.
196 • MARIADB_OPT_SSL_FP
198 Specify a file which contains one or more SHA1 fingerprints of server
199 certificates for validation during the TLS handshake.
200 • MARIADB_OPT_SSL_PASPHRASE
202 Specify a passphrase for a passphrase protected client key.
203 • MYSQL_OPT_SSL_VERIFY_SERVER_CERT
205 Enable (or disable) the verification of the hostname against common
206 name (CN) of the server’s host certificate.
207 • MYSQL_SERVER_PUBLIC_KEY
209 Specifies the name of the file which contains the RSA public key of the
210 database server. The format of this file must be in PEM format. This
211 option is used by the caching_sha2_password plugin and was added in
212 Connector/C 3.1.0
213 • MARIADB_OPT_TLS_CIPHER_STRENGTH
215 This option is not in use anymore.
216 • MARIADB_OPT_RESTRICTED_AUTH
218 Specifies one or more comma separated authentication plugins which are
219 allowed for authentication. If the database server asks for an authen‐
220 tication plugin not listed in this option, MariaDB Connector/C will re‐
221 turn an error. This option was added in MariaDB Connector/C 3.3.0
222 Proxy settings
224 As per the proxy protocol specification, the connecting client can pre‐
225 fix its first packet with a proxy protocol header. The server will
226 parse the header and assume the client’s IP address is the one set in
227 the proxy header. * MARIADB_OPT_PROXY_HEADER - specifies the proxy
228 header which will be prefixed to the first packet. Parameters are void
229 * for the prefix buffer and size_t for length of the buffer:
230 const char *hdr="PROXY TCP4 192.168.0.1 192.168.0.11 56324 443\r\n";
232 mysql_optionsv(mysql, MARIADB_OPT_PROXY_HEADER, hdr, strlen(hdr));
233 Connection Attributes
235 Connection attributes are stored in the session_connect_attrs and ses‐
236 sion_account_connect_attrsPerformance Schema tables. By default, Mari‐
237 aDB Connector/C sends the following connection attributes to the serv‐
238 er: * _client_name: always “libmariadb” * _client_version: version of
239 MariaDB Connector/C * _os: operation system * _pid: process id * _plat‐
240 form: e.g. x86 or x64 * _server_host: the hostname (as specified in
241 mysql_real_connect). This attribute was added in Connector/C 3.0.5
242 Note: If the Performance Schema is disabled, connection attributes will
244 not be stored on server.
245 • MYSQL_OPT_CONNECT_ATTR_DELETE
247 Deletes a connection attribute for the given key.
248 • MYSQL_OPT_CONNECT_ATTR_ADD
250 Adds a key/value pair to connection attributes.
251 • MYSQL_OPT_CONNECT_ATTR_RESET
253 Clears the current list of connection attributes.
254 See Also
256 mysql_init(3) mysql_real_connect(3)
257Version 3.3.1 mysql_optionsv(3)