MySQL 8.0 C API Developer Guide
This section provides guidelines for compiling C programs that use the MySQL C API.
The examples here use gcc as the compiler. A different compiler might be appropriate on some systems (for example, clang on macOS or FreeBSD, or Sun Studio on Solaris). Adjust the examples as necessary.
You may need to specify an -I
option when you
compile client programs that use MySQL header files, so that
the compiler can find them. For example, if the header files
are installed in /usr/local/mysql/include
,
use this option in the compile command:
-I/usr/local/mysql/include
You can link your code with either the dynamic or static MySQL
C client library. The dynamic library base name is
libmysqlclient
and the suffix differs by
platform (for example, .so
for Linux,
.dylib
for macOS). The static library is
named libmysqlclient.a
on all platforms.
MySQL clients must be linked using the
-lmysqlclient
option in the link command. You
may also need to specify a -L
option to tell
the linker where to find the library. For example, if the
library is installed in
/usr/local/mysql/lib
, use these options
in the link command:
-L/usr/local/mysql/lib -lmysqlclient
The path names may differ on your system. Adjust the
-I
and -L
options as
necessary.
To make it simpler to compile MySQL programs on Unix, use the mysql_config script. See mysql_config — Display Options for Compiling Clients.
mysql_config displays the options needed for compiling or linking:
mysql_config --cflags mysql_config --libs
You can invoke those commands at the command line to get the proper options and add them manually to compilation or link commands. Alternatively, include the output from mysql_config directly within command lines using backticks:
gcc -c `mysql_config --cflags` progname.c gcc -o progname progname.o `mysql_config --libs`
On Unix, linking uses dynamic libraries by default. To link to
the static client library instead, add its path name to the
link command. For example, if the library is located in
/usr/local/mysql/lib
, link like this:
gcc -o progname progname.o /usr/local/mysql/lib/libmysqlclient.a
Or use mysql_config to provide the path to the library:
gcc -o progname progname.o `mysql_config --variable=pkglibdir`/libmysqlclient.a
mysql_config does not currently provide a
way to list all libraries needed for static linking, so it
might be necessary to name additional libraries on the link
command (for example, -lnsl -lsocket
on
Solaris). To get an idea which libraries to add, use
mysql_config --libs and ldd
libmysqlclient.so (or otool -L
libmysqlclient.dylib on macOS).
pkg-config can be used as an alternative to mysql_config for obtaining information such as compiler flags or link libraries required to compile MySQL applications. For example, the following pairs of commands are equivalent:
mysql_config --cflags pkg-config --cflags mysqlclient mysql_config --libs pkg-config --libs mysqlclient
To produce flags for static linking, use this command:
pkg-config --static --libs mysqlclient
For more information, see Section 4.2, “Building C API Client Programs Using pkg-config”.
To specify header and library file locations, use the facilities provided by your development environment.
To build C API clients on Windows, you must link in the C client library, as well as the Windows ws2_32 sockets library and Secur32 security library.
You can link your code with either the dynamic or static MySQL C client library:
The dynamic library is named
libmysql.dll
. In addition, the
libmysql.lib
static import library is
needed for using the dynamic library.
The static library is named
mysqlclient.lib
. To link with the
static C client library, the client application must be
compiled with the same version of Visual Studio used to
compile the C client library (which is Visual Studio 2015
for the static C client library built by Oracle).
When using the Oracle-built MySQL C client library, follow these rules when it comes to linking the C runtime for your client application:
For the MySQL C client library from a Community distribution of MySQL:
Always link dynamically to the C runtime (use the
/MD
compiler option), whether you
are linking to the static or dynamic C client library.
Also, target hosts running the client application must
have the
Visual
C++ Redistributable for Visual Studio 2015
installed.
For the MySQL C client library from a Commercial distribution of MySQL:
If linking to the static C client library, link
statically to the C runtime (use the
/MT
compiler option).
If linking to the dynamic C client library, link
either statically or dynamically to the C runtime (use
either /MT
or
/MD
compiler option).
In general, when linking to a static MySQL C client library,
the client library and the client application must use the
same compiler options when it comes to linking the C
runtime—that is, if your C client library is compiled
with the /MT
option, your client
application should also be compiled with the
/MT
option, and so on (see
the
MSDN page describing the C library linking options for
more details). Follow this rule when you build your own static
MySQL C client library from a source distribution of MySQL and
link your client application to it.
Debug Mode: Because of the
just-mentioned linking rule, you cannot build your
application in debug mode (with the
/MTd
or /MDd
compiler option) and link it to a static C client library
built by Oracle, which is not built
with the debug options. Instead, you must build the static
client library from source with the debug options.
The MySQL client library includes SSL support built in. It is
unnecessary to specify either -lssl
or
-lcrypto
at link time. Doing so may in fact
result in problems at runtime.
If the linker cannot find the MySQL client library, you might
get undefined-reference errors for symbols that start with
mysql_
, such as those shown here:
/tmp/ccFKsdPa.o: In function `main': /tmp/ccFKsdPa.o(.text+0xb): undefined reference to `mysql_init' /tmp/ccFKsdPa.o(.text+0x31): undefined reference to `mysql_real_connect' /tmp/ccFKsdPa.o(.text+0x69): undefined reference to `mysql_error' /tmp/ccFKsdPa.o(.text+0x9a): undefined reference to `mysql_close'
You should be able to solve this problem by adding
-L
at the end of your link command, where
dir_path
-lmysqlclientdir_path
represents the path name
of the directory where the client library is located. To
determine the correct directory, try this command:
mysql_config --libs
The output from mysql_config might indicate other libraries that should be specified on the link command as well. You can include mysql_config output directly in your compile or link command using backticks. For example:
gcc -o progname progname.o `mysql_config --libs`
If an error occurs at link time that the
floor
symbol is undefined, link to the math
library by adding -lm
to the end of the
compile/link line. Similarly, if you get undefined-reference
errors for other functions that should exist on your system,
such as connect()
, check the manual page
for the function in question to determine which libraries you
should add to the link command.
If you get undefined-reference errors such as the following for functions that do not exist on your system, it usually means that your MySQL client library was compiled on a system that is not 100% compatible with yours:
mf_format.o(.text+0x201): undefined reference to `__lxstat'
In this case, you should download a source distribution for the latest version of MySQL and compile the MySQL client library yourself. See Installing MySQL from Source.