27.7.6.41 mysql_library_init()
int mysql_library_init(int argc, char **argv, char **groups)
Call this function to initialize the MySQL client library before you call any other MySQL function, whether your application is a regular client program or uses the embedded server. If the application uses the embedded server, this call starts the server and initializes any subsystems (mysys
, InnoDB
, and so forth) that the server uses.
To avoid memory leaks after the application is done using the library (for example, after closing the connection to the server), be sure to call mysql_library_end()
explicitly. This enables memory managment to be performed to clean up and free resources used by the library. See Section 27.7.6.40, “mysql_library_end()”.
The choice of whether the application operates as a regular client or uses the embedded server depends on whether you use the libmysqlclient
or libmysqld
library at link time to produce the final executable. For additional information, see Section 27.7.5, “C API Function Overview”.
In a nonmultithreaded environment, the call to mysql_library_init()
may be omitted, because mysql_init()
will invoke it automatically as necessary. However, mysql_library_init()
is not thread-safe in a multithreaded environment, and thus neither is mysql_init()
, which calls mysql_library_init()
. You must either call mysql_library_init()
prior to spawning any threads, or else use a mutex to protect the call, whether you invoke mysql_library_init()
or indirectly through mysql_init()
. Do this prior to any other client library call.
The argc
and argv
arguments are analogous to the arguments to main()
, and enable passing of options to the embedded server. For convenience, argc
may be 0
(zero) if there are no command-line arguments for the server. This is the usual case for applications intended for use only as regular (nonembedded) clients, and the call typically is written as mysql_library_init(0, NULL, NULL)
.
#include <mysql.h>
#include <stdlib.h>
int main(void) {
if (mysql_library_init(0, NULL, NULL)) {
fprintf(stderr, "could not initialize MySQL client library\n");
exit(1);
}
/* Use any MySQL API functions here */
mysql_library_end();
return EXIT_SUCCESS;
}
When arguments are to be passed (argc
is greater than 0
), the first element of argv
is ignored (it typically contains the program name). mysql_library_init()
makes a copy of the arguments so it is safe to destroy argv
or groups
after the call.
For embedded applications, if you want to connect to an external server without starting the embedded server, you have to specify a negative value for argc
.
The groups
argument is an array of strings that indicate the groups in option files from which to read options. See Section 4.2.2.2, “Using Option Files”. Make the final entry in the array NULL
. For convenience, if the groups
argument itself is NULL
, the [server]
and [embedded]
groups are used by default.
#include <mysql.h>
#include <stdlib.h>
static char *server_args[] = {
"this_program", /* this string is not used */
"--datadir=.",
"--key_buffer_size=32M"
};
static char *server_groups[] = {
"embedded",
"server",
"this_program_SERVER",
(char *)NULL
};
int main(void) {
if (mysql_library_init(sizeof(server_args) / sizeof(char *),
server_args, server_groups)) {
fprintf(stderr, "could not initialize MySQL client library\n");
exit(1);
}
/* Use any MySQL API functions here */
mysql_library_end();
return EXIT_SUCCESS;
}