man3/mbrlen.3

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