man3/mbsinit.3

   1 '\" t
   2 .\" Copyright (c) Bruno Haible <haible@clisp.cons.org>
   3 .\"
   4 .\" SPDX-License-Identifier: GPL-2.0-or-later
   5 .\"
   6 .\" References consulted:
   7 .\"   GNU glibc-2 source code and manual
   8 .\"   Dinkumware C library reference http://www.dinkumware.com/
   9 .\"   OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html
  10 .\"   ISO/IEC 9899:1999
  11 .\"
  12 .TH mbsinit 3 (date) "Linux man-pages (unreleased)"
  13 .SH NAME
  14 mbsinit \- test for initial shift state
  15 .SH LIBRARY
  16 Standard C library
  17 .RI ( libc ", " \-lc )
  18 .SH SYNOPSIS
  19 .nf
  20 .B #include <wchar.h>
  21 .P
  22 .BI "int mbsinit(const mbstate_t *" ps );
  23 .fi
  24 .SH DESCRIPTION
  25 Character conversion between the multibyte representation and the wide
  26 character representation uses conversion state, of type
  27 .IR mbstate_t .
  28 Conversion of a string uses a finite-state machine; when it is interrupted
  29 after the complete conversion of a number of characters, it may need to
  30 save a state for processing the remaining characters.
  31 Such a conversion
  32 state is needed for the sake of encodings such as ISO-2022 and UTF-7.
  33 .P
  34 The initial state is the state at the beginning of conversion of a string.
  35 There are two kinds of state: the one used by multibyte to wide character
  36 conversion functions, such as
  37 .BR mbsrtowcs (3),
  38 and the one used by wide
  39 character to multibyte conversion functions, such as
  40 .BR wcsrtombs (3),
  41 but they both fit in a
  42 .IR mbstate_t ,
  43 and they both have the same
  44 representation for an initial state.
  45 .P
  46 For 8-bit encodings, all states are equivalent to the initial state.
  47 For multibyte encodings like UTF-8, EUC-*, BIG5, or SJIS, the wide character
  48 to multibyte conversion functions never produce non-initial states, but the
  49 multibyte to wide-character conversion functions like
  50 .BR mbrtowc (3)
  51 do
  52 produce non-initial states when interrupted in the middle of a character.
  53 .P
  54 One possible way to create an
  55 .I mbstate_t
  56 in initial state is to set it to zero:
  57 .P
  58 .in +4n
  59 .EX
  60 mbstate_t state;
  61 memset(&state, 0, sizeof(state));
  62 .EE
  63 .in
  64 .P
  65 On Linux, the following works as well, but might generate compiler warnings:
  66 .P
  67 .in +4n
  68 .EX
  69 mbstate_t state = { 0 };
  70 .EE
  71 .in
  72 .P
  73 The function
  74 .BR mbsinit ()
  75 tests whether
  76 .I *ps
  77 corresponds to an
  78 initial state.
  79 .SH RETURN VALUE
  80 .BR mbsinit ()
  81 returns nonzero if
  82 .I *ps
  83 is an initial state, or if
  84 .I ps
  85 is NULL.
  86 Otherwise, it returns 0.
  87 .SH ATTRIBUTES
  88 For an explanation of the terms used in this section, see
  89 .BR attributes (7).
  90 .TS
  91 allbox;
  92 lbx lb lb
  93 l l l.
  94 Interface       Attribute       Value
  95 T{
  96 .na
  97 .nh
  98 .BR mbsinit ()
  99 T}      Thread safety   MT-Safe
 100 .TE
 101 .SH STANDARDS
 102 C11, POSIX.1-2008.
 103 .SH HISTORY
 104 POSIX.1-2001, C99.
 105 .SH NOTES
 106 The behavior of
 107 .BR mbsinit ()
 108 depends on the
 109 .B LC_CTYPE
 110 category of the
 111 current locale.
 112 .SH SEE ALSO
 113 .BR mbrlen (3),
 114 .BR mbrtowc (3),
 115 .BR mbsrtowcs (3),
 116 .BR wcrtomb (3),
 117 .BR wcsrtombs (3)