man3/btowc.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 btowc 3 (date) "Linux man-pages (unreleased)"
  13 .SH NAME
  14 btowc \- convert single byte to wide character
  15 .SH LIBRARY
  16 Standard C library
  17 .RI ( libc ", " \-lc )
  18 .SH SYNOPSIS
  19 .nf
  20 .B #include <wchar.h>
  21 .PP
  22 .BI "wint_t btowc(int " c );
  23 .fi
  24 .SH DESCRIPTION
  25 The
  26 .BR btowc ()
  27 function converts \fIc\fP,
  28 interpreted as a multibyte sequence
  29 of length 1, starting in the initial shift state, to a wide character and
  30 returns it.
  31 If \fIc\fP is
  32 .B EOF
  33 or not a valid multibyte sequence of length 1,
  34 the
  35 .BR btowc ()
  36 function returns
  37 .BR WEOF .
  38 .SH RETURN VALUE
  39 The
  40 .BR btowc ()
  41 function returns the wide character
  42 converted from the single byte \fIc\fP.
  43 If \fIc\fP is
  44 .B EOF
  45 or not a valid multibyte sequence of length 1,
  46 it returns
  47 .BR WEOF .
  48 .SH ATTRIBUTES
  49 For an explanation of the terms used in this section, see
  50 .BR attributes (7).
  51 .ad l
  52 .nh
  53 .TS
  54 allbox;
  55 lbx lb lb
  56 l l l.
  57 Interface       Attribute       Value
  58 T{
  59 .BR btowc ()
  60 T}      Thread safety   MT-Safe
  61 .TE
  62 .hy
  63 .ad
  64 .sp 1
  65 .SH STANDARDS
  66 POSIX.1-2001, POSIX.1-2008, C99.
  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 .PP
  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)