errmsg_readme.txt

Copyright (c) 2019, 2024, Oracle and/or its affiliates.

This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License, version 2.0,
as published by the Free Software Foundation.

This program is designed to work with certain software (including
but not limited to OpenSSL) that is licensed under separate terms,
as designated in a particular file or component or in included license
documentation.  The authors of MySQL hereby grant you an additional
permission to link the program and your derivative works with the
separately licensed software that they have either included with
the program or referenced in the documentation.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License, version 2.0, for more details.

You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301  USA

FREQUENTLY ASKED QUESTIONS (FAQ)
about error messages

1  What kinds of messages exist?

I  Messages that are built into certain components
   and that are not loaded by the server at runtime.
   They can not be localized; in the canonical version
   of the MySQL software, they are in English.

a) There are errors thrown by the operating system
   (cf. errno / strerror()).

b) The client library (libmysql / C-API) can throw
   certain errors on the client side. If for instance
   the client cannot connect to the server, we cannot
   receive an error message saying so from the server,
   so these messages are built into the client library.

c) "Global errors" are error codes / messages used by
   the mysys library. This library is used by the
   MySQL server as well as some of its clients.
   These messages are built into the mysys library.

II Messages that are loaded at runtime by the MySQL server.
   These messages can be localized; in the canonical version
   of the software, the default language is english. If a
   given message has not been translated to the configured
   language, the server will fall back to the english version
   of this message.
   The messages and their translations are configured in
   text files in the source tree. During the build process,
   files usable by the server (once for each language
   translations exist for in the input files) will be
   created.

d) Messages sent by the server to its clients.
   They are located in the file, messages_to_clients.txt
   in the same directory as these instructions.
   This is a different set of messages from that mentioned
   in b).
   See below for more information.

e) Messages sent by the server to the error log.
   They are located in the file, messages_to_error_log.txt
   in the same directory as these instructions.
   See below for more information.

These instructions are concerned with the messages
of type II.

These messages have a symbol ("ER_I_AM_A_TEAPOT"),
a number ("MY-000418"), and a message ("I am a teapot!").
The message may exist in various translations, and may
be changed (for clarity etc.) over time.

-> Message text may change, message signatures
   (the number and type of % subsitutions)
   currently must not.

-> Error numbers ("MY-000418") may not change,
   except for messages that exist only in trunk.

-> Error symbols may change, but this is strongly
   discouraged as user configurations (error log
   filtering etc.) may depend on these names.


2  What are ranges?

   In the simplest case, defining 5 error messages
   will give them the error numbers 1-5.
   This means error numbers will be assigned in the
   chronological order messages are added to the source.

   However, messages can be grouped in non-consecutive
   error number ranges. If each range is larger than the
   expect number of messages, there'll be some free "slots"
   (i.e. error numbers) at the end of each range in case
   we need them later. This lets us group messages/error
   number, which serves several purposes:

   -> We can keep all messages the server sends to clients
      in one range (error numbers less than 10,000), and
      all messages it writes to the error log in another
      range (error numbers 10,000 and greater).
      This way, the server can easily identify which
      group a message belongs to, and throw an error
      if the wrong type is sent to a given destination.

   -> We can keep all messages for a specific subsystem
      (e.g. X) together in its own range. Without ranges,
      messages for all subsystems would be numbered in
      the order they are added to the MySQL server's source,
      rather than by subsystem.

   -> Having different ranges for each version of the
      MySQL server lets us add messages to older versions
      of the server as required by bugfixing, and upmerge
      them safely:

      Suppose 5.6 has messages 3 messages, and 5.7 has
      the same 3 messages, but additionally 2 new ones
      for the features added in 5.7.

      Suppose also that we need to fix an issue in 5.6
      and above that requires a new message.

      - Without ranges, we'd start with the error numbers
        { 1, 2, 3 } in 5.6, and { 1, 2, 3, 4, 5 } in 5.7.
        Adding the new message to 5.6 would be simple;
        we'd append it with error number 4.

        5.7 however already has its own, different error
        number 4; appending the new message at the end
        of the 5.7 messages would give it different
        error numbers in 5.6 and 5.7, which would make
        the documentation confusing.

        Inserting the new message in 5.7's error list
        so it would have the same number as in 5.6
        would mean changing the error number of the
        message that previously was error number 4 in 5.7,
        and documentation would yet again be confusing.

      - With ranges, suppose we reserve the error numbers
        [1;10[ for 5.6, [10;20[ for 5.7, and so on.
        Now, we can safely append the new message as
        error number 4 to 5.6, and then upmerge it into
        5.7. The messages of 5.7 start at error number
        10, so upmerging message number 4 from 5.6 is safe,
        as number is not 4 used in 5.7; it's reserved for
        5.6 messages.



3  Where do I add server-to-client messages?
   (Messages used with my_error(), push_warning_printf())

   Messages that the server sends to its clients
   go into the file messages_to_clients.txt
   in the same directory as these instructions.
   Open that file, find the end of error number
   range for the server version you are adding
   the message to, and append your message.


4  Where do I add messages intended for the error log?
   (Messages used with LogErr() / LogEvent())

   Messages intended for the error log (as opposed to
   server-to-client messages) go into the file
   messages_to_error_log.txt in the same directory
   as these instructions. Open that file, find the
   end of error number range for the server version
   you are adding the message to, and append your message.


5  What do I do if a message needs to go to both the
   error log AND the client?

   If your message needs to be sent both to the client and to the
   error log, please add it twice, once in each of the above files.

   Several ranges may exist for each, pick the one corresponding
   to the lowest MySQL server version for which you are adding
   the message.

   Then, place two calls in the code (e.g. my_error() to send the
   one message to the client, and e.g. LogErr() to send the other
   message to the error log).

   If in doubt, use ER_ as the prefix for the error-log message,
   and ER_DA_ ("diagnostics area") for the one intended for the
   client, e.g.

   In messages_to_clients.txt:

     ER_DA_MY_MESSAGE
       eng "Hi!"

   In messages_to_error_log.txt:

     ER_MY_MESSAGE
       eng "Hi!"

   While both messages are allowed to have the same text, they
   do not need to do so, and you are encouraged to tailor each
   of the two strings to suit the intended audience and context.


6  I'm fixing existing code, how do I know where a message is sent?

   As a general guideline, if LogErr() or LogEvent() is used, the
   message is sent to the error log; if my_error() or
   push_warning_printf() is used, the message is sent to a client.

   -> executables other than the MySQL server may use their own
      wrappers around the relevant functions; see the documentation
      of that software for more information.

   -> within the MySQL server, the InnoDB storage engine uses
      its own wrapper code for the relevant functions; see the
      documentation for the InnoDB source code.

   -> within the MySQL server, the replication code (when used
      as a "client") may do transformations of error information;
      see the documentation of replication code for more information.


7  The test suite aborted with an assert() having to do with error numbers?

   This usually means that you tried to send a message intended for
   the error log to a client, or tried to write a message intended
   for the client to the error log. Find out whether two versions
   of this message already exist; if so, use the correct one;
   otherwise, add the missing message (see above for more information
   on how to do that).


8  Upmerging a new message into trunk failed, there already is a
   message in that place. What do I do?

   First, make sure you understand the general principle of
   per-version ranges described in answer 2.

   This is the exception from the rule described in answer 2,
   as trunk does not have its own range separate from that of
   the highest versioned tree.

   Therefore, error numbers in trunk, and only in trunk, may
   change during upmerge:

   For each range of messages in trunk, the order should become

     I    messages that existed in both in trunk and the lower branch
     II   messages you newly added to the lower branch
     III  messages that exist only in trunk

   This way, the message you add will have the same number in
   trunk as in the lower branch.

   However, it also means that the error numbers of new features
   in trunk, and ONLY in trunk, may change (as bug fixes are
   upmerged from the lower tree, and their messages inserted before
   the trunk-only ones, see also answer 2).

   It is more important to keep the error numbers that are in both
   trees (and therefore in released versions) stable between MySQL
   server versions than it is to keep the error numbers of new
   messages that exist only in trunk stable between commits to trunk.

   -> When error-numbers change, certain .result files may have to
      be re-recorded!

   This should ONLY happen when merging to trunk; once a branch is
   added for a new server version (e.g. "mysql-9.0"), a new range
   for 9.0 error log messages should be added, as well as a new
   range for 9.0 messages-to-clients.

   New messages to are most likely to be added for features (and
   therefore, in trunk), but if one were to be added in an 8.0
   bug fix, it would go at the end of the 8.0 range (the 8.0 range
   for error log or client messages, depending on the bug);
   this would not interfere with 9.0 messages as they'd be in a
   new, separate range. Interference / renumbering / merge problems
   should only ever occur between trunk and the most modern tree
   (mysql-x.y) below it!


9  What revelant files exist in the source tree?
   What relevant files are generated?
 
   The messages-to-clients are located in messages_to_clients.txt.
   These messages are sent by the MySQL server to its clients.

   The messages for the error log are located in
   messages_to_error_log.txt. These messages are
   written to the error log by the MySQL server.

   For each language in the files messages_to_clients.txt
   and messages_to_error_log.txt, a file errmsg.sys is created
   in a directory named for that language (e.g.
   share/english/errmsg.sys) at build time.

   At runtime, the server will read the messages from the errmsg.sys
   file containing the messages for the configured language.

   Additionally, the messages for the default language, English,
   are built into the server as a fallback so the MySQL server
   can still start (and report on the issue!) when it cannot find
   its errmsg.sys. To this end, mysqld_ername.h contains those
   messages as C code, while mysqld_error.h maps each symbol
   ("ER_MY_EXAMPLE_MESSAGE") to its error-number.


   The "global errors" defined by the mysys library are similarly
   built in from mysys/errors.cc (messages) and include/mysys_err.h
   (symbol to error number mapping), respectively.


   The client library (libmysql / C-API) also contains some error messages.
   These messages become part of theclient and let us provide diagnostics
   even when the server is not connected, or the server has no information
   about a client-side issue.

   -> These are not the same messages as the "messages intended
      for sending to clients"; this is further described in
      section 1-b above.

   -> As a simple guideline, client-library symbols begin with CR_,
      while server messages (both to the error log and for sending
      to clients) begin with ER_.

   For the client-library, mysqlclient_ername.h contains the union
   of messages, error numbers, and symbol names as C code. The file
   is generated from the symbol to error number mapping in errmsg.h
   and the  messages in errmsg.cc.
   The code in errmsg.cc serves as the client-library equivalent of
   messages_to_clients.txt.


10 What is the function of the OBSOLETE_ symbols?

   Symbols for obsolete messages are not defined in the build and
   therefore can't be used accidentally. The corresponding message
   however is still included in the errmsg.sys files (because older
   versions of the server may still use them), and the error number
   is still reserved (so the messages following below don't all have
   their error-number decreased by one when we make a message obsolete).