usr/src/man/man3c/wcscasecmp.3c

   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 "April 9, 2016"
  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
  54 These functions perform case-insensitive comparison of wide-character
  55 strings
  56 .Fa ws1
  57 and
  58 .Fa ws2 .
  59 Pairs of wide-characters from each of
  60 .Fa ws1
  61 and
  62 .Fa ws2
  63 are compared consecutively, ignoring differences in case (if the "POSIX" locale
  64 upper case characters are treated as lower case).
  65 If the two values are different, the comparison stops and either a negative
  66 value is returned if the character from
  67 .Fa ws1
  68 is less than that from
  69 .Fa ws2 ,
  70 or a positive is returned if the character from
  71 .Fa ws1
  72 is greater than that from
  73 .Fa ws2 .
  74 The comparison also stops if both characters are null wide-characters,
  75 or, in the case of
  76 .Fn wcsncasecmp
  77 and
  78 .Fn wcsncasecmp_l ,
  79 after
  80 .Fa n
  81 comparisons have been made without finding a difference.
  82 In either of these two cases, 0 is returned.
  83 .Lp
  84 The
  85 .Fn wcscasecmp
  86 and
  87 .Fn wcsncasecmp
  88 functions use the
  89 .Dv LC_CTYPE
  90 category of the current locale to determine case.
  91 The
  92 .Fn wcscasecmp_l
  93 and
  94 .Fn wcsncasecmp_l
  95 functions use the
  96 .Dv LC_CTYPE
  97 category of the locale pointed to by
  98 .Fa loc
  99 to determine case.
 100 .Lp
 101 Passing
 102 .Dv LC_GLOBAL_LOCALE
 103 for
 104 .Fa loc
 105 results in undefined behavior.
 106 .Lp
 107 The
 108 .Fn wcscasecmp ,
 109 .Fn wcsncasecmp ,
 110 .Fn wcscasecmp_l ,
 111 and
 112 .Fn wcsncasecmp_l
 113 functions are the wide-character equivalents of the
 114 .Fn strcasecmp ,
 115 .Fn strncasecmp ,
 116 .Fn strcasemp_l ,
 117 and
 118 .Fn strncasecmp_l
 119 functions, respectively.
 120 .Sh RETURN VALUES
 121 These functions return a negative value if, ignoring case,
 122 .Fa ws1
 123 is less than
 124 .Fa ws1 ,
 125 or a positive value  if
 126 .Fa ws1
 127 is greater than
 128 .Fa ws2 ,
 129 or 0 if the both
 130 .Fa ws1
 131 and
 132 .Fa ws2
 133 are the same.
 134 .Sh ERRORS
 135 None.
 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 5 ,
 150 .Xr standards 5
 151 .Sh STANDARDS
 152 The
 153 .Fn wcscasecmp ,
 154 .Fn wcsncasecmp ,
 155 .Fn wcscasecmp_l ,
 156 and
 157 .Fn wcsncasecmp_l
 158 functions were introduced in
 159 .St -p1003.1-2008 .