MySQL Bugs: #62394: handle_options is no longer exported by libmysqlclient

Bug #62394	handle_options is no longer exported by libmysqlclient
Submitted:	8 Sep 2011 23:12	Modified:	28 Aug 2013 13:25
Reporter:	[ name withheld ]	Email Updates:
Status:	Closed	Impact on me:	None
Category:	MySQL Server: C API (client library)	Severity:	S3 (Non-critical)
Version:	5.5.15	OS:	Any
Assigned to:		CPU Architecture:	Any

Description:
The function handle_options() is not exported by libmysqlclient as of 5.5.  This appears to be because it is not called out as one of the target functions in the  SET(CLIENT_API_FUNCTIONS) macro in libmysql/CMakeLists.txt, and therefore mysys/my_getopt.c doesn't get linked into the library.

Now I'm aware that handle_options is not part of your published API, but it was documented in Paul Dubois' MySQL book, and I think that a fair number of people are relying on it.  So what I'm really looking for is an official ruling: is this function in or out?  If it's out, it's no skin off my nose personally, but I don't want to tell my users "tough luck" unless it's upstream telling them that.

While we're on the subject, the SET(CLIENT_API_FUNCTIONS) list seems to be a few bricks shy of a load in other respects.  The other symbols that I'd expect to find there include:

my_init
mysql_client_find_plugin
mysql_client_register_plugin
mysql_get_parameters
mysql_load_plugin
mysql_load_plugin_v
mysql_plugin_options

and probably also

client_errors
free_defaults
my_make_scrambled_password
my_print_help

(these last are again not part of the official API, but seem to be widely depended on, so I'd like to see them either officially recognized or officially killed)

And while we are on the subject, mysql_connector_odbc depends on these symbols:

default_charset_info
get_charset
get_charset_by_csname
net_realloc

which is probably something you ought to teach it not to do, but until you do, maybe you'd better export the symbols.

With the exception of handle_options and my_print_help, these seem to all be exported anyway by the built library, but I believe that's just an accident of them being in the same .o file as other symbols that are pulled in.  I'd suggest that the CMakeLists file ought to explicitly list everything you consider part of the API, just to be sure you don't have unexpected breakage after future code rearrangements.

How to repeat:
Examine exported symbol list of libmysqlclient.so.

Suggested fix:
Ideally, either export these officially, or state for the record that they are unsupported and people must not rely on them.

Have you thought about establishing an export list to enforce that the library only exports the symbols it's supposed to?  Because it sure clutters application namespace with a lot of stuff it shouldn't, and that's part of the reason why these functions have developed their own followings.  I'm using an experimental exports list in Fedora, which you're quite welcome to study.

Thank you for the bug report.

c:\build\5.5-2011-09-06\libmysql\Release>dumpbin /EXPORTS libmysql.dll  | findstr handle_options

c:\build\5.5-2011-09-06\libmysql\Release>cd c:\build\5.1-2011-09-06\libmysql\Release

c:\build\5.1-2011-09-06\libmysql\Release>dumpbin /EXPORTS libmysql.dll  | findstr handle_options
         10    9 00022F90 handle_options

c:\build\5.1-2011-09-06\libmysql\Release>

I think Paul (Dubois) should could publish caveats to his book and say that non-documented functions that do not have a well-known prefix mysql_ are not guaranteed to work. 
If they appear to work, they only work  with static library.  The mentioned functions have nothing to do with "client" or "connectivity" anyway. The purpose of client API was not providing framework for writing command line utilities or ini file parsers. This may have some useful functionality, but not something you would expect this from database connectivity libraries (that is, neither ODBC nor JDBC nor ADO.NET,Python, Ruby, not even Perl-DBI/DBD or your-favorite-language-database-library  would provide such functionality to parse command lines). 
Just my opinion :)

I think Paul (Dubois) should could publish caveats to his book and say that non-documented functions that do not have a well-known prefix mysql_ are not guaranteed to work. 
If they appear to work, they only work  with static library.  The mentioned functions have nothing to do with "client" or "connectivity" anyway. The purpose of client API was not providing framework for writing command line utilities or ini file parsers. This may have some useful functionality, but not something you would expect this from database connectivity libraries (that is, neither ODBC nor JDBC nor ADO.NET,Python, Ruby, not even Perl-DBI/DBD or your-favorite-language-database-library  would provide such functionality to parse command lines). 
Just my opinion :)

btw, this appears to work in 5.5.27 now

Posted by developer:
 
Problem with missing handle_options was fixed in mysql-5.5.21.

Following *documented* symbols were added to CLIENT_API_FUNCTIONS by the patch for bug#69204: my_init, mysql_client_find_plugin, mysql_client_register_plugin, mysql_load_plugin, mysql_load_plugin_v, mysql_options4, and mysql_plugin_options.

Noted in 5.5.21 changelog.