1mysql_real_connect(3) MariaDB Connector/C mysql_real_connect(3)
2 Name
6 mysql_real_connect - establishes a connection to a MariaDB database
7 server
8 Synopsis
10 MYSQL * mysql_real_connect(MYSQL *mysql,
11 const char *host,
12 const char *user,
13 const char *passwd,
14 const char *db,
15 unsigned int port,
16 const char *unix_socket,
17 unsigned long flags);
18 Description
20 Establishes a connection to a database server.
21 Parameter
23 • mysql - a mysql handle, which was previously allocated by
24 mysql_init(3)
25 • host - can be either a host name or an IP address. Passing the NULL
27 value or the string “localhost” to this parameter, the local host is
28 assumed. When possible, pipes will be used instead of the TCP/IP
29 protocol. Since version 3.3.0 it is also possible to provide a comma
30 separated list of hosts for simple fail over in case of one or more
31 hosts are not available.
32 • user - the user name.
34 • passwd - If provided or NULL, the server will attempt to authenticate
36 the user against those user records which have no password only.
37 This allows one username to be used with different permissions (de‐
38 pending on if a password as provided or not).
39 • db - if provided will specify the default database to be used when
41 performing queries.
42 • port - specifies the port number to attempt to connect to the server.
44 • unix_socket - specifies the socket or named pipe that should be used.
46 • flags - the flags allows various connection options to be set
48 Flag Description
49 ──────────────────────────────────────────────────────────────────────────
50 CLIENT_FOUND_ROWS Return the number of matched rows
51 instead of number of changed rows.
52 CLIENT_NO_SCHEMA Forbids the use of database.table‐
53 name.column syntax and forces the
54 SQL parser to generate an error.
55 CLIENT_COMPRESS Use compression protocol
56 CLIENT_IGNORE_SPACE Allows spaces after function names.
57 All function names will become re‐
58 served words.
59 CLIENT_LOCAL_FILES Allows LOAD DATA LOCAL statements
60 CLIENT_MULTI_STATEMENTS Allows the client to send multiple
61 statements in one command. State‐
62 ments will be divided by a semi‐
63 colon.
64 CLIENT_MULTI_RESULTS Indicates that the client is able
68 to handle multiple result sets from
69 stored procedures or multi state‐
70 ments. This option will be auto‐
71 matically set if CLIENT_MUL‐
72 TI_STATEMENTS is set.
73 CLIENT_REMEMBER_OPTIONS Rembers options passed to mysql_op‐
74 tionsv(3) if a connect attempt
75 failed. If MYSQL_OPTIONS_RECONNECT
76 option was set to true, options
77 will be saved and used for recon‐
78 nection.
79 Return value
81 returns a connection handle (same as passed for 1st parameter) or NULL
82 on error. On error, please check mysql_errno(3) and mysql_error(3)
83 functions for more information.
84 Notes
86 • The password doesn’t need to be encrypted before executing mysql_re‐
87 al_connect(). This will be handled in the client server protocol.
88 • The connection handle can’t be reused for establishing a new connec‐
90 tion. It must be closed and reinitialized before.
91 • mysql_real_connect() must complete successfully before you can exe‐
93 cute any other API functions beside mysql_optionsv(3).
94 • host parameter may contain multiple host/port combinations (supported
96 since version 3.3.0). The following syntax is required:
97 • hostname and port must be seperated by a colon (:)
99 • IPv6 addresses must be enclosed within square brackets
101 • hostname:port pairs must be be seperated by a comma (,)
103 • if only one host:port was specified, the host string needs to end
105 with a comma.
106 • if no port was specified, the default port will be used.
108 Examples for failover host string:
110 host=[::1]:3306,192.168.0.1:3306,test.example.com
112 host=127.0.0.1:3306,
114 See also
116 • mysql_init(3)
117 • mysql_close(3)
119 • mariadb_reconnect(3)
121 • mysql_error(3)
123 • mysql_errno(3)
125Version 3.3.1 mysql_real_connect(3)