.\" Copyright (c) Bruno Haible <haible@clisp.cons.org>
.\"
.\" This is free documentation; you can redistribute it and/or
.\" modify it under the terms of the GNU General Public License as
.\" published by the Free Software Foundation; either version 2 of
.\" the License, or (at your option) any later version.
.\"
.\" 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
.\"
.\" Translated Tue Apr 25 2000 by Juan Piernas <piernas@ditec.um.es>
.\" Traducción revisada por Miguel Pérez Ibars <mpi79470@alu.um.es> el 29-marzo-2005
.\"
.TH MBRTOWC 3  "22 noviembre 2001" "GNU" "Manual del Programador de Linux"
.SH NOMBRE
mbrtowc \- convierte una secuencia multibyte a un carácter ancho
.SH SINOPSIS
.nf
.B #include <wchar.h>
.sp
.BI "size_t mbrtowc (wchar_t *" pwc ", const char *" s ", size_t " n ", mbstate_t *" ps );
.fi
.SH DESCRIPCIÓN
El principal caso para esta función se da cuando \fIs\fP no es NULL y \fIpwc\fP
no es NULL. En este caso, la función \fBmbrtowc\fP inspecciona, como mucho,
\fIn\fP bytes de la cadena multibyte que comienza en \fIs\fP, extrae el
siguiente carácter multibyte completo, lo convierte a un carácter ancho y lo
almacena en \fI*pwc\fP. La función actualiza el estado de cambios \fI*ps\fP.
Si el carácter ancho obtenido no es L'\\0', devuelve el número de bytes
que se han consumido de \fIs\fP. Si el carácter ancho obtenido es L'\\0',
restablece el estado de cambios \fI*ps\fP al estado inicial y devuelve 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 \fBerrno\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 \fBerrno\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
En todos los casos anteriores, si \fIps\fP es un puntero NULL, en su lugar se
usa un estado anónimo privado sólo conocido por la función \fBmbrtowc\fP.
En caso contrario, \fI*ps\fP debe ser un objeto \fBmbstate_t\fP válido.
Un objeto \fBmbstate_t\fP \fIa\fP puede ser incializado al estado inicial
rellenándolo con ceros, usando por ejemplo:
.sp
.RS
memset(&a, 0, sizeof(a));
.RE
.SH "VALOR DEVUELTO"
La función \fBmbrtowc\fP devuelve el número de bytes analizados de la
secuencia multibyte que comienza en \fIs\fP, si se ha reconocido un carácter
ancho distinto de L'\\0'. Devuelve 0 si se ha reconocido un carácter ancho
L'\\0'. Devuelve (size_t)(-1) y asigna a \fBerrno\fP el valor \fBEILSEQ\fP
si se ha encontrado una secuencia multibyte inválida. Devuelve (size_t)(-2)
si no se ha podido analizar un carácter multibyte completo, indicando esto
que se debería incrementar \fIn\fP.
.SH "CONFORME A"
ISO/ANSI C, UNIX98
.SH "VÉASE TAMBIÉN"
.BR mbsrtowcs (3)
.SH OBSERVACIONES
El comportamiento de \fBmbrtowc\fP depende de la categoría LC_CTYPE de la
localización actual.