Standard C Library Functions                          wcsxfrm(3C)



NAME
     wcsxfrm, wsxfrm - wide character string transformation

SYNOPSIS
     #include 

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


     sizet wsxfrm(wchart *ws1, const wchart *ws2, sizet 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.


     The wcsxfrm() and wsxfrm() functions do not change the  set-
     ting 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  wsxfrm(),  then  check
     errno.

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() may set errno but no return
     value is reserved to indicate an error.

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





SunOS 5.11           Last change: 1 Nov 2003                    1






Standard C Library Functions                          wcsxfrm(3C)



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


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 LCOLATE).


     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.

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



     
     ATRIBUTE TYPE               ATRIBUTE VALUE             
    
     CSI                          Enabled                     
    
     Interface Stability          wcsxfrm() is Standard       
    
     MT-Level                     MT-Safe with exceptions     
    



     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.

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














SunOS 5.11           Last change: 1 Nov 2003                    2