Standard C Library Functions                          strxfrm(3C)



NAME
     strxfrm - string transformation

SYNOPSIS
     #include 

     sizet strxfrm(char *restrict s1, const char *restrict s2, sizet n);


DESCRIPTION
     The strxfrm() function transforms the string pointed  to  by
     s2 and places the resulting string into the array pointed to
     by s1. The transformation is  such  that  if  strcmp(3C)  is
     applied  to  two  transformed  strings,  it  returns a value
     greater than, equal to or less than 0, corresponding to  the
     result  of  strcoll(3C)  applied  to  the  same two original
     strings. No more than n bytes are placed into the  resulting
     array pointed to by s1, including the terminating null byte.
     If n is 0, s1 is permitted to be a null pointer. If  copying
     takes  place  between  objects that overlap, the behavior is
     undefined.


     The strxfrm() function does 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 strxfrm(), then check errno.

RETURN VALUES
     Upon successful completion, strxfrm() returns the length  of
     the  transformed  string (not including the terminating null
     byte). If the value returned is n or more, the  contents  of
     the array pointed to by s1 are indeterminate.


     On error, strxfrm() may set errno but  no  return  value  is
     reserved to indicate the error.

USAGE
     The transformation function is  such  that  two  transformed
     strings  can be ordered by strcmp(3C) as appropriate to col-
     lating  sequence  information  in   the   program's   locale
     (category LCOLATE).


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




SunOS 5.11          Last change: 10 Dec 2003                    1






Standard C Library Functions                          strxfrm(3C)



EXAMPLES
     Example 1 A sample of using the strxfm() function.


     The value of the following expression is  the  size  of  the
     array  needed  to  hold  the  transformation  of  the string
     pointed to by s.


       1 ] strxfrm(NUL, s, 0);


FILES
     /usr/lib/locale/locale/locale.so.*

         LCOLATE database for locale


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



     
           ATRIBUTE TYPE               ATRIBUTE VALUE       
    
     CSI                          Enabled                     
    
     Interface Stability          Standard                    
    
     MT-Level                     MT-Safe with exceptions     
    



     The strxfrm() function can be used safely in a multithreaded
     application, as long as setlocale(3C) is not being called to
     change the locale.

SEE ALSO
     localedef(1),   setlocale(3C),   strcmp(3C),    strcoll(3C),
     wscoll(3C), attributes(5), environ(5), standards(5)












SunOS 5.11          Last change: 10 Dec 2003                    2