WCSCOLL(3C) Standard C Library Functions WCSCOLL(3C)
NAME
wcscoll, wcscoll_l, wscoll - wide character string comparison using
collating information
SYNOPSIS
#include <wchar.h>
int wcscoll(
const wchar_t *ws1,
const wchar_t *ws2);
int wcscoll_l(
const wchar_t *ws1,
const wchar_t *ws2,
locale_t loc);
int wscoll(
const wchar_t *ws1,
const wchar_t *ws2);
DESCRIPTION
The
wcscoll(),
wcscoll_l(), and
wscoll() functions compare the wide
character string pointed to by
ws1 to the wide character string
pointed to by
ws2, both interpreted as appropriate to the
LC_COLLATE locale category.
These functions do not change the setting of
errno if successful.
An application wanting to check for error situations should set
errno to 0 before calling these functions. If
errno is non-zero on return,
an error has occurred.
The function
wcsoll_l() behaves identically to
wcsoll(), except
instead of operating in the current locale, it operates in the locale
specified by
loc.
RETURN VALUES
Upon successful completion, these functions return an integer greater
than, equal to, or less than 0, depending upon whether the wide
character string pointed to by
ws1 is greater than, equal to, or less
than the wide character string pointed to by
ws2, when both are
interpreted as appropriate to the current locale, or the locale
specified by
loc. On error, they set
errno, but no return value is
reserved to indicate an error.
ERRORS
The
wcscoll(),
wcscoll_l() and
wscoll() functions may fail if:
EINVAL The
ws1 or
ws2 arguments contain wide character codes
outside the domain of the collating sequence.
USAGE
The
wcsxfrm(3C) and
wcscmp(3C) functions should be used for sorting
large lists, or when performing many comparisons on the same strings.
ATTRIBUTES
See
attributes(7) for descriptions of the following attributes:
+--------------------+-----------------+
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
+--------------------+-----------------+
|CSI | Enabled |
+--------------------+-----------------+
|Interface Stability | See below. |
+--------------------+-----------------+
|MT-Level | MT-Safe |
+--------------------+-----------------+
The
wcscoll() and
wcscoll_l() functions are Standard. The
wscoll() function is Committed.
SEE ALSO
newlocale(3C),
setlocale(3C),
uselocale(3C),
wcscmp(3C),
wcsxfrm(3C),
attributes(7),
standards(7) November 8, 2020 WCSCOLL(3C)
