man3p/mbrtowc.3p

   1 .\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved
   2 .TH "MBRTOWC" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual"
   3 .\" mbrtowc
   4 .SH NAME
   5 mbrtowc \- convert a character to a wide-character code (restartable)
   6 .SH SYNOPSIS
   7 .LP
   8 \fB#include <wchar.h>
   9 .br
  10 .sp
  11 size_t mbrtowc(wchar_t *restrict\fP \fIpwc\fP\fB, const char *restrict\fP
  12 \fIs\fP\fB,
  13 .br
  14 \ \ \ \ \ \  size_t\fP \fIn\fP\fB, mbstate_t *restrict\fP \fIps\fP\fB);
  15 .br
  16 \fP
  17 .SH DESCRIPTION
  18 .LP
  19 If \fIs\fP is a null pointer, the \fImbrtowc\fP() function shall be
  20 equivalent to the call:
  21 .sp
  22 .RS
  23 .nf
  24
  25 \fBmbrtowc(NULL, "", 1, ps)
  26 \fP
  27 .fi
  28 .RE
  29 .LP
  30 In this case, the values of the arguments \fIpwc\fP and \fIn\fP are
  31 ignored.
  32 .LP
  33 If \fIs\fP is not a null pointer, the \fImbrtowc\fP() function shall
  34 inspect at most \fIn\fP bytes beginning at the byte
  35 pointed to by \fIs\fP to determine the number of bytes needed to complete
  36 the next character (including any shift sequences). If
  37 the function determines that the next character is completed, it shall
  38 determine the value of the corresponding wide character and
  39 then, if \fIpwc\fP is not a null pointer, shall store that value in
  40 the object pointed to by \fIpwc\fP. If the corresponding wide
  41 character is the null wide character, the resulting state described
  42 shall be the initial conversion state.
  43 .LP
  44 If \fIps\fP is a null pointer, the \fImbrtowc\fP() function shall
  45 use its own internal \fBmbstate_t\fP object, which shall be
  46 initialized at program start-up to the initial conversion state. Otherwise,
  47 the \fBmbstate_t\fP object pointed to by \fIps\fP
  48 shall be used to completely describe the current conversion state
  49 of the associated character sequence. The implementation shall
  50 behave as if no function defined in this volume of IEEE\ Std\ 1003.1-2001
  51 calls \fImbrtowc\fP().
  52 .LP
  53 The behavior of this function is affected by the \fILC_CTYPE\fP category
  54 of the current locale.
  55 .SH RETURN VALUE
  56 .LP
  57 The \fImbrtowc\fP() function shall return the first of the following
  58 that applies:
  59 .TP 7
  60 0
  61 If the next \fIn\fP or fewer bytes complete the character that corresponds
  62 to the null wide character (which is the value
  63 stored).
  64 .TP 7
  65 between 1 and \fIn\fP inclusive
  66 .sp
  67 If the next \fIn\fP or fewer bytes complete a valid character (which
  68 is the value stored); the value returned shall be the number
  69 of bytes that complete the character.
  70 .TP 7
  71 (\fBsize_t\fP)-2
  72 If the next \fIn\fP bytes contribute to an incomplete but potentially
  73 valid character, and all \fIn\fP bytes have been
  74 processed (no value is stored). When \fIn\fP has at least the value
  75 of the {MB_CUR_MAX} macro, this case can only occur if
  76 \fIs\fP points at a sequence of redundant shift sequences (for implementations
  77 with state-dependent encodings).
  78 .TP 7
  79 (\fBsize_t\fP)-1
  80 If an encoding error occurs, in which case the next \fIn\fP or fewer
  81 bytes do not contribute to a complete and valid character
  82 (no value is stored). In this case, [EILSEQ] shall be stored in \fIerrno\fP
  83 and the conversion state is undefined.
  84 .sp
  85 .SH ERRORS
  86 .LP
  87 The \fImbrtowc\fP() function may fail if:
  88 .TP 7
  89 .B EINVAL
  90 \fIps\fP points to an object that contains an invalid conversion state.
  91 .TP 7
  92 .B EILSEQ
  93 Invalid character sequence is detected.
  94 .sp
  95 .LP
  96 \fIThe following sections are informative.\fP
  97 .SH EXAMPLES
  98 .LP
  99 None.
 100 .SH APPLICATION USAGE
 101 .LP
 102 None.
 103 .SH RATIONALE
 104 .LP
 105 None.
 106 .SH FUTURE DIRECTIONS
 107 .LP
 108 None.
 109 .SH SEE ALSO
 110 .LP
 111 \fImbsinit\fP() , the Base Definitions volume of IEEE\ Std\ 1003.1-2001,
 112 \fI<wchar.h>\fP
 113 .SH COPYRIGHT
 114 Portions of this text are reprinted and reproduced in electronic form
 115 from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
 116 -- Portable Operating System Interface (POSIX), The Open Group Base
 117 Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of
 118 Electrical and Electronics Engineers, Inc and The Open Group. In the
 119 event of any discrepancy between this version and the original IEEE and
 120 The Open Group Standard, the original IEEE and The Open Group Standard
 121 is the referee document. The original Standard can be obtained online at
 122 http://www.opengroup.org/unix/online.html .