# wcsxfrm

## 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.
    


* * *