.\" 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 into Spanish Tue Mar  3 15:28:21 CET 1998 by Gerardo
.\" Aburruzaga García <gerardo.aburruzaga@uca.es>
.\" Translation revised Sun Aug  6 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 MBTOWC 3  "4 julio 2001" "GNU" "Manual del Programador de Linux"
.SH NOMBRE
mbtowc \- convierte una secuencia multibyte en un carácter ancho
.SH SINOPSIS
.nf
.B #include <stdlib.h>
.sp
.BI "int mbtowc (wchar_t *" pwc ", const char *" s ", size_t " n );
.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 \fBmbtowc\fP inspecciona,
como mucho, \fIn\fP bytes de la cadena multibyte \fIs\fP, extrae el
siguiente carácter multibyte completo, lo convierte a un carácter ancho y lo
almacena en \fI*pwc\fP. Actualiza un estado de cambios interno sólo conocido
por la función mbtowc. Si \fIs\fP no apunta aun byte '\\0', la función
devuelve el número de bytes consumidos de \fIs\fP. En otro caso, devuelve 0.
.PP
Si los primeros \fIn\fP bytes de \fIs\fP no contienen un carácter multibyte
completo, o si contiene una secuencia multibyte inválida, \fBmbtowc\fP
devuelve \fI-1\fP. Esto puede ocurrir incluso sif \fIn\fP >= \fIMB_CUR_MAX\fP,
si la cadena multibyte contiene secuencias de cambios redundantes.
.PP
Un caso diferente se da cuando \fIs\fP no es NULL pero \fIpwc\fP sí lo es.
En este caso, la función \fBmbtowc\fP se comporta como antes pero 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. La función \fBmbtowc\fP
.\" The Dinkumware doc and the Single Unix specification say this, but
.\" glibc doesn't implement this.
devuelve el estado de cambios, sólo conocido por esta función, a su estado
inicial y devuelve un valor distinto de cero si la condificación posee un
estado de cambios no trivial o cero si es una codificación sin estado.
.SH "VALOR DEVUELTO"
Si \fIs\fP no es NULL, la función \fBmbtowc\fP devuelve el número de bytes
consumidos de \fIs\fP, 0 si \fIs\fP apunta a un byte nulo o \-1 en caso de
fallo.
.PP
Si \fIs\fP es NULL, la función \fBmbtowc\fP devuelve un valor distinto de
cero si la codificación posee un estado de cambios no trivial o cero si es
una codificación sin estado.
.SH "CONFORME A"
ISO/ANSI C, UNIX98
.SH "VÉASE TAMBIÉN"
.BR mbrtowc "(3), " mbstowcs "(3), " MB_CUR_MAX (3)
.SH OBSERVACIONES
El comportamiento de \fBmbtowc\fP depende de la categoría LC_CTYPE de la
localización actual.
.PP
Esta función no es segura en un entorno multihilos. La función \fBmbrtowc\fP
proporciona una interfaz mejor con la misma funcionalidad.