string/FreeBSD/wcsxfrm.3.patch

   1 --- wcsxfrm.3.bsdnew    2009-11-18 18:24:41.000000000 -0800
   2 +++ wcsxfrm.3   2009-11-18 18:24:41.000000000 -0800
   3 @@ -37,34 +37,47 @@
   4  .Dt WCSXFRM 3
   5  .Os
   6  .Sh NAME
   7 -.Nm wcsxfrm
   8 +.Nm wcsxfrm ,
   9 +.Nm wcsxfrm_l
  10  .Nd transform a wide string under locale
  11  .Sh LIBRARY
  12  .Lb libc
  13  .Sh SYNOPSIS
  14  .In wchar.h
  15  .Ft size_t
  16 -.Fn wcsxfrm "wchar_t * restrict dst" "const wchar_t * restrict src" "size_t n"
  17 +.Fo wcsxfrm
  18 +.Fa "wchar_t *restrict ws1"
  19 +.Fa "const wchar_t *restrict ws2"
  20 +.Fa "size_t n"
  21 +.Fc
  22 +.In wchar.h
  23 +.In xlocale.h
  24 +.Ft size_t
  25 +.Fo wcsxfrm_l
  26 +.Fa "wchar_t *restrict ws1"
  27 +.Fa "const wchar_t *restrict ws2"
  28 +.Fa "size_t n"
  29 +.Fa "locale_t loc"
  30 +.Fc
  31  .Sh DESCRIPTION
  32  The
  33  .Fn wcsxfrm
  34  function transforms a null-terminated wide character string pointed to by
  35 -.Fa src
  36 -according to the current locale collation order
  37 -then copies the transformed string
  38 -into
  39 -.Fa dst .
  40 +.Fa ws2 ,
  41 +according to the current locale's collation order,
  42 +then copies the transformed string into
  43 +.Fa ws1 .
  44  No more than
  45  .Fa n
  46  wide characters are copied into
  47 -.Fa dst ,
  48 -including the terminating null character added.
  49 +.Fa ws1 ,
  50 +including the terminating null character.
  51  If
  52  .Fa n
  53  is set to 0
  54  (it helps to determine an actual size needed
  55  for transformation),
  56 -.Fa dst
  57 +.Fa ws1
  58  is permitted to be a
  59  .Dv NULL
  60  pointer.
  61 @@ -76,6 +89,14 @@ after
  62  is equivalent to comparing
  63  two original strings with
  64  .Fn wcscoll .
  65 +.Pp
  66 +Although the
  67 +.Fn wcsxfrm
  68 +function uses the current locale, the
  69 +.Fn wcsxfrm_l
  70 +function may be passed a locale directly. See
  71 +.Xr xlocale 3
  72 +for more information.
  73  .Sh RETURN VALUES
  74  Upon successful completion,
  75  .Fn wcsxfrm
  76 @@ -84,13 +105,14 @@ the terminating null character.
  77  If this value is
  78  .Fa n
  79  or more, the contents of
  80 -.Fa dst
  81 +.Fa ws1
  82  are indeterminate.
  83  .Sh SEE ALSO
  84  .Xr setlocale 3 ,
  85  .Xr strxfrm 3 ,
  86  .Xr wcscmp 3 ,
  87 -.Xr wcscoll 3
  88 +.Xr wcscoll 3 ,
  89 +.Xr xlocale 3
  90  .Sh STANDARDS
  91  The
  92  .Fn wcsxfrm
  93 @@ -116,7 +138,7 @@ always equivalent to comparison with
  94  .Fn wcscoll ;
  95  .Fn wcsxfrm
  96  only stores information about primary collation weights into
  97 -.Fa dst ,
  98 +.Fa ws1 ,
  99  whereas
 100  .Fn wcscoll
 101  compares characters using both primary and secondary weights.