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