strxfrm(3C)                                                     strxfrm(3C)

NAME
     strxfrm - string transformation

SYNOPSIS
     #include <string.h>

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

DESCRIPTION
     strxfrm() transforms the string s2 and places the resulting string
     into the array s1. The transformation is such that if strcmp() is
     applied to two transformed strings, it will return a similar result as
     strcoll() applied to the same two original strings. The transformation
     is based on the program's locale for category LCCOLLATE [see
     setlocale(3C)].

     No more than n bytes will be placed into the resulting array pointed
     to by s1, including the terminating null character. If n is 0, then s1
     is permitted to be a null pointer. If copying takes place between two
     overlapping objects, the behavior is undefined.

     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 s1 are indeterminate.

EXAMPLE
     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);

RESULT
     On failure, strxfrm() returns the value (sizet)-1.

     Because no return value is reserved to indicate an error, an applica-
     tion wishing to check for error situations should set errno to 0, then
     call strxfrm(), then check errno. If it is non- zero, an error must
     have occurred.

FILES
     /usr/lib/locale/locale/LCCOLLATE
          database for locale

SEE ALSO
     colltbl(1M), setlocale(3C), strcoll(3C), string(3C), environ(5).










Page 1                       Reliant UNIX 5.44                Printed 11/98