gl/setlocale_null.h

   1 /* Query the name of the current global locale.
   2    Copyright (C) 2019-2023 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 (CATEGORY, BUF, BUFSIZE) is like setlocale (CATEGORY, NULL),
  48    except that
  49      - it is guaranteed to be multithread-safe,
  50      - it returns the resulting locale category name or locale name in the
  51        user-supplied buffer BUF, which must be BUFSIZE bytes long.
  52    The recommended minimum buffer size is
  53      - SETLOCALE_NULL_MAX for CATEGORY != LC_ALL, and
  54      - SETLOCALE_NULL_ALL_MAX for CATEGORY == LC_ALL.
  55    The return value is an error code: 0 if the call is successful, EINVAL if
  56    CATEGORY is invalid, or ERANGE if BUFSIZE is smaller than the length needed
  57    size (including the trailing NUL byte).  In the latter case, a truncated
  58    result is returned in BUF, but still NUL-terminated if BUFSIZE > 0.
  59    For this call to be multithread-safe, *all* calls to
  60    setlocale (CATEGORY, NULL) in all other threads must have been converted
  61    to use setlocale_null_r or setlocale_null as well, and the other threads
  62    must not make other setlocale invocations (since changing the global locale
  63    has side effects on all threads).  */
  64 extern int setlocale_null_r (int category, char *buf, size_t bufsize)
  65   _GL_ARG_NONNULL ((2));
  66
  67 /* setlocale_null (CATEGORY) is like setlocale (CATEGORY, NULL), except that
  68    it is guaranteed to be multithread-safe.
  69    The return value is NULL if CATEGORY is invalid.
  70    For this call to be multithread-safe, *all* calls to
  71    setlocale (CATEGORY, NULL) in all other threads must have been converted
  72    to use setlocale_null_r or setlocale_null as well, and the other threads
  73    must not make other setlocale invocations (since changing the global locale
  74    has side effects on all threads).  */
  75 extern const char *setlocale_null (int category);
  76
  77
  78 #ifdef __cplusplus
  79 }
  80 #endif
  81
  82 #endif /* _SETLOCALE_NULL_H */