PROLOG

       This  manual  page  is part of the POSIX Programmer's Manual.  The Linux implementation of this interface
       may differ (consult the corresponding Linux manual page for details of Linux behavior), or the  interface
       may not be implemented on Linux.

NAME

       wcsxfrm, wcsxfrm_l — wide-character string transformation

SYNOPSIS

       #include <wchar.h>

       size_t wcsxfrm(wchar_t *restrict ws1, const wchar_t *restrict ws2,
           size_t n);
       size_t wcsxfrm_l(wchar_t *restrict ws1, const wchar_t *restrict ws2,
           size_t n, locale_t locale);

DESCRIPTION

       For wcsxfrm(): The functionality described on this reference page is aligned with the ISO C standard. Any
       conflict  between the requirements described here and the ISO C standard is unintentional. This volume of
       POSIX.1‐2017 defers to the ISO C standard.

       The wcsxfrm() and wcsxfrm_l() functions shall transform the wide-character string pointed to by  ws2  and
       place  the resulting wide-character string into the array pointed to by ws1.  The transformation shall be
       such that if wcscmp() is applied to two transformed wide strings, it shall return a value  greater  than,
       equal  to,  or  less than 0, corresponding to the result of wcscoll() and wcscoll_l() applied to the same
       two original wide-character strings, and the same LC_COLLATE category of the current locale or the locale
       object locale, respectively. No more than n wide-character codes shall be placed into the resulting array
       pointed to by ws1, including the terminating null wide-character code. If n is 0, ws1 is permitted to  be
       a null pointer. If copying takes place between objects that overlap, the behavior is undefined.

       The wcsxfrm() and wcsxfrm_l() functions shall not change the setting of errno if successful.

       Since  no  return  value  is  reserved  to  indicate  an error, an application wishing to check for error
       situations should set errno to 0, then call wcsxfrm() or wcsxfrm_l(), then check errno.

       The behavior  is  undefined  if  the  locale  argument  to  wcsxfrm_l()  is  the  special  locale  object
       LC_GLOBAL_LOCALE or is not a valid locale object handle.

RETURN VALUE

       The  wcsxfrm() and wcsxfrm_l() functions shall return the length of the transformed wide-character string
       (not including the terminating null wide-character code). If  the  value  returned  is  n  or  more,  the
       contents of the array pointed to by ws1 are unspecified.

       On  error,  the  wcsxfrm()  and  wcsxfrm_l()  functions may set errno, but no return value is reserved to
       indicate an error.

ERRORS

       These functions may fail if:

       EINVAL The wide-character string pointed to by ws2 contains wide-character codes outside  the  domain  of
              the collating sequence.

       The following sections are informative.

EXAMPLES

       None.

APPLICATION USAGE

       The  transformation  function  is  such  that  two  transformed  wide-character strings can be ordered by
       wcscmp() as appropriate to collating sequence information in the current locale (category LC_COLLATE).

       The fact that when n is 0 ws1 is permitted to be a null pointer is useful to determine the  size  of  the
       ws1 array prior to making the transformation.

RATIONALE

       None.

FUTURE DIRECTIONS

       None.

SEE ALSO

       wcscmp(), wcscoll()

       The Base Definitions volume of POSIX.1‐2017, <wchar.h>

COPYRIGHT

       Portions of this text are reprinted and reproduced in electronic form from IEEE Std 1003.1-2017, Standard
       for  Information  Technology  --  Portable  Operating  System  Interface  (POSIX),  The  Open  Group Base
       Specifications Issue 7, 2018 Edition, Copyright (C) 2018 by the Institute of Electrical  and  Electronics
       Engineers, Inc and The Open Group.  In the event of any discrepancy between this version and the original
       IEEE  and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document.
       The original Standard can be obtained online at http://www.opengroup.org/unix/online.html .

       Any typographical or formatting errors that appear in this page are most likely to have  been  introduced
       during   the   conversion  of  the  source  files  to  man  page  format.  To  report  such  errors,  see
       https://www.kernel.org/doc/man-pages/reporting_bugs.html .

IEEE/The Open Group                                   2017                                       WCSXFRM(3POSIX)