original/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 2011-09-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 .sp
  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 CONFORMING TO
  50 C99, POSIX.1-2001.
  51 .SH NOTES
  52 The behavior of
  53 .BR btowc ()
  54 depends on the
  55 .B LC_CTYPE
  56 category of the
  57 current locale.
  58 .PP
  59 This function should never be used.
  60 It does not work for encodings which have
  61 state, and unnecessarily treats single bytes differently from multibyte
  62 sequences.
  63 Use either
  64 .BR mbtowc (3)
  65 or the thread-safe
  66 .BR mbrtowc (3)
  67 instead.
  68 .SH SEE ALSO
  69 .BR mbrtowc (3),
  70 .BR mbtowc (3),
  71 .BR wctob (3)
  72 .SH COLOPHON
  73 This page is part of release 3.68 of the Linux
  74 .I man-pages
  75 project.
  76 A description of the project,
  77 information about reporting bugs,
  78 and the latest version of this page,
  79 can be found at
  80 \%http://www.kernel.org/doc/man\-pages/.