# strxfrm

## PROLOG



           This manual page is part of the POSIX Programmer's Manual.  The
           Linux implementation of this interface may differ (consult the
           corresponding Linux manual page for details of Linux behavior), or
           the interface may not be implemented on Linux.
    


## NAME



           strxfrm, strxfrm_l — string transformation
    


## SYNOPSIS



           #include <string.h>
    
           size_t strxfrm(char *restrict _s1_ , const char *restrict _s2_ , size_t _n_);
           size_t strxfrm_l(char *restrict _s1_ , const char *restrict _s2_ ,
               size_t _n_ , locale_t _locale_);
    


## DESCRIPTION



           For _strxfrm_(): The functionality described on this reference page
           is aligned with the ISO C standard. Any conflict between the
           requirements described here and the ISO C standard is
           unintentional. This volume of POSIX.1‐2017 defers to the ISO C
           standard.
    
           The _strxfrm_() and _strxfrm_l_() functions 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_() or _strcoll_l_(), respectively, applied to the
           same two original strings with the same locale.  No more than _n_
           bytes are placed into the resulting array pointed to by _s1_ ,
           including the terminating NUL character. 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_() and _strxfrm_l_() functions 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_() or _strxfrm_l_(), then check _errno_.
    
           The behavior is undefined if the _locale_ argument to _strxfrm_l_() is
           the special locale object LC_GLOBAL_LOCALE or is not a valid
           locale object handle.
    


## RETURN VALUE



           Upon successful completion, _strxfrm_() and _strxfrm_l_() shall return
           the length of the transformed string (not including the
           terminating NUL character). If the value returned is _n_ or more,
           the contents of the array pointed to by _s1_ are unspecified.
    
           On error, _strxfrm_() and _strxfrm_l_() may set _errno_ but no return
           value is reserved to indicate an error.
    


## ERRORS



           These functions 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 current 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.
    


* * *