Provided by: manpages-pt-br-dev_4.13-4_all 
NOME
mbstowcs - converte uma string multibyte para uma string de caracteres largos
SINOPSE
#include <stdlib.h>
size_t mbstowcs(wchar_t *dest, const char *orig, size_t n);
DESCRIÇÃO
Se dest não é um ponteiro NULO, a função mbstowcs() converte a string multibyte orig para uma string de
caracteres largos iniciando em dest. No máximo n caracteres largos são gravados em dest. A sequência de
caracteres na string orig deve começar no estado de transição inicial. A conversão começa no estado
inicial. A conversão pode parar por três razões:
1. Uma sequência multibyte inválida foi encontrada. Neste caso, (size_t) -1 é retornado.
2. n caracteres largos diferentes de L'\0' foram gravados em dest. Neste caso o número de caracteres
largos gravados em dest é retornado, mas o estado de transição neste ponto é perdido.
3. A string multibyte foi completamente convertida, incluindo o caractere nulo de terminação ('\0').
Neste caso o número de caracteres largos gravados em dest, excluindo o caractere nulo de terminação, é
retornado.
O programador deve assegurar que há espaço para pelo menos n caracteres largos em dest.
Se dest é NULO, n é ignorado, e a conversão prossegue como acima, exceto que os caracteres largos
convertidos não são gravados na memória, e que não há limite de tamanho.
A fim de evitar o caso 2 acima, o programador deve garantir que n seja maior ou igual a
mbstowcs(NULL,src,0)+1.
VALOR DE RETORNO
A função mbstowcs() retorna o número de caracteres largos que perfazem a parte convertida da string de
caracteres largos, não incluindo o caractere largo nulo de terminação. Se uma sequência multibyte
inválida foi encontrada, (size_t) -1 é retornado.
ATRIBUTOS
Para uma explicação dos termos usados nesta seção, consulte attributes(7).
┌────────────┬───────────────┬─────────┐
│ Interface │ Atributo │ Valor │
├────────────┼───────────────┼─────────┤
│ mbstowcs() │ Thread safety │ MT-Safe │
└────────────┴───────────────┴─────────┘
DE ACORDO COM
POSIX.1-2001, POSIX.1-2008, C99.
NOTAS
O comportamento de mbstowcs() depende da categoria LC_CTYPE da localidade atual.
A função mbsrtowcs() fornece uma interface melhor para a mesma funcionalidade.
EXEMPLOS
O programa abaixo ilustra o uso de mbstowcs(), bem como algumas das funções de classificação de
caracteres largos. Um exemplo de execução é o seguinte:
$ ./t_mbstowcs de_DE.UTF-8 Grüße!
Length of source string (excluding terminator):
8 bytes
6 multibyte characters
Wide character string is: Grüße! (6 characters)
G alpha upper
r alpha lower
ü alpha lower
ß alpha lower
e alpha lower
! !alpha
Fonte do programa
#include <wctype.h>
#include <locale.h>
#include <wchar.h>
#include <stdio.h>
#include <string.h>
#include <stdlib.h>
int
main(int argc, char *argv[])
{
size_t mbslen; /* Número de caracteres multibyte no fonte */
wchar_t *wcs; /* Ponteiro para string de caracteres largos convertida */
if (argc < 3) {
fprintf(stderr, "Usage: %s <locale> <string>\n", argv[0]);
exit(EXIT_FAILURE);
}
/* Aplica a localidade especificada */
if (setlocale(LC_ALL, argv[1]) == NULL) {
perror("setlocale");
exit(EXIT_FAILURE);
}
/* Calcula o tamanho necessário para manter argv[2] convertido
para uma string da caracteres largos */
mbslen = mbstowcs(NULL, argv[2], 0);
if (mbslen == (size_t) -1) {
perror("mbstowcs");
exit(EXIT_FAILURE);
}
/* Descreve a string fonte para o usuário */
printf("Length of source string (excluding terminator):\n");
printf(" %zu bytes\n", strlen(argv[2]));
printf(" %zu multibyte characters\n\n", mbslen);
/* Aloca uma string de caracteres largos do tamanho desejado.
Adicione 1 para permitir caractere largo nulo de terminação
(L'\0'). */
wcs = calloc(mbslen + 1, sizeof(*wcs));
if (wcs == NULL) {
perror("calloc");
exit(EXIT_FAILURE);
}
/* Converte uma string da caracteres multibyte em argv[2]
para uma string de caracteres largos */
if (mbstowcs(wcs, argv[2], mbslen + 1) == (size_t) -1) {
perror("mbstowcs");
exit(EXIT_FAILURE);
}
printf("Wide character string is: %ls (%zu characters)\n",
wcs, mbslen);
/* Agora faz uma inspeção da classe de caracteres na string
de caracteres largos */
for (wchar_t *wp = wcs; *wp != 0; wp++) {
printf(" %lc ", (wint_t) *wp);
if (!iswalpha(*wp))
printf("!");
printf("alpha ");
if (iswalpha(*wp)) {
if (iswupper(*wp))
printf("upper ");
if (iswlower(*wp))
printf("lower ");
}
putchar('\n');
}
exit(EXIT_SUCCESS);
}
VEJA TAMBÉM
mblen(3), mbsrtowcs(3), mbtowc(3), wcstombs(3), wctomb(3)
COLOFÃO
Esta página faz parte da versão 5.10 do projeto Linux man-pages. Uma descrição do projeto, informações
sobre relatórios de bugs e a versão mais recente desta página podem ser encontradas em
https://www.kernel.org/doc/man-pages/.
TRADUÇÃO
A tradução para português brasileiro desta página man foi criada por Felipe M Pereira
<Felipe.Pereira@ic.unicamp.br>, André Luiz Fassone <lonely_wolf@ig.com.br> e Rafael Fontenelle
<rafaelff@gnome.org>.
Esta tradução é uma documentação livre; leia a Licença Pública Geral GNU Versão 3 ou posterior para as
condições de direitos autorais. Nenhuma responsabilidade é aceita.
Se você encontrar algum erro na tradução desta página de manual, envie um e-mail para a lista de
discussão de tradutores.
GNU 1 novembro 2020 MBSTOWCS(3)