lib/localename.h

   1 /* Determine name of the currently selected locale.
   2    Copyright (C) 2007, 2009-2024 Free Software Foundation, Inc.
   3
   4    This program is free software: you can redistribute it and/or modify
   5    it under the terms of the GNU Lesser General Public License as published by
   6    the Free Software Foundation; either version 2.1 of the License, or
   7    (at your option) any later version.
   8
   9    This program is distributed in the hope that it will be useful,
  10    but WITHOUT ANY WARRANTY; without even the implied warranty of
  11    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  12    GNU Lesser General Public License for more details.
  13
  14    You should have received a copy of the GNU Lesser General Public License
  15    along with this program.  If not, see <https://www.gnu.org/licenses/>.  */
  16
  17 #ifndef _GL_LOCALENAME_H
  18 #define _GL_LOCALENAME_H
  19
  20 /* This file uses _GL_ATTRIBUTE_CONST, HAVE_CFPREFERENCESCOPYAPPVALUE.  */
  21 #if !_GL_CONFIG_H_INCLUDED
  22  #error "Please include config.h first."
  23 #endif
  24
  25 #ifdef __cplusplus
  26 extern "C" {
  27 #endif
  28
  29
  30 /* Determine the current locale's name.
  31    It considers both the POSIX notion of locale name (see functions
  32    gl_locale_name_thread and gl_locale_name_posix) and the system notion
  33    of locale name (see function gl_locale_name_default).
  34    CATEGORY is a locale category abbreviation, as defined in <locale.h>,
  35    but not LC_ALL. E.g. LC_MESSAGES.
  36    CATEGORYNAME is the name of CATEGORY as a string, e.g. "LC_MESSAGES".
  37    Return the locale category's name, canonicalized into XPG syntax
  38      language[_territory][.codeset][@modifier]
  39    The codeset part in the result is not reliable; the locale_charset()
  40    should be used for codeset information instead.
  41    The result must not be freed; it is statically allocated.  */
  42 extern const char * gl_locale_name (int category, const char *categoryname);
  43
  44 /* Determine the current per-thread locale's name, as specified by uselocale()
  45    calls.
  46    CATEGORY is a locale category abbreviation, as defined in <locale.h>,
  47    but not LC_ALL. E.g. LC_MESSAGES.
  48    CATEGORYNAME is the name of CATEGORY as a string, e.g. "LC_MESSAGES".
  49    Return the locale category's name, canonicalized into XPG syntax
  50      language[_territory][.codeset][@modifier]
  51    or NULL if no locale has been specified for the current thread.
  52    The codeset part in the result is not reliable; the locale_charset()
  53    should be used for codeset information instead.
  54    The result must not be freed; it is statically allocated.  */
  55 extern const char * gl_locale_name_thread (int category, const char *categoryname);
  56
  57 /* Determine the thread-independent current locale's name, as specified by
  58    setlocale() calls or by environment variables.
  59    CATEGORY is a locale category abbreviation, as defined in <locale.h>,
  60    but not LC_ALL. E.g. LC_MESSAGES.
  61    CATEGORYNAME is the name of CATEGORY as a string, e.g. "LC_MESSAGES".
  62    Return the locale category's name, canonicalized into XPG syntax
  63      language[_territory][.codeset][@modifier]
  64    or NULL if no locale has been specified to setlocale() or by environment
  65    variables.
  66    The codeset part in the result is not reliable; the locale_charset()
  67    should be used for codeset information instead.
  68    The result must not be freed; it is statically allocated.  */
  69 extern const char * gl_locale_name_posix (int category, const char *categoryname);
  70
  71 /* Determine the default locale's name, as specified by environment
  72    variables.
  73    Return the locale category's name, or NULL if no locale has been specified
  74    by environment variables.
  75    The result must not be freed; it is statically allocated.  */
  76 extern const char * gl_locale_name_environ (int category, const char *categoryname);
  77
  78 /* Determine the default locale's name.  This is the current locale's name,
  79    if not specified by uselocale() calls, by setlocale() calls, or by
  80    environment variables.  This locale name is usually determined by systems
  81    settings that the user can manipulate through a GUI.
  82
  83    Quoting POSIX:2001:
  84      "All implementations shall define a locale as the default locale,
  85       to be invoked when no environment variables are set, or set to the
  86       empty string.  This default locale can be the C locale or any other
  87       implementation-defined locale.  Some implementations may provide
  88       facilities for local installation administrators to set the default
  89       locale, customizing it for each location.  IEEE Std 1003.1-2001 does
  90       not require such a facility."
  91
  92    The result must not be freed; it is statically allocated.  */
  93 extern const char * gl_locale_name_default (void)
  94 #if !(HAVE_CFPREFERENCESCOPYAPPVALUE || defined _WIN32 || defined __CYGWIN__)
  95   _GL_ATTRIBUTE_CONST
  96 #endif
  97   ;
  98
  99
 100 /* These functions with the '_unsafe' suffix are like the functions without
 101    this suffix, above, except that the result is not statically allocated, but
 102    instead only valid in the current thread, until the next uselocale(),
 103    setlocale(), newlocale(), or freelocale() call.  */
 104 extern const char * gl_locale_name_unsafe (int category,
 105                                            const char *categoryname);
 106 extern const char * gl_locale_name_thread_unsafe (int category,
 107                                                   const char *categoryname);
 108 extern const char * gl_locale_name_posix_unsafe (int category,
 109                                                  const char *categoryname);
 110
 111
 112 #ifdef __cplusplus
 113 }
 114 #endif
 115
 116 #endif /* _GL_LOCALENAME_H */