man3/btowc.3

   1 .\" Copyright (c) Bruno Haible <haible@clisp.cons.org>
   2 .\"
   3 .\" %%%LICENSE_START(GPLv2+_DOC_ONEPARA)
   4 .\" This is free documentation; you can redistribute it and/or
   5 .\" modify it under the terms of the GNU General Public License as
   6 .\" published by the Free Software Foundation; either version 2 of
   7 .\" the License, or (at your option) any later version.
   8 .\" %%%LICENSE_END
   9 .\"
  10 .\" References consulted:
  11 .\"   GNU glibc-2 source code and manual
  12 .\"   Dinkumware C library reference http://www.dinkumware.com/
  13 .\"   OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html
  14 .\"   ISO/IEC 9899:1999
  15 .\"
  16 .TH BTOWC 3 2021-03-22 "GNU" "Linux Programmer's Manual"
  17 .SH NAME
  18 btowc \- convert single byte to wide character
  19 .SH SYNOPSIS
  20 .nf
  21 .B #include <wchar.h>
  22 .PP
  23 .BI "wint_t btowc(int " c );
  24 .fi
  25 .SH DESCRIPTION
  26 The
  27 .BR btowc ()
  28 function converts \fIc\fP,
  29 interpreted as a multibyte sequence
  30 of length 1, starting in the initial shift state, to a wide character and
  31 returns it.
  32 If \fIc\fP is
  33 .B EOF
  34 or not a valid multibyte sequence of length 1,
  35 the
  36 .BR btowc ()
  37 function returns
  38 .BR WEOF .
  39 .SH RETURN VALUE
  40 The
  41 .BR btowc ()
  42 function returns the wide character
  43 converted from the single byte \fIc\fP.
  44 If \fIc\fP 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 .ad l
  53 .nh
  54 .TS
  55 allbox;
  56 lbx lb lb
  57 l l l.
  58 Interface       Attribute       Value
  59 T{
  60 .BR btowc ()
  61 T}      Thread safety   MT-Safe
  62 .TE
  63 .hy
  64 .ad
  65 .sp 1
  66 .SH CONFORMING TO
  67 POSIX.1-2001, POSIX.1-2008, C99.
  68 .SH NOTES
  69 The behavior of
  70 .BR btowc ()
  71 depends on the
  72 .B LC_CTYPE
  73 category of the
  74 current locale.
  75 .PP
  76 This function should never be used.
  77 It does not work for encodings which have
  78 state, and unnecessarily treats single bytes differently from multibyte
  79 sequences.
  80 Use either
  81 .BR mbtowc (3)
  82 or the thread-safe
  83 .BR mbrtowc (3)
  84 instead.
  85 .SH SEE ALSO
  86 .BR mbrtowc (3),
  87 .BR mbtowc (3),
  88 .BR wctob (3)