wsxfrm(3C)




NAME

     wcsxfrm, wsxfrm - wide character string transformation


SYNOPSIS

     #include <wchar.h>

     size_t wcsxfrm(wchar_t *ws1, const wchar_t *ws2, size_t n);

     size_t wsxfrm(wchar_t *ws1, const wchar_t *ws2, size_t n);


DESCRIPTION

     The wcsxfrm() and wcsxfrm()  functions  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  is  such  that  if  either the wcscmp(3C) or
     wscmp(3C) functions are  applied  to  two  transformed  wide
     strings, they return a value greater than, equal to, or less
     than 0, corresponding to the result of the   wcscoll(3C)  or
     wscoll(3C)  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
     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.


RETURN VALUES

     The wcsxfrm() and wsxfrm() functions 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 indeterminate.

     On error, wcsxfrm() and wsxfrm() return  (size_t)-1 and  set
     errno to indicate the error.


ERRORS

     The wcsxfrm() and wsxfrm() functions may fail if:

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

     ENOSYS
           The function is not supported.


USAGE

     The transformation function is such  that   two  transformed
     wide  character  strings  can be ordered by the  wcscmp() or
     wscmp()  functions  as  appropriate  to  collating  sequence
     information in the program's 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.

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

     The wcsxfrm() and wsxfrm() functions can be used  safely  in
     multithreaded  applications  as long as setlocale(3C) is not
     being called to change the locale.


ATTRIBUTES

     See attributes(5) for descriptions of the  following  attri-
     butes:

     ____________________________________________________________
    |       ATTRIBUTE TYPE        |       ATTRIBUTE VALUE       |
    | MT-Level                    | MT-Safe with exceptions     |
    | CSI                         | Enabled                     |
    |_____________________________|_____________________________|


SEE ALSO

     setlocale(3C),    wcscmp(3C),    wcscoll(3C),     wscmp(3C),
     wscoll(3C), attributes(5)


Man(1) output converted with man2html