NAME    [Toc]    [Back]

       strxfrm  -  Transforms  string  for  collation  in current
       locale

SYNOPSIS    [Toc]    [Back]

       #include <string.h>

       size_t strxfrm(
               char *s1,
               const char *s2,
               size_t n );

LIBRARY    [Toc]    [Back]

       Standard C Library (libc)

STANDARDS    [Toc]    [Back]

       Interfaces documented on this reference  page  conform  to
       industry standards as follows:

       strxfrm():  XPG4, XPG4-UNIX

       Refer to the standards(5) reference page for more information
 about industry standards and associated tags.

PARAMETERS    [Toc]    [Back]

       Specifies the destination string.  Specifies the string to
       be  transformed.  Specifies the maximum number of bytes to
       store in the transformed string.

DESCRIPTION    [Toc]    [Back]

       The strxfrm() function transforms the string pointed to by
       the s2 parameter into an internal form suitable for collation
 and places the result in the address specified by s1.
       This  transformation  is  performed  as appropriate to the
       LC_COLLATE category of the current locale. When  the  strcmp()
  function  is  applied to two transformed strings, a
       value greater than, equal to, or less  than  0  (zero)  is
       returned. The returned value corresponds to the same value
       that is returned when the strcoll() function is applied to
       the same two original transformed strings. The transformed
       string can be longer than the  original  string.  No  more
       than n characters are placed in the location pointed to by
       the s1 parameter, including the terminating  null  character.
  When  n  is 0 (zero), the s1 parameter can be a null
       pointer. When operating on overlapping strings, the behavior
 of this function is unreliable.

NOTES    [Toc]    [Back]

       If  you  are doing multiple comparisons using the same set
       of text strings, the strxfrm() transformation function  in
       conjunction  with  the strcmp() function may be more efficient
 than using the strcoll() collation function  because
       the  string is transformed based on the locale tables only
       once. However, the transformation  function  must  convert
       all  characters  in  the string for each level of a multilevel
 collation. In  comparison,  the  collation  function
       stops  comparing characters at the first inequality. These
       efficiency tradeoffs make the most efficient method for  a
       specific  application  dependent  on  both  the  number of
       repeated comparisons for each string and the  contents  of
       each string.

RETURN VALUES    [Toc]    [Back]

       Upon successful completion, the strxfrm() function returns
       the number of bytes  required  to  store  the  transformed
       string  (not including the terminating null byte). If this
       is greater than or equal to the value of the n  parameter,
       which  specifies  the  maximum number of bytes that can be
       stored in s1, the contents of s1 are indeterminate.

ERRORS    [Toc]    [Back]

       If the following condition occurs, the strxfrm()  function
       sets  errno  to the corresponding value.  The s2 parameter
       contains  codes  outside  the  domain  of  the   collating
       sequence defined by the current locale.

SEE ALSO    [Toc]    [Back]

       Functions: setlocale(3), strcoll(3), string(3), strcmp(3),
       wcsxfrm(3)

       Standards: standards(5)



                                                       strxfrm(3)