Provided by: manpages-pt-br-dev_4.21.0-2_all 
NOME
mbstowcs - converte uma string multibyte para uma string de caracteres largos
BIBLIOTECA
Biblioteca C Padrão (libc, -lc)
SINOPSE
#include <stdlib.h>
size_t mbstowcs(wchar_t dest[restrict .n], const char *restrict src,
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:
• Uma sequência multibyte inválida foi encontrada. Neste caso, (size_t) -1 é retornado.
• n non-L'\0' wide characters have been stored at dest. In this case, the number of wide characters
written to dest is returned, but the shift state at this point is lost.
• The multibyte string has been completely converted, including the terminating null character ('\0').
In this case, the number of wide characters written to dest, excluding the terminating null wide
character, is returned.
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 │
└─────────────────────────────────────────────────────────────────────────────┴───────────────┴─────────┘
PADRÕES
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 <locale.h>
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <wchar.h>
#include <wctype.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);
/* Allocate wide character string of the desired size. Add 1
to allow for terminating null wide character (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)
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.
Linux man-pages 6.03 5 fevereiro 2023 mbstowcs(3)