strxfrm(3)						     Library Functions Manual							strxfrm(3)

NAME

       strxfrm - Transforms string for collation in current locale

LIBRARY

       Standard C Library (libc.so, libc.a)

SYNOPSIS

       #include <string.h>

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

STANDARDS

       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

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

DESCRIPTION

       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

       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  multi-level  colla-
       tion.  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

       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

       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.

RELATED INFORMATION

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

       Standards: standards(5) delim off

																	strxfrm(3)