'\"macro stdmacro
.if n .pH g3c.strxfrm 'ident	"@(#)strxfrm	40.11"'
.\" Copyright 1989 AT&T
.nr X
.if \nX=0 .ds x} strxfrm 3C "C Programming Language Utilities" "\&"
.if \nX=1 .ds x} strxfrm 3C "C Programming Language Utilities"
.if \nX=2 .ds x} strxfrm 3C "" "\&"
.if \nX=3 .ds x} strxfrm "" "" "\&"
.TH \*(x}
.SH NAME
\f4strxfrm\f1 \- string transformation
.SH SYNOPSIS
\f4#include <string.h>\f1
.PP
\f4size_t strxfrm (char \(**s1, const char \(**s2, size_t n);\f1
.SH DESCRIPTION
\f4strxfrm\fP transforms the string \f2s2\f1 and places the resulting
string into the array \f2s1\f1.  The transformation is such that
if \f4strcmp\fP is applied to two transformed strings, it will
return the same result as \f4strcoll\fP applied to the same two 
original strings.  The transformation is based on the program's locale
for category \f4LC_COLLATE\fP [see \f4setlocale\fP(3C)].
.PP
No more than \f2n\f1 characters will be placed into the resulting
array pointed to by \f2s1\f1, including the terminating
null character.  
If \f2n\f1 is 0, then \f2s1\f1 is permitted to be a null pointer. 
If copying takes place between objects that overlap,
the behavior is undefined.
.PP
\f4strxfrm\fP returns the length of the transformed string (not including
the terminating null character).  If the value returned is \f2n\f1 or
more, the contents of the array \f2s1\f1 are indeterminate.
.SH EXAMPLE
The value of the following expression is the size of the array needed to hold
the transformation of the string pointed to by \f2s\f1.
.PP
.RS
\f41 + strxfrm(NULL, s, 0);\f1
.RE
.SH FILES
.TP 2.5i
\f4/usr/lib/locale/\f2locale\f4/LC_COLLATE
\f4LC_COLLATE\fP database for \f2locale\f1.
.SH "SEE ALSO"
\f4colltbl\f1(1M) in the \f2System Administrator's Reference Manual\f1.
.br
\f4setlocale\fP(3C), \f4strcoll\fP(3C), \f4string\fP(3C), \f4environ\f1(5).
.SH DIAGNOSTICS
On failure, \f4strxfrm\fP returns \f4(size_t) -1\fP.
.\"	@(#)strxfrm.3c	
.Ee
