strxfrm(3C)




NAME

     strxfrm - string transformation


SYNOPSIS

     #include <string.h>

     size_t strxfrm(char *s1, const char *s2, size_t 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.


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 failure, strxfrm() returns (size_t)-1.


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

     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.

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

     This issue is aligned with the ANSI C  standard;  this  does
     not  affect  compatibility  with XPG3 applications. Reliable
     error detection by this function was never guaranteed.


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(NULL, s, 0);


FILES

     /usr/lib/locale/locale/locale.so.*
           LC_COLLATE database for 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

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


NOTES

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


Man(1) output converted with man2html