Provided by: manpages-pt-br-dev_4.18.1-1_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
⟨https://www.gnu.org/licenses/gpl-3.0.html⟩ 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 ⟨debian-l10n-portuguese@lists.debian.org⟩.