1  .\" Copyright (c) 1990, 1991, 1993
  2  .\"	The Regents of the University of California.  All rights reserved.
  3  .\"
  4  .\" This code is derived from software contributed to Berkeley by
  5  .\" Chris Torek and the American National Standards Committee X3,
  6  .\" on Information Processing Systems.
  7  .\"
  8  .\" Redistribution and use in source and binary forms, with or without
  9  .\" modification, are permitted provided that the following conditions
 10  .\" are met:
 11  .\" 1. Redistributions of source code must retain the above copyright
 12  .\"    notice, this list of conditions and the following disclaimer.
 13  .\" 2. Redistributions in binary form must reproduce the above copyright
 14  .\"    notice, this list of conditions and the following disclaimer in the
 15  .\"    documentation and/or other materials provided with the distribution.
 16  .\" 4. Neither the name of the University nor the names of its contributors
 17  .\"    may be used to endorse or promote products derived from this software
 18  .\"    without specific prior written permission.
 19  .\"
 20  .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
 21  .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
 22  .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
 23  .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
 24  .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
 25  .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
 26  .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
 27  .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
 28  .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
 29  .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 30  .\" SUCH DAMAGE.
 31  .\"
 32  .\"     @(#)strxfrm.3	8.1 (Berkeley) 6/4/93
 33  .\" FreeBSD: src/lib/libc/string/strxfrm.3,v 1.16 2002/09/06 11:24:06 tjr Exp
 34  .\" $FreeBSD: src/lib/libc/string/wcsxfrm.3,v 1.3 2007/01/09 00:28:12 imp Exp $
 35  .\"
 36  .Dd October 4, 2002
 37  .Dt WCSXFRM 3
 38  .Os
 39  .Sh NAME
 40  .Nm wcsxfrm ,
 41  .Nm wcsxfrm_l
 42  .Nd transform a wide string under locale
 43  .Sh LIBRARY
 44  .Lb libc
 45  .Sh SYNOPSIS
 46  .In wchar.h
 47  .Ft size_t
 48  .Fo wcsxfrm
 49  .Fa "wchar_t *restrict ws1"
 50  .Fa "const wchar_t *restrict ws2"
 51  .Fa "size_t n"
 52  .Fc
 53  .In wchar.h
 54  .In xlocale.h
 55  .Ft size_t
 56  .Fo wcsxfrm_l
 57  .Fa "wchar_t *restrict ws1"
 58  .Fa "const wchar_t *restrict ws2"
 59  .Fa "size_t n"
 60  .Fa "locale_t loc"
 61  .Fc
 62  .Sh DESCRIPTION
 63  The
 64  .Fn wcsxfrm
 65  function transforms a null-terminated wide character string pointed to by
 66  .Fa ws2 ,
 67  according to the current locale's collation order,
 68  then copies the transformed string into
 69  .Fa ws1 .
 70  No more than
 71  .Fa n
 72  wide characters are copied into
 73  .Fa ws1 ,
 74  including the terminating null character.
 75  If
 76  .Fa n
 77  is set to 0
 78  (it helps to determine an actual size needed
 79  for transformation),
 80  .Fa ws1
 81  is permitted to be a
 82  .Dv NULL
 83  pointer.
 84  .Pp
 85  Comparing two strings using
 86  .Fn wcscmp
 87  after
 88  .Fn wcsxfrm
 89  is equivalent to comparing
 90  two original strings with
 91  .Fn wcscoll .
 92  .Pp
 93  Although the
 94  .Fn wcsxfrm
 95  function uses the current locale, the
 96  .Fn wcsxfrm_l
 97  function may be passed a locale directly. See
 98  .Xr xlocale 3
 99  for more information.
100  .Sh RETURN VALUES
101  Upon successful completion,
102  .Fn wcsxfrm
103  returns the length of the transformed string not including
104  the terminating null character.
105  If this value is
106  .Fa n
107  or more, the contents of
108  .Fa ws1
109  are indeterminate.
110  .Sh SEE ALSO
111  .Xr setlocale 3 ,
112  .Xr strxfrm 3 ,
113  .Xr wcscmp 3 ,
114  .Xr wcscoll 3 ,
115  .Xr xlocale 3
116  .Sh STANDARDS
117  The
118  .Fn wcsxfrm
119  function
120  conforms to
121  .St -isoC-99 .
122  .Sh BUGS
123  The current implementation of
124  .Fn wcsxfrm
125  only works in single-byte
126  .Dv LC_CTYPE
127  locales, and falls back to using
128  .Fn wcsncpy
129  in locales with extended character sets.
130  .Pp
131  Comparing two strings using
132  .Fn wcscmp
133  after
134  .Fn wcsxfrm
135  is
136  .Em not
137  always equivalent to comparison with
138  .Fn wcscoll ;
139  .Fn wcsxfrm
140  only stores information about primary collation weights into
141  .Fa ws1 ,
142  whereas
143  .Fn wcscoll
144  compares characters using both primary and secondary weights.