man3/mblen.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 MBLEN 3  2021-03-22 "GNU" "Linux Programmer's Manual"
  12 .SH NAME
  13 mblen \- 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 <stdlib.h>
  20 .PP
  21 .BI "int mblen(const char *" s ", size_t " n );
  22 .fi
  23 .SH DESCRIPTION
  24 If
  25 .I s
  26 is not NULL, the
  27 .BR mblen ()
  28 function inspects at most
  29 .I n
  30 bytes of the multibyte string starting at
  31 .I s
  32 and extracts the
  33 next complete multibyte character.
  34 It uses a static anonymous shift state known only to the
  35 .BR mblen ()
  36 function.
  37 If the multibyte character is not the null wide
  38 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 returns 0.
  41 .PP
  42 If the
  43 .IR n
  44 bytes starting at
  45 .I s
  46 do not contain a complete multibyte
  47 character,
  48 .BR mblen ()
  49 returns \-1.
  50 This can happen even if
  51 .I n
  52 is greater than or equal to
  53 .IR MB_CUR_MAX ,
  54 if the multibyte string contains redundant shift sequences.
  55 .PP
  56 If the multibyte string starting at
  57 .I s
  58 contains an invalid multibyte
  59 sequence before the next complete character,
  60 .BR mblen ()
  61 also returns \-1.
  62 .PP
  63 If
  64 .I s
  65 is NULL, the
  66 .BR mblen ()
  67 function
  68 .\" The Dinkumware doc and the Single UNIX specification say this, but
  69 .\" glibc doesn't implement this.
  70 resets the shift state, known to only this function, to the initial state, and
  71 returns nonzero if the encoding has nontrivial shift state, or zero if the
  72 encoding is stateless.
  73 .SH RETURN VALUE
  74 The
  75 .BR mblen ()
  76 function returns the number of
  77 bytes parsed from the multibyte
  78 sequence starting at
  79 .IR s ,
  80 if a non-null wide character was recognized.
  81 It returns 0, if a null wide character was recognized.
  82 It returns \-1, if an
  83 invalid multibyte sequence was encountered or if it couldn't parse a complete
  84 multibyte character.
  85 .SH ATTRIBUTES
  86 For an explanation of the terms used in this section, see
  87 .BR attributes (7).
  88 .ad l
  89 .nh
  90 .TS
  91 allbox;
  92 lbx lb lb
  93 l l l.
  94 Interface       Attribute       Value
  95 T{
  96 .BR mblen ()
  97 T}      Thread safety   MT-Unsafe race
  98 .TE
  99 .hy
 100 .ad
 101 .sp 1
 102 .SH CONFORMING TO
 103 POSIX.1-2001, POSIX.1-2008, C99.
 104 .SH NOTES
 105 The behavior of
 106 .BR mblen ()
 107 depends on the
 108 .B LC_CTYPE
 109 category of the
 110 current locale.
 111 .PP
 112 The function
 113 .BR mbrlen (3)
 114 provides a better interface to the same
 115 functionality.
 116 .SH SEE ALSO
 117 .BR mbrlen (3)