man3/mbrlen.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 mbrlen 3 (date) "Linux man-pages (unreleased)"
  13 .SH NAME
  14 mbrlen \- determine number of bytes in next multibyte 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 "size_t mbrlen(const char " s "[restrict ." n "], size_t " n ,
  23 .BI "              mbstate_t *restrict " ps );
  24 .fi
  25 .SH DESCRIPTION
  26 The
  27 .BR mbrlen ()
  28 function inspects at most
  29 .I n
  30 bytes of the multibyte
  31 string starting at
  32 .I s
  33 and extracts the next complete multibyte character.
  34 It updates the shift state
  35 .IR *ps .
  36 If the multibyte character is not the
  37 null wide character, it returns the number of bytes that were consumed from
  38 .IR s .
  39 If the multibyte character is the null wide character, it resets the
  40 shift state
  41 .I *ps
  42 to the initial state and returns 0.
  43 .PP
  44 If the
  45 .I n
  46 bytes starting at
  47 .I s
  48 do not contain a complete multibyte
  49 character,
  50 .BR mbrlen ()
  51 returns
  52 .IR "(size_t)\ \-2" .
  53 This can happen even if
  54 .I n
  55 >=
  56 .IR MB_CUR_MAX ,
  57 if the multibyte string contains redundant shift
  58 sequences.
  59 .PP
  60 If the multibyte string starting at
  61 .I s
  62 contains an invalid multibyte
  63 sequence before the next complete character,
  64 .BR mbrlen ()
  65 returns
  66 .I (size_t)\ \-1
  67 and sets
  68 .I errno
  69 to
  70 .BR EILSEQ .
  71 In this case,
  72 the effects on
  73 .I *ps
  74 are undefined.
  75 .PP
  76 If
  77 .I ps
  78 is NULL, a static anonymous state known only to the
  79 .BR mbrlen ()
  80 function is used instead.
  81 .SH RETURN VALUE
  82 The
  83 .BR mbrlen ()
  84 function returns the number of bytes
  85 parsed from the multibyte
  86 sequence starting at
  87 .IR s ,
  88 if a non-null wide character was recognized.
  89 It returns 0, if a null wide character was recognized.
  90 It returns
  91 .I "(size_t)\ \-1"
  92 and sets
  93 .I errno
  94 to
  95 .BR EILSEQ ,
  96 if an invalid multibyte sequence was
  97 encountered.
  98 It returns
  99 .I (size_t)\ \-2
 100 if it couldn't parse a complete multibyte
 101 character, meaning that
 102 .I n
 103 should be increased.
 104 .SH ATTRIBUTES
 105 For an explanation of the terms used in this section, see
 106 .BR attributes (7).
 107 .ad l
 108 .nh
 109 .TS
 110 allbox;
 111 lbx lb lb
 112 l l l.
 113 Interface       Attribute       Value
 114 T{
 115 .BR mbrlen ()
 116 T}      Thread safety   MT-Unsafe race:mbrlen/!ps
 117 .TE
 118 .hy
 119 .ad
 120 .sp 1
 121 .SH STANDARDS
 122 C11, POSIX.1-2008.
 123 .SH HISTORY
 124 POSIX.1-2001, C99.
 125 .SH NOTES
 126 The behavior of
 127 .BR mbrlen ()
 128 depends on the
 129 .B LC_CTYPE
 130 category of the
 131 current locale.
 132 .SH SEE ALSO
 133 .BR mbrtowc (3)