.\" -*- coding: UTF-8 -*-
'\" 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
.\"
.\"*******************************************************************
.\"
.\" This file was generated with po4a. Translate the source file.
.\"
.\"*******************************************************************
.TH mbrtowc 3 "5 Febrero 2023" "Páginas de manual de Linux 6.03" 
.SH NOMBRE
mbrtowc \- convierte una secuencia multibyte a un carácter ancho
.SH BIBLIOTECA
Biblioteca Estándar C (\fIlibc\fP, \fI\-lc\fP)
.SH SINOPSIS
.nf
\fB#include <wchar.h>\fP
.PP
\fBsize_t mbrtowc(wchar_t *restrict \fP\fIpwc\fP\fB, const char \fP\fIs\fP\fB[restrict .\fP\fIn\fP\fB],\fP
\fB               size_t \fP\fIn\fP\fB, mbstate_t *restrict \fP\fIps\fP\fB);\fP
.fi
.SH DESCRIPCIÓN
The main case for this function is when \fIs\fP is not NULL and \fIpwc\fP is not
NULL.  In this case, the \fBmbrtowc\fP()  function inspects at most \fIn\fP bytes
of the multibyte string starting at \fIs\fP, extracts the next complete
multibyte character, converts it to a wide character and stores it at
\fI*pwc\fP.  It updates the shift state \fI*ps\fP.  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 \fIs\fP.  If the converted wide
character is L\[aq]\e0\[aq], it resets the shift state \fI*ps\fP to the initial
state and returns 0.
.PP
Si los \fIn\fP bytes que comienzan en \fIs\fP no contienen un carácter multibyte
completo, \fBmbrtowc\fP() devuelve \fI(size_t)\ \-2\fP. Esto puede ocurrir incluso
si \fIn\fP >= \fIMB_CUR_MAX\fP, si la cadena multibyte contiene secuencias de
cambios redundantes.
.PP
Si la cadena multibyte que comienza en \fIs\fP contiene una secuencia multibyte
inválida antes del siguiente carácter completo, \fBmbrtowc\fP() devuelve
\fI(size_t)\ \-1\fP y asigna a \fIerrno\fP el valor \fBEILSEQ\fP.  En este caso, los
efectos sobre \fI*ps\fP son indefinidos.
.PP
Un caso diferente se da cuando \fIs\fP no es NULL pero \fIpwc\fP es NULL. En este
caso, la función \fBmbrtowc\fP() se comporta como antes, excepto que no
almacena el carácter ancho obtenido en memoria.
.PP
Un tercer caso se da cuando \fIs\fP es NULL. En este caso, \fIpwc\fP y \fIn\fP se
ignoran. Si el estado de conversión representado por \fI*ps\fP indica una
conversión incompleta de carácteres multibyte, la función \fBmbrtowc\fP()
devuelve \fI(size_t)\ \-1\fP, asigna a \fIerrno\fP el valor \fBEILSEQ\fP, y deja
\fI*ps\fP en un estado indefinido. En otro caso, la función \fBmbrtowc\fP() coloca
\fI*ps\fP en el estado inicial y devuelve 0.
.PP
In all of the above cases, if \fIps\fP is NULL, a static anonymous state known
only to the \fBmbrtowc\fP()  function is used instead.  Otherwise, \fI*ps\fP must
be a valid \fImbstate_t\fP object.  An \fImbstate_t\fP object \fIa\fP can be
initialized to the initial state by zeroing it, for example using
.PP
.in +4n
.EX
memset(&a, 0, sizeof(a));
.EE
.in
.SH "VALOR DEVUELTO"
The \fBmbrtowc\fP()  function returns the number of bytes parsed from the
multibyte sequence starting at \fIs\fP, 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 \fI(size_t)\ \-1\fP and sets \fIerrno\fP to \fBEILSEQ\fP, if
an invalid multibyte sequence was encountered.  It returns \fI(size_t)\ \-2\fP
if it couldn't parse a complete multibyte character, meaning that \fIn\fP
should be increased.
.SH ATRIBUTOS
Para obtener una explicación de los términos usados en esta sección, véase
\fBattributes\fP(7).
.ad l
.nh
.TS
allbox;
lbx lb lb
l l l.
Interfaz	Atributo	Valor
T{
\fBmbrtowc\fP()
T}	Seguridad del hilo	MT\-Unsafe race:mbrtowc/!ps
.TE
.hy
.ad
.sp 1
.SH ESTÁNDARES
POSIX.1\-2001, POSIX.1\-2008, C99.
.SH NOTAS
El comportamiento de \fBmbrtowc\fP() depende de la categoría \fBLC_CTYPE\fP de la
localización actual.
.SH "VÉASE TAMBIÉN"
\fBmbsinit\fP(3), \fBmbsrtowcs\fP(3)
.PP
.SH TRADUCCIÓN
La traducción al español de esta página del manual fue creada por
Juan Piernas <piernas@ditec.um.es>
.
.PP
Esta traducción es documentación libre; lea la
.UR https://www.gnu.org/licenses/gpl-3.0.html
GNU General Public License Version 3
.UE
o posterior con respecto a las condiciones de copyright.
No existe NINGUNA RESPONSABILIDAD.
.PP
Si encuentra algún error en la traducción de esta página del manual, envíe un
correo electrónico a
.MT debian-l10n-spanish@lists.debian.org
.ME .