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 2015-08-08 "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 .TS
  53 allbox;
  54 lb lb lb
  55 l l l.
  56 Interface       Attribute       Value
  57 T{
  58 .BR btowc ()
  59 T}      Thread safety   MT-Safe
  60 .TE
  61 .SH CONFORMING TO
  62 POSIX.1-2001, POSIX.1-2008, C99.
  63 .SH NOTES
  64 The behavior of
  65 .BR btowc ()
  66 depends on the
  67 .B LC_CTYPE
  68 category of the
  69 current locale.
  70 .PP
  71 This function should never be used.
  72 It does not work for encodings which have
  73 state, and unnecessarily treats single bytes differently from multibyte
  74 sequences.
  75 Use either
  76 .BR mbtowc (3)
  77 or the thread-safe
  78 .BR mbrtowc (3)
  79 instead.
  80 .SH SEE ALSO
  81 .BR mbrtowc (3),
  82 .BR mbtowc (3),
  83 .BR wctob (3)