Debian Codegraph @

upstream/debian-unstable/man3/btowc.3

raw
1 '\" t
2 .\" Copyright, Bruno Haible <[email protected]>
3 .\" Copyright, the authors of the Linux man-pages project
4 .\"
5 .\" SPDX-License-Identifier: GPL-2.0-or-later
6 .\"
7 .TH btowc 3 2026-02-08 "Linux man-pages 6.18"
8 .SH NAME
9 btowc \- convert single byte to wide character
10 .SH LIBRARY
11 Standard C library
12 .RI ( libc ,\~ \-lc )
13 .SH SYNOPSIS
14 .nf
15 .B #include <wchar.h>
16 .P
17 .BI "wint_t btowc(int " c );
18 .fi
19 .SH DESCRIPTION
20 The
21 .BR btowc ()
22 function converts
23 .IR c ,
24 interpreted as a multibyte sequence
25 of length 1, starting in the initial shift state, to a wide character and
26 returns it.
27 If
28 .I c
29 is
30 .B EOF
31 or not a valid multibyte sequence of length 1,
32 the
33 .BR btowc ()
34 function returns
35 .BR WEOF .
36 .SH RETURN VALUE
37 The
38 .BR btowc ()
39 function returns the wide character
40 converted from the single byte
41 .IR c .
42 If
43 .I c
44 is
45 .B EOF
46 or not a valid multibyte sequence of length 1,
47 it returns
48 .BR WEOF .
49 .SH ATTRIBUTES
50 For an explanation of the terms used in this section, see
51 .BR attributes (7).
52 .TS
53 allbox;
54 lbx lb lb
55 l l l.
56 Interface Attribute Value
57 T{
58 .na
59 .nh
60 .BR btowc ()
61 T} Thread safety MT-Safe
62 .TE
63 .SH STANDARDS
64 C11, POSIX.1-2008.
65 .SH HISTORY
66 C99, POSIX.1-2001.
67 .SH NOTES
68 The behavior of
69 .BR btowc ()
70 depends on the
71 .B LC_CTYPE
72 category of the
73 current locale.
74 .P
75 This function should never be used.
76 It does not work for encodings which have
77 state, and unnecessarily treats single bytes differently from multibyte
78 sequences.
79 Use either
80 .BR mbtowc (3)
81 or the thread-safe
82 .BR mbrtowc (3)
83 instead.
84 .SH SEE ALSO
85 .BR mbrtowc (3),
86 .BR mbtowc (3),
87 .BR wctob (3)