xref: /illumos-gate/usr/src/man/man3c/wcscasecmp.3c (revision 4a8d6d7c)
1.\"
2.\" This file and its contents are supplied under the terms of the
3.\" Common Development and Distribution License ("CDDL"), version 1.0.
4.\" You may only use this file in accordance with the terms of version
5.\" 1.0 of the CDDL.
6.\"
7.\" A full copy of the text of the CDDL should have accompanied this
8.\" source.  A copy of the CDDL is also available via the Internet at
9.\" http://www.illumos.org/license/CDDL.
10.\"
11.\"
12.\" Copyright 2014 Garrett D'Amore <garrett@damore.org>
13.\"
14.Dd "February 17, 2023"
15.Dt WCSCASECMP 3C
16.Os
17.Sh NAME
18.Nm wcscasecmp ,
19.Nm wcscasecmp_l ,
20.Nm wcsncasecmp ,
21.Nm wcsncasecmp_l
22.Nd case-insensitive wide-character string comparison
23.Sh SYNOPSIS
24.In wchar.h
25.
26.Ft int
27.Fo wcscasecmp
28.Fa "const wchar_t *ws1"
29.Fa "const wchar_t *ws2"
30.Fc
31.
32.Ft int
33.Fo wcscasecmp_l
34.Fa "const wchar_t *ws1"
35.Fa "const wchar_t *ws2"
36.Fa "locale_t loc"
37.Fc
38.
39.Ft int
40.Fo wcsncasecmp
41.Fa "const wchar_t *ws1"
42.Fa "const wchar_t *ws2"
43.Fa "size_t n"
44.Fc
45.
46.Ft int
47.Fo wcsncasecmp_l
48.Fa "const wchar_t *ws1"
49.Fa "const wchar_t *ws2"
50.Fa "size_t n"
51.Fa "locale_t loc"
52.Fc
53.Sh DESCRIPTION
54These functions perform case-insensitive comparison of wide-character
55strings
56.Fa ws1
57and
58.Fa ws2 .
59Pairs of wide-characters from each of
60.Fa ws1
61and
62.Fa ws2
63are compared consecutively, ignoring differences in case (if the "POSIX" locale
64upper case characters are treated as lower case).
65If the two values are different, the comparison stops and either a negative
66value is returned if the character from
67.Fa ws1
68is less than that from
69.Fa ws2 ,
70or a positive is returned if the character from
71.Fa ws1
72is greater than that from
73.Fa ws2 .
74The comparison also stops if both characters are null wide-characters,
75or, in the case of
76.Fn wcsncasecmp
77and
78.Fn wcsncasecmp_l ,
79after
80.Fa n
81comparisons have been made without finding a difference.
82In either of these two cases, 0 is returned.
83.Lp
84The
85.Fn wcscasecmp
86and
87.Fn wcsncasecmp
88functions use the
89.Dv LC_CTYPE
90category of the current locale to determine case.
91The
92.Fn wcscasecmp_l
93and
94.Fn wcsncasecmp_l
95functions use the
96.Dv LC_CTYPE
97category of the locale pointed to by
98.Fa loc
99to determine case.
100.Lp
101Passing
102.Dv LC_GLOBAL_LOCALE
103for
104.Fa loc
105results in undefined behavior.
106.Lp
107The
108.Fn wcscasecmp ,
109.Fn wcsncasecmp ,
110.Fn wcscasecmp_l ,
111and
112.Fn wcsncasecmp_l
113functions are the wide-character equivalents of the
114.Fn strcasecmp ,
115.Fn strncasecmp ,
116.Fn strcasecmp_l ,
117and
118.Fn strncasecmp_l
119functions, respectively.
120.Sh RETURN VALUES
121These functions return a negative value if, ignoring case,
122.Fa ws1
123is less than
124.Fa ws1 ,
125or a positive value  if
126.Fa ws1
127is greater than
128.Fa ws2 ,
129or 0 if the both
130.Fa ws1
131and
132.Fa ws2
133are the same.
134.Sh ERRORS
135None.
136.Sh INTERFACE STABILITY
137.Sy Standard .
138.Sh MT-LEVEL
139.Sy MT-Safe .
140.Sh SEE ALSO
141.Xr newlocale 3C ,
142.Xr setlocale 3C ,
143.Xr strcasecmp 3C ,
144.Xr strcasecmp_l 3C ,
145.Xr strncasecmp 3C ,
146.Xr strncasecmp_l 3C ,
147.Xr uselocale 3C ,
148.Xr wchar.h 3HEAD ,
149.Xr locale 7 ,
150.Xr standards 7
151.Sh STANDARDS
152The
153.Fn wcscasecmp ,
154.Fn wcsncasecmp ,
155.Fn wcscasecmp_l ,
156and
157.Fn wcsncasecmp_l
158functions were introduced in
159.St -p1003.1-2008 .
160