summaryrefslogtreecommitdiffstats
path: root/man3/mbrtowc.3
diff options
context:
space:
mode:
Diffstat (limited to 'man3/mbrtowc.3')
-rw-r--r--man3/mbrtowc.3201
1 files changed, 0 insertions, 201 deletions
diff --git a/man3/mbrtowc.3 b/man3/mbrtowc.3
deleted file mode 100644
index c35f540..0000000
--- a/man3/mbrtowc.3
+++ /dev/null
@@ -1,201 +0,0 @@
-'\" t
-.\" Copyright (c) Bruno Haible <haible@clisp.cons.org>
-.\"
-.\" SPDX-License-Identifier: GPL-2.0-or-later
-.\"
-.\" References consulted:
-.\" GNU glibc-2 source code and manual
-.\" Dinkumware C library reference http://www.dinkumware.com/
-.\" OpenGroup's Single UNIX specification
-.\" http://www.UNIX-systems.org/online.html
-.\" ISO/IEC 9899:1999
-.\"
-.TH mbrtowc 3 2023-10-31 "Linux man-pages 6.7"
-.SH NAME
-mbrtowc \- convert a multibyte sequence to a wide character
-.SH LIBRARY
-Standard C library
-.RI ( libc ", " \-lc )
-.SH SYNOPSIS
-.nf
-.B #include <wchar.h>
-.P
-.BI "size_t mbrtowc(wchar_t *restrict " pwc ", const char " s "[restrict ." n ],
-.BI " size_t " n ", mbstate_t *restrict " ps );
-.fi
-.SH DESCRIPTION
-The main case for this function is when
-.I s
-is not NULL and
-.I pwc
-is
-not NULL.
-In this case, the
-.BR mbrtowc ()
-function inspects at most
-.I n
-bytes of the multibyte string starting at
-.IR s ,
-extracts the next complete
-multibyte character, converts it to a wide character and stores it at
-.IR *pwc .
-It updates the shift state
-.IR *ps .
-If the converted wide
-character is not L\[aq]\e0\[aq] (the null wide character),
-it returns the number of bytes that were consumed
-from
-.IR s .
-If the converted wide character is L\[aq]\e0\[aq], it resets the shift
-state
-.I *ps
-to the initial state and returns 0.
-.P
-If the
-.I n
-bytes starting at
-.I s
-do not contain a complete multibyte
-character,
-.BR mbrtowc ()
-returns
-.IR "(size_t)\ \-2" .
-This can happen even if
-.I n
->=
-.IR MB_CUR_MAX ,
-if the multibyte string contains redundant shift
-sequences.
-.P
-If the multibyte string starting at
-.I s
-contains an invalid multibyte
-sequence before the next complete character,
-.BR mbrtowc ()
-returns
-.I (size_t)\ \-1
-and sets
-.I errno
-to
-.BR EILSEQ .
-In this case,
-the effects on
-.I *ps
-are undefined.
-.P
-A different case is when
-.I s
-is not NULL but
-.I pwc
-is NULL.
-In this case, the
-.BR mbrtowc ()
-function behaves as above, except that it does not
-store the converted wide character in memory.
-.P
-A third case is when
-.I s
-is NULL.
-In this case,
-.I pwc
-and
-.I n
-are
-ignored.
-If the conversion state represented by
-.I *ps
-denotes an
-incomplete multibyte character conversion, the
-.BR mbrtowc ()
-function
-returns
-.IR "(size_t)\ \-1" ,
-sets
-.I errno
-to
-.BR EILSEQ ,
-and
-leaves
-.I *ps
-in an undefined state.
-Otherwise, the
-.BR mbrtowc ()
-function
-puts
-.I *ps
-in the initial state and returns 0.
-.P
-In all of the above cases, if
-.I ps
-is NULL, a static anonymous
-state known only to the
-.BR mbrtowc ()
-function is used instead.
-Otherwise,
-.I *ps
-must be a valid
-.I mbstate_t
-object.
-An
-.I mbstate_t
-object
-.I a
-can be initialized to the initial state
-by zeroing it, for example using
-.P
-.in +4n
-.EX
-memset(&a, 0, sizeof(a));
-.EE
-.in
-.SH RETURN VALUE
-The
-.BR mbrtowc ()
-function returns the number of bytes parsed from the
-multibyte sequence starting at
-.IR s ,
-if a non-L\[aq]\e0\[aq] wide character
-was recognized.
-It returns 0, if a L\[aq]\e0\[aq] wide character was recognized.
-It returns
-.I (size_t)\ \-1
-and sets
-.I errno
-to
-.BR EILSEQ ,
-if an invalid multibyte sequence was
-encountered.
-It returns
-.I "(size_t)\ \-2"
-if it couldn't parse a complete multibyte
-character, meaning that
-.I n
-should be increased.
-.SH ATTRIBUTES
-For an explanation of the terms used in this section, see
-.BR attributes (7).
-.TS
-allbox;
-lbx lb lb
-l l l.
-Interface Attribute Value
-T{
-.na
-.nh
-.BR mbrtowc ()
-T} Thread safety MT-Unsafe race:mbrtowc/!ps
-.TE
-.SH STANDARDS
-C11, POSIX.1-2008.
-.SH HISTORY
-POSIX.1-2001, C99.
-.SH NOTES
-The behavior of
-.BR mbrtowc ()
-depends on the
-.B LC_CTYPE
-category of the
-current locale.
-.SH SEE ALSO
-.BR mbsinit (3),
-.BR mbsrtowcs (3)