wcsxfrm(3C)                                                     wcsxfrm(3C)

NAME
     wcsxfrm - wide character string transformation

SYNOPSIS
     #include <wchar.h>

     sizet wcsxfrm(wchart *ws1, const wchart *ws2, sizet n);

DESCRIPTION
     The wcsxfrm() function transforms the wide character string pointed to
     by ws2 and places the resulting wide character string into the array
     pointed to by ws1. The transformation is such that if the wcscmp()
     function is applied to two transformed wide strings, it returns a
     value greater than, equal to or less than zero, corresponding to the
     result of the wcscoll() function applied to the same two original wide
     character strings. No more than n wide character codes are placed into
     the resulting array pointed to by ws1, including terminating null wide
     character code. If n is zero, ws1 is permitted to be a null pointer.
     If copying takes place between objects that overlap, the behavior is
     undefined.

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

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

     Because no return value is reserved to indicate an error, an applica-
     tion wishing to check for error situations should set errno to zero,
     then call wcsxfrm(), then check errno and if it is non-zero assume an
     error has occurred.

     The wcsxfrm() function may fail if:

     ENOSYS   The function is not supported.

RESULT
     The wcsxfrm() function returns 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 indeterminate.

     On error, the wcsxfrm() function returns (sizet)-1, and sets errno to
     indicate the error.

SEE ALSO
     wcscmp(3C), wcscoll(3C), wchar(5).





Page 1                       Reliant UNIX 5.44                Printed 11/98