mbsinit(3)

1mbsinit(3)                 Library Functions Manual                 mbsinit(3)
2
3
4

NAME

6       mbsinit - test for initial shift state
7

LIBRARY

9       Standard C library (libc, -lc)
10

SYNOPSIS

12       #include <wchar.h>
13
14       int mbsinit(const mbstate_t *ps);
15

DESCRIPTION

17       Character  conversion between the multibyte representation and the wide
18       character representation uses  conversion  state,  of  type  mbstate_t.
19       Conversion  of  a string uses a finite-state machine; when it is inter‐
20       rupted after the complete conversion of a number of characters, it  may
21       need  to  save a state for processing the remaining characters.  Such a
22       conversion state is needed for the sake of encodings such  as  ISO-2022
23       and UTF-7.
24
25       The  initial  state  is  the  state at the beginning of conversion of a
26       string.  There are two kinds of state: the one  used  by  multibyte  to
27       wide  character conversion functions, such as mbsrtowcs(3), and the one
28       used by wide character to multibyte conversion functions, such as wcsr‐
29       tombs(3), but they both fit in a mbstate_t, and they both have the same
30       representation for an initial state.
31
32       For 8-bit encodings, all states are equivalent to  the  initial  state.
33       For  multibyte  encodings  like  UTF-8,  EUC-*, BIG5, or SJIS, the wide
34       character to multibyte conversion functions never  produce  non-initial
35       states,  but  the multibyte to wide-character conversion functions like
36       mbrtowc(3) do produce non-initial states when interrupted in the middle
37       of a character.
38
39       One  possible  way to create an mbstate_t in initial state is to set it
40       to zero:
41
42           mbstate_t state;
43           memset(&state, 0, sizeof(state));
44
45       On Linux, the following works as  well,  but  might  generate  compiler
46       warnings:
47
48           mbstate_t state = { 0 };
49
50       The  function  mbsinit()  tests  whether  *ps corresponds to an initial
51       state.
52

RETURN VALUE

54       mbsinit() returns nonzero if *ps is an initial state, or if ps is NULL.
55       Otherwise, it returns 0.
56

ATTRIBUTES

58       For  an  explanation  of  the  terms  used  in  this  section,  see at‐
59       tributes(7).
60
61       ┌────────────────────────────────────────────┬───────────────┬─────────┐
62       │Interface                                   │ Attribute     │ Value   │
63       ├────────────────────────────────────────────┼───────────────┼─────────┤
64       │mbsinit()                                   │ Thread safety │ MT-Safe │
65       └────────────────────────────────────────────┴───────────────┴─────────┘
66

STANDARDS

68       C11, POSIX.1-2008.
69

HISTORY

71       POSIX.1-2001, C99.
72

NOTES

74       The behavior of mbsinit() depends on the LC_CTYPE category of the  cur‐
75       rent locale.
76