lib/setlocale_null.h

   1 /* Query the name of the current global locale.
   2    Copyright (C) 2019-2024 Free Software Foundation, Inc.
   3
   4    This file is free software: you can redistribute it and/or modify
   5    it under the terms of the GNU Lesser General Public License as
   6    published by the Free Software Foundation; either version 2.1 of the
   7    License, or (at your option) any later version.
   8
   9    This file 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 /* Written by Bruno Haible <bruno@clisp.org>, 2019.  */
  18
  19 #ifndef _SETLOCALE_NULL_H
  20 #define _SETLOCALE_NULL_H
  21
  22 #include <stddef.h>
  23
  24 #include "arg-nonnull.h"
  25
  26
  27 #ifdef __cplusplus
  28 extern "C" {
  29 #endif
  30
  31
  32 /* Recommended size of a buffer for a locale name for a single category.
  33    On glibc systems, you can have locale names that are relative file names;
  34    assume a maximum length 256.
  35    In native Windows, in 2018 the longest locale name was of length 58
  36    ("FYRO Macedonian_Former Yugoslav Republic of Macedonia.1251").  */
  37 #define SETLOCALE_NULL_MAX (256+1)
  38
  39 /* Recommended size of a buffer for a locale name with all categories.
  40    On glibc systems, you can have locale names that are relative file names;
  41    assume maximum length 256 for each.  There are 12 categories; so, the
  42    maximum total length is 148+12*256.
  43    In native Windows, there are 5 categories, and the maximum total length is
  44    55+5*58.  */
  45 #define SETLOCALE_NULL_ALL_MAX (148+12*256+1)
  46
  47 /* setlocale_null_r_unlocked (CATEGORY, BUF, BUFSIZE) is like
  48    setlocale (CATEGORY, NULL), except that
  49      - it returns the resulting locale category name or locale name in the
  50        user-supplied buffer BUF, which must be BUFSIZE bytes long.
  51    The recommended minimum buffer size is
  52      - SETLOCALE_NULL_MAX for CATEGORY != LC_ALL, and
  53      - SETLOCALE_NULL_ALL_MAX for CATEGORY == LC_ALL.
  54    The return value is an error code: 0 if the call is successful, EINVAL if
  55    CATEGORY is invalid, or ERANGE if BUFSIZE is smaller than the length needed
  56    size (including the trailing NUL byte).  In the latter case, a truncated
  57    result is returned in BUF, but still NUL-terminated if BUFSIZE > 0.
  58    This call is guaranteed to be multithread-safe only if
  59      - CATEGORY != LC_ALL and SETLOCALE_NULL_ONE_MTSAFE is true, or
  60      - CATEGORY == LC_ALL and SETLOCALE_NULL_ALL_MTSAFE is true,
  61    and the other threads must not make other setlocale invocations (since
  62    changing the global locale has side effects on all threads).  */
  63 extern int setlocale_null_r_unlocked (int category, char *buf, size_t bufsize)
  64   _GL_ARG_NONNULL ((2));
  65
  66 /* setlocale_null_unlocked (CATEGORY) is like setlocale (CATEGORY, NULL).
  67    The return value is NULL if CATEGORY is invalid.
  68    This call is guaranteed to be multithread-safe only if
  69      - CATEGORY != LC_ALL and SETLOCALE_NULL_ONE_MTSAFE is true, or
  70      - CATEGORY == LC_ALL and SETLOCALE_NULL_ALL_MTSAFE is true,
  71    and the other threads must not make other setlocale invocations (since
  72    changing the global locale has side effects on all threads).  */
  73 extern const char *setlocale_null_unlocked (int category);
  74
  75 /* setlocale_null_r (CATEGORY, BUF, BUFSIZE) is like setlocale (CATEGORY, NULL),
  76    except that
  77      - it is guaranteed to be multithread-safe,
  78      - it returns the resulting locale category name or locale name in the
  79        user-supplied buffer BUF, which must be BUFSIZE bytes long.
  80    The recommended minimum buffer size is
  81      - SETLOCALE_NULL_MAX for CATEGORY != LC_ALL, and
  82      - SETLOCALE_NULL_ALL_MAX for CATEGORY == LC_ALL.
  83    The return value is an error code: 0 if the call is successful, EINVAL if
  84    CATEGORY is invalid, or ERANGE if BUFSIZE is smaller than the length needed
  85    size (including the trailing NUL byte).  In the latter case, a truncated
  86    result is returned in BUF, but still NUL-terminated if BUFSIZE > 0.
  87    For this call to be multithread-safe, *all* calls to
  88    setlocale (CATEGORY, NULL) in all other threads must have been converted
  89    to use setlocale_null_r or setlocale_null as well, and the other threads
  90    must not make other setlocale invocations (since changing the global locale
  91    has side effects on all threads).  */
  92 extern int setlocale_null_r (int category, char *buf, size_t bufsize)
  93   _GL_ARG_NONNULL ((2));
  94
  95 /* setlocale_null (CATEGORY) is like setlocale (CATEGORY, NULL), except that
  96    it is guaranteed to be multithread-safe.
  97    The return value is NULL if CATEGORY is invalid.
  98    For this call to be multithread-safe, *all* calls to
  99    setlocale (CATEGORY, NULL) in all other threads must have been converted
 100    to use setlocale_null_r or setlocale_null as well, and the other threads
 101    must not make other setlocale invocations (since changing the global locale
 102    has side effects on all threads).  */
 103 extern const char *setlocale_null (int category);
 104
 105
 106 #ifdef __cplusplus
 107 }
 108 #endif
 109
 110 #endif /* _SETLOCALE_NULL_H */