man3/strxfrm.3

   1 '\" t
   2 .\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk)
   3 .\"
   4 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
   5 .\"
   6 .\" References consulted:
   7 .\"     Linux libc source code
   8 .\"     Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991)
   9 .\"     386BSD man pages
  10 .\" Modified Sun Jul 25 10:41:28 1993 by Rik Faith (faith@cs.unc.edu)
  11 .TH strxfrm 3 (date) "Linux man-pages (unreleased)"
  12 .SH NAME
  13 strxfrm \- string transformation
  14 .SH LIBRARY
  15 Standard C library
  16 .RI ( libc ", " \-lc )
  17 .SH SYNOPSIS
  18 .nf
  19 .B #include <string.h>
  20 .P
  21 .BI "size_t strxfrm(char " dest "[restrict ." n "], \
  22 const char " src "[restrict ." n ],
  23 .BI "               size_t " n );
  24 .fi
  25 .SH DESCRIPTION
  26 The
  27 .BR strxfrm ()
  28 function transforms the
  29 .I src
  30 string into a
  31 form such that the result of
  32 .BR strcmp (3)
  33 on two strings that have
  34 been transformed with
  35 .BR strxfrm ()
  36 is the same as the result of
  37 .BR strcoll (3)
  38 on the two strings before their transformation.
  39 The first
  40 .I n
  41 bytes of the transformed string are placed in
  42 .IR dest .
  43 The transformation is based on the program's current
  44 locale for category
  45 .BR LC_COLLATE .
  46 (See
  47 .BR setlocale (3)).
  48 .SH RETURN VALUE
  49 The
  50 .BR strxfrm ()
  51 function returns the number of bytes required to
  52 store the transformed string in
  53 .I dest
  54 excluding the
  55 terminating null byte (\[aq]\e0\[aq]).
  56 If the value returned is
  57 .I n
  58 or more, the
  59 contents of
  60 .I dest
  61 are indeterminate.
  62 .SH ATTRIBUTES
  63 For an explanation of the terms used in this section, see
  64 .BR attributes (7).
  65 .TS
  66 allbox;
  67 lbx lb lb
  68 l l l.
  69 Interface       Attribute       Value
  70 T{
  71 .na
  72 .nh
  73 .BR strxfrm ()
  74 T}      Thread safety   MT-Safe locale
  75 .TE
  76 .SH STANDARDS
  77 C11, POSIX.1-2008.
  78 .SH HISTORY
  79 POSIX.1-2001, C89, SVr4, 4.3BSD.
  80 .SH SEE ALSO
  81 .BR memcmp (3),
  82 .BR setlocale (3),
  83 .BR strcasecmp (3),
  84 .BR strcmp (3),
  85 .BR strcoll (3),
  86 .BR string (3)