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 "Nov 4, 2014"
  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
  64 .\"POSIX\." locale upper case characters are treated as lower case).  If
  65 the two values are different, the comparision stops and either
  66 a negative 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.  In either of
  82 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.  The
  91 .Fn wcscasecmp_l
  92 and
  93 .Fn wcsncasecmp_l
  94 functions use the
  95 .Dv LC_CTYPE
  96 category of the locale pointed to by
  97 .Fa loc
  98 to determine case.
  99 .Lp
 100 Passing
 101 .Dv LC_GLOBAL_LOCALE
 102 for
 103 .Fa loc
 104 results in undefined behavior.
 105 .Lp
 106 The
 107 .Fn wcscasecmp ,
 108 .Fn wcsncasecmp ,
 109 .Fn wcscasecmp_l ,
 110 and
 111 .Fn wcsncasecmp_l
 112 functions are the wide-character equivalents of the
 113 .Fn strcasecmp ,
 114 .Fn strncasecmp ,
 115 .Fn strcasemp_l ,
 116 and
 117 .Fn strncasecmp_l
 118 functions, respectively.
 119 .Sh RETURN VALUES
 120 These functions return a negative value if, ignoring case,
 121 .Fa ws1
 122 is less than
 123 .Fa ws1 ,
 124 or a positive value  if
 125 .Fa ws1
 126 is greater than
 127 .Fa ws2 ,
 128 or 0 if the both
 129 .Fa ws1
 130 and
 131 .Fa ws2
 132 are the same.
 133 .Sh ERRORS
 134 None.
 135 .Sh INTERFACE STABILITY
 136 .Sy Standard .
 137 .Sh MT-LEVEL
 138 .Sy MT-Safe .
 139 .Sh SEE ALSO
 140 .Xr newlocale 3C ,
 141 .Xr setlocale 3C ,
 142 .Xr strcasecmp 3C ,
 143 .Xr strcasecmp_l 3C ,
 144 .Xr strncasecmp 3C ,
 145 .Xr strncasecmp_l 3C ,
 146 .Xr uselocale 3C ,
 147 .Xr wchar.h 3HEAD ,
 148 .Xr locale 5 ,
 149 .Xr standards 5
 150 .Sh STANDARDS
 151 The
 152 .Fn wcscasecmp ,
 153 .Fn wcsncasecmp ,
 154 .Fn wcscasecmp_l ,
 155 and
 156 .Fn wcsncasecmp_l
 157 functions were introduced in
 158 .St -p1003.1-2008 .