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  2013-06-21 "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 .sp
  23 .BI "size_t mbrlen(const char *" s ", size_t " n ", mbstate_t *" 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 .IR 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 .IR "(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 .IR "(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 .SS Multithreading (see pthreads(7))
 106 The
 107 .BR mbrlen ()
 108 function is thread-safe with exceptions.
 109 It is not thread-safe if called with a NULL \fIps\fP parameter.
 110 .SH CONFORMING TO
 111 C99.
 112 .SH NOTES
 113 The behavior of
 114 .BR mbrlen ()
 115 depends on the
 116 .B LC_CTYPE
 117 category of the
 118 current locale.
 119 .SH SEE ALSO
 120 .BR mbrtowc (3)