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)