int mysql_library_init(int argc, char **argv, char
**groups)
Description
This function should be called to initialize the MySQL 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.
After your application is done using the MySQL library, call
mysql_library_end()
to clean up.
See Section 21.9.3.39, “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 21.9.2, “C API Function Overview”.
In a nonmulti-threaded 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 multi-threaded 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 via mysql_init()
.
This should be done 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 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 should be an array of
strings that indicate the groups in option files from which
options should be read. See Section 4.2.3.3, “Using Option Files”. The
final entry in the array should be 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 library\n"); exit(1); } /* Use any MySQL API functions here */ mysql_library_end(); return EXIT_SUCCESS; }
Return Values
Zero if successful. Nonzero if an error occurred.
User Comments
Add your own comment.