mysql_optionsv

You are viewing an old version of this article. View the current version here.

Syntax

int mysql_optionsv(MYSQL * mysql,
                   enum mysql_option,
                   const void * arg,
                   ...);
  • mysql - a mysql handle, which was previously allocated by mysql_init() or mysql_real_connect().
  • mysql_option - the option you want to set. See description below.
  • arg - the value for the option.
  • ... - variable argument list

Description

Used to set extra connect options and affect behavior for a connection. This function may be called multiple times to set several options. mysql_optionsv() should be called after mysql_init().

Returns

Returns zero on success, non zero if an error occurred (invalid option or value)

If MYSQL_READ_DEFAULT_FILE is specified the [client] section will be always processed.

Options

  • MYSQL_INIT_COMMAND: Command(s) which will be executed when connecting and reconnecting to the server.

    mysql_optionsv(mysql, MYSQL_INIT_COMMAND, (void *)"CREATE TABLE ...");
    
  • MYSQL_OPT_COMPRESS: Use the compressed protocol for client server communication. If the server doesn't support compressed protocol, the default protocol will be used.

    mysql_optionsv(mysql, MYSQL_OPT_COMPRESS, NULL);
    
  • MYSQL_OPT_CONNECT_TIMEOUT: Connect timeout in seconds. This value will be passed as an unsigned int parameter.

    unsigned int timeout= 5;
    mysql_optionsv(mysql, MYSQL_OPT_CONNECT_TIMEOUT, (void *)&timeout);                   
    
  • MYSQL_OPT_LOCAL_INFILE: Enable or disable use of LOAD DATA LOCAL INFILE

    mysql_optionsv(mysql, MYSQL_OPT_LOCAL_INFILE, NULL);        /* disable */                  
    mysql_optionsv(mysql, MYSQL_OPT_LOCAL_INFILE, (void *)"1"); /* enable */                  
    
  • MARIADB_OPT_VERIFY_LOCAL_INFILE_CALLBACK: Specifies a callback function for filename and/or directory verification. This option was added in Connector/C 2.3.0

    int my_verify_filename(void *data, const char *filename)
    {
      return strcmp((char *)data, filename);
    }
    ...
    char *filename= "mydata.csv";
    mysql_optionsv(mysql, MARIADB_OPT_VERIFY_LOCAL_INFILE_CALLBACK, my_verify_filename, (void *)filename);
    
  • MYSQL_OPT_NAMED_PIPE: For Windows operating systems only: Use named pipes for client/server communication.

    mysql_optionsv(mysql, MYSQL_OPT_NAMED_PIPE, NULL);
    
  • MYSQL_PROGRESS_CALLBACK: Specifies a callback function which will be able to visualize the progress of certain long running statements (i.e. LOAD DATA LOCAL INFILE or ALTER TABLE).

    static void report_progress(const MYSQL *mysql __attribute__((unused)),
            uint stage, uint max_stage,
            double progress __attribute__((unused)),
            const char *proc_info __attribute__((unused)),
            uint proc_info_length __attribute__((unused)))
    {
      ...
    }
    mysql_optionsv(mysql, MYSQL_PROGRESS_CALLBACK, (void *)report_progress);                  
    
  • MYSQL_OPT_PROTOCOL: Specify the type of client/server protocol. Possible values are: MYSQL_PROTOCOL_TCP, MYSQL_PROTOCOL_SOCKET, MYSQL_PROTOCOL_PIPE and MYSQL_PROTOCOL_MEMORY.

    enum mysql_protocol_type prot_type= MYSQL_PROTOCOL_SOCKET;
    mysql_optionsv(mysql, MYSQL_OPT_PROTOCOL, (void *)&prot_type);
    
  • MYSQL_OPT_RECONNECT: Enable or disable automatic reconnect.

    my_bool reconnect= 1; /* enable reconnect */
    mysql_optionsv(mysql, MYSQL_OPT_RECONNECT, (void *)&reconnect);
    
  • MYSQL_OPT_READ_TIMEOUT: Specifies the timeout in seconds for reading packets from server.

    unsigned int timeout= 5;
    mysql_optionsv(mysql, MYSQL_OPT_READ_TIMEOUT, (void *)&timeout);
    
  • MYSQL_OPT_WRITE_TIMEOUT: Specifies the timeout in seconds for sending packets to server.

    unsigned int timeout= 5;
    mysql_optionsv(mysql, MYSQL_OPT_WRITE_TIMEOUT, (void *)&timeout);
    
  • MYSQL_READ_DEFAULT_FILE: Read options from named option file instead of my.cnf

    mysql_optionsv(mysql, MYSQL_READ_DEFAULT_FILE, (void *)"./my_conf.cnf");
    
  • MYSQL_READ_DEFAULT_GROUP: Read options from the named group from my.cnf or the file specified with MYSQL_READ_DEFAULT_FILE.

    mysql_optionsv(mysql, MYSQL_READ_DEFAULT_GROUP, (void *)"my_section");
    
  • MYSQL_REPORT_DATA_TRUNCATION: Enable or disable reporting data truncation errors for prepared statement.

    mysql_optionsv(mysql, MYSQL_REPORT_DATA_TRUNCATION, NULL);        /* disable */
    mysql_optionsv(mysql, MYSQL_REPORT_DATA_TRUNCATION, (void *)"1"); /* enable */                 
    
  • MYSQL_SET_CHARSET_NAME: Specify the default character set for the connection.

    mysql_optionsv(mysql, MYSQL_SET_CHARSET_NAME, (void *)"utf8");
    
  • MYSQL_OPT_BIND: Specify the network interface from which to connect to MariaDB Server.

    mysql_optionsv(mysql, MYSQL_OPT_BIND, (void *)"192.168.8.3");
    
  • MYSQL_PLUGIN_DIR: Specify the location of client plugins.

    mysql_optionsv(mysql, MYSQL_PLUGIN_DIR, (void *)"/opt/mariadb/lib/plugins");
    
  • MYSQL_OPT_NONBLOCK: Specify stack size for non blocking operations. The argument for MYSQL_OPT_NONBLOCK is the size of the stack used to save the state of a non-blocking operation while it is waiting for I/O and the application is doing other processing. Normally, applications will not have to change this, and it can be passed as zero to use the default value.

    mysql_optionsv(mysql, MYSQL_OPT_NONBLOCK, 0);
    
  • MARIADB_OPT_CONNECTION_HANDLER: Specify the name of a connection handler plugin.

    mysql_optionsv(mysql, MARIADB_OPT_CONNECTION_HANDLER, (void *)"aurora");
    
  • MARIADB_OPT_USERDATA: Bundle user data to the current connection, e.g. for use in connection handler plugins. This option requires 4 parameters: connection, option, key and value.
    mysql_optionsv(mysql, MARIADB_OPT_USERDATA, (void *)"ssh_user", (void *)ssh_user);
    
  • MARIADB_OPT_CONNECTION_READ_ONLY: This option is used by connection handler plugins and indicates that the current connection will be used for read operations only.

    my_bool read_only= 1;
    mysql_optionsv(mysql, MARIADB_OPT_CONNECTION_READ_ONLY, (void *)&read_only);
    
  • MYSQL_OPT_CAN_HANDLE_EXPIRED_PASSWORDS: If this option is set, client indicates that he will be able to handle expired passwords by setting the CLIENT_CAN_HANDLE_EXPIRED_PASSWORDS capability flag. If password expired and CLIENT_CAN_HANDLE_EXPIRED_PASSWORDS is set, the server will not return an error when connecting, but put the connection in sandbox mode, where all commands will return error 1820 (ER_MUST_CHANGE_PASSWORD) unless a new password was set.. This option was added in MariaDB Connector/C 3.0.4

    mysql_optionsv(mysql, MYSQL_OPT_CAN_HANDLE_EXPIRED_PASSWORDS, 1);
    

TLS options

  • MYSQL_OPT_SSL_KEY: Specify the name of a TLS key for a secure connection. If the key is protected with a passphrase, the passphrase needs to be specified with MARIADB_OPT_PASSPHRASE option.

    mysql_optionsv(mysql, MYSQL_OPT_SSL_KEY, (void *)"certs/client-key.pem");
    
  • MYSQL_OPT_SSL_CERT: Specify the name of a TLS certificate for a secure connection.

    mysql_optionsv(mysql, MYSQL_OPT_SSL_CERT, (void *)"certs/client-cert.pem");
    
  • MYSQL_OPT_SSL_CA: Specify the name of a file which contains one or more trusted TLS CAs.

    mysql_optionsv(mysql, MYSQL_OPT_SSL_CA, (void *)"certs/ca-cert.pem");
    
  • MYSQL_OPT_SSL_CAPATH: Specify the path which contains trusted CAs.

    mysql_optionsv(mysql, MYSQL_OPT_SSL_CAPATH, (void *)"certs/ca-cert.pem");
    
  • MYSQL_OPT_SSL_CIPHER: Specify a list of cipher suites for TLS encryption.

    mysql_optionsv(mysql, MYSQL_OPT_SSL_CIPHER, (void *)"DHE-RSA-AES256-SHA");
    
  • MYSQL_OPT_SSL_CRL: Specify a file with certificate revocation list.

    mysql_optionsv(mysql, MYSQL_OPT_SSL_CRL, (void *)"certs/crl.pem");
    
  • MYSQL_OPT_SSL_CRLPATH: Specify a directory with contains files with certificate revocation lists.

    mysql_optionsv(mysql, MYSQL_OPT_SSL_CRLPATH, (void *)"certs/crls");
    
  • MARIADB_OPT_SSL_FP: Specify the SHA1 fingerprint of a server certificate for validation during TLS handshake.

    mysql_optionsv(mysql, MARIADB_OPT_SSL_FP, (void *)"3a079e1a14ad326953a5d280f996b93d772a5bea");
    
  • MARIADB_OPT_SSL_FP: Specify a file which contains one or more SHA1 fingerprints of server certificates for validation during TLS handshake.

    mysql_optionsv(mysql, MARIADB_OPT_SSL_FP_LIST, (void *)"certs/fingerprints.txt");
    
  • MARIADB_OPT_SSL_PASPHRASE: Specify a passphrase for a passphrase protected client key.

    mysql_optionsv(mysql, MARIADB_OPT_SSL_PASSPHRASE, (void *)"thisisashortpassphrase");
    
  • MYSQL_OPT_SSL_VERIFY_SERVER_CERT: Enable (or disable) the verification of the hostname against common name (CN) of the servers host certificate.

    my_bool verify= 1;
    mysql_optionsv(mysql, MYSQL_OPT_SSL_VERIFY_SERVER_CERT, (void *)&verify);
    
Connection attributes

Connection attributes are stored in the session_connect_attrs and session_account_connect_attrs Performance Schema tables. By default MariaDB Connector/C sends the following connection attributes to the server:

  • _client_name: always "libmariadb"
  • _client_version: version of MariaDB Connector/C
  • _os: operation system
  • _pid: process id
  • _platform: e.g. x86 or x64

If performance schema is disabled, connection attributes will not be stored on server.

  • MYSQL_OPT_CONNECT_ATTR_DELETE: Deletes a connection attribute for the given key.

    mysql_optionsv(mysql, MYSQL_OPT_CONNECT_ATTR_DELETE, (void *)"app_version");
    
  • MYSQL_OPT_CONNECT_ATTR_ADD: Adds an key/value pair to connection attributes.

    mysql_optionsv(mysql, MYSQL_OPT_CONNECT_ATTR_ADD, (void *)"app_version", (void *)"2.0.1");
    
  • MYSQL_OPT_CONNECT_ATTR_RESET: Clears the current list of connection attributes.

    mysql_optionsv(mysql, MYSQL_OPT_CONNECT_ATTR_RESET, 0);
    

See also

Comments

Comments loading...
Content reproduced on this site is the property of its respective owners, and this content is not reviewed in advance by MariaDB. The views, information and opinions expressed by this content do not necessarily represent those of MariaDB or any other party.