NAME

       strxfrm - string transformation

SYNOPSIS

       #include <string.h>

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

DESCRIPTION

       The  strxfrm()  function  shall transform the string pointed to by s2 and place the resulting string into
       the array pointed to by s1. The transformation is such that if strcmp() is  applied  to  two  transformed
       strings,  it  shall return a value greater than, equal to, or less than 0, corresponding to the result of
       strcoll() 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 shall 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 VALUE

       Upon  successful  completion,  strxfrm() shall return 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 unspecified.

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

ERRORS

       The strxfrm() function may fail if:

       EINVAL The  string  pointed to by the s2 argument contains characters outside the domain of the collating
              sequence.

       The following sections are informative.

EXAMPLES

       None.

APPLICATION USAGE

       The transformation function is  such  that  two  transformed  strings  can  be  ordered  by  strcmp()  as
       appropriate to collating 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.

RATIONALE

       None.

FUTURE DIRECTIONS

       None.

SEE ALSO

       strcmp() , strcoll() , the Base Definitions volume of IEEE Std 1003.1-2001, <string.h>

COPYRIGHT

       Portions of this text are reprinted and reproduced in electronic form from IEEE Std 1003.1, 2003 Edition,
       Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open  Group  Base
       Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of Electrical and Electronics Engineers,
       Inc  and  The  Open Group. In the event of any discrepancy between this version and the original IEEE and
       The Open Group Standard, the original IEEE and The Open Group  Standard  is  the  referee  document.  The
       original Standard can be obtained online at http://www.opengroup.org/unix/online.html .

IEEE/The Open Group                                   2003                                            STRXFRM(P)