1 WCSCOLL(3C)              Standard C Library Functions              WCSCOLL(3C)
   2 
   3 
   4 
   5 NAME
   6        wcscoll, wcscoll_l, wscoll - wide character string comparison using
   7        collating information
   8 
   9 SYNOPSIS
  10        #include <wchar.h>
  11 
  12        int wcscoll(const wchar_t *ws1, const wchar_t *ws2);
  13 
  14        int wcscoll_l(const wchar_t *ws1, const wchar_t *ws2, locale_t loc);
  15 
  16        int wscoll(const wchar_t *ws1, const wchar_t *ws2);
  17 
  18 DESCRIPTION
  19        The wcscoll(), wcscoll_l(), and wscoll() functions compare the wide
  20        character string pointed to by ws1 to the wide character string pointed
  21        to by ws2, both interpreted as appropriate to the LC_COLLATE locale
  22        category.
  23 
  24        These  functions do not change the setting of errno if successful.
  25 
  26        An application wanting to check for error situations should set errno
  27        to 0 before calling these functions.  If errno is non-zero on return,
  28        an error has occurred.
  29 
  30        The function wcsoll_l() behaves identically to wcsoll(), except instead
  31        of operating in the current locale, it operates in the locale specified
  32        by loc.
  33 
  34 RETURN VALUES
  35        Upon successful completion, these functions return an integer greater
  36        than, equal to, or less than 0, depending upon whether the wide
  37        character string pointed to by ws1 is greater than, equal to, or less
  38        than the wide character string pointed to by ws2, when both are
  39        interpreted as appropriate to the current locale, or the locale
  40        specified by loc. On error, they set errno, but no return value is
  41        reserved to indicate an error.
  42 
  43 ERRORS
  44        The wcscoll(), wcscoll_l() and wscoll() functions may fail if:
  45 
  46        EINVAL
  47                  The ws1 or ws2 arguments contain wide character codes outside
  48                  the domain of the collating sequence.
  49 
  50 USAGE
  51        The wcsxfrm(3C) and wcscmp(3C) functions should be used for sorting
  52        large lists, or when performing many comparisons on the same strings.
  53 
  54 ATTRIBUTES
  55        See attributes(5) for descriptions of the following attributes:
  56 
  57        +--------------------+-----------------+
  58        |  ATTRIBUTE TYPE    | ATTRIBUTE VALUE |
  59        +--------------------+-----------------+
  60        |CSI                 | Enabled         |
  61        +--------------------+-----------------+
  62        |Interface Stability | See below.      |
  63        +--------------------+-----------------+
  64        |MT-Level            | MT-Safe         |
  65        +--------------------+-----------------+
  66 
  67        The wcscoll() and wcscoll_l() functions are Standard.  The wscoll()
  68        function is Committed.
  69 
  70 SEE ALSO
  71        newlocale(3C), setlocale(3C), uselocale(3C), wcscmp(3C), wcsxfrm(3C),
  72        attributes(5), standards(5)
  73 
  74 
  75 
  76                                 August 20, 2019                    WCSCOLL(3C)