.\" -*- coding: UTF-8 -*- '\" t .\" Copyright (c) Bruno Haible .\" and Copyright 2014 Michael Kerrisk .\" .\" SPDX-License-Identifier: GPL-2.0-or-later .\" .\" 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 .\" .\"******************************************************************* .\" .\" This file was generated with po4a. Translate the source file. .\" .\"******************************************************************* .TH mbstowcs 3 "20 julho 2023" "Linux man\-pages 6.05.01" .SH NOME mbstowcs \- converte uma string multibyte para uma string de caracteres largos .SH BIBLIOTECA Biblioteca C Padrão (\fIlibc\fP, \fI\-lc\fP) .SH SINOPSE .nf \fB#include \fP .PP \fBsize_t mbstowcs(wchar_t \fP\fIdest\fP\fB[restrict .\fP\fIn\fP\fB], const char *restrict \fP\fIsrc\fP\fB,\fP \fB size_t \fP\fIn\fP\fB);\fP .fi .SH DESCRIÇÃO Se \fIdest\fP não é um ponteiro NULO, a função \fBmbstowcs\fP() converte a string multibyte \fIorig\fP para uma string de caracteres largos iniciando em \fIdest\fP. No máximo \fIn\fP caracteres largos são gravados em \fIdest\fP. A sequência de caracteres na string \fIorig\fP 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: .IP \[bu] 3 Uma sequência multibyte inválida foi encontrada. Neste caso, \fI(size_t)\ \-1\fP é retornado. .IP \[bu] \fIn\fP non\-L\[aq]\e0\[aq] wide characters have been stored at \fIdest\fP. In this case, the number of wide characters written to \fIdest\fP is returned, but the shift state at this point is lost. .IP \[bu] The multibyte string has been completely converted, including the terminating null character (\[aq]\e0\[aq]). In this case, the number of wide characters written to \fIdest\fP, excluding the terminating null wide character, is returned. .PP O programador deve assegurar que há espaço para pelo menos \fIn\fP caracteres largos em \fIdest\fP. .PP Se \fIdest\fP é NULO, \fIn\fP é 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. .PP A fim de evitar o caso 2 acima, o programador deve garantir que \fIn\fP seja maior ou igual a \fImbstowcs(NULL,src,0)+1\fP. .SH "VALOR DE RETORNO" A função \fBmbstowcs\fP() 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, \fI(size_t)\ \-1\fP é retornado. .SH ATRIBUTOS Para uma explicação dos termos usados nesta seção, consulte \fBattributes\fP(7). .TS allbox; lbx lb lb l l l. Interface Atributo Valor T{ .na .nh \fBmbstowcs\fP() T} Thread safety MT\-Safe .TE .sp 1 .SH VERSÕES A função \fBmbsrtowcs\fP() fornece uma interface melhor para a mesma funcionalidade. .SH PADRÕES C11, POSIX.1\-2008. .SH HISTÓRICO POSIX.1\-2001, C99. .SH NOTAS O comportamento de \fBmbstowcs\fP() depende da categoria \fBLC_CTYPE\fP da localidade atual. .SH EXEMPLOS O programa abaixo ilustra o uso de \fBmbstowcs\fP(), bem como algumas das funções de classificação de caracteres largos. Um exemplo de execução é o seguinte: .PP .in +4n .EX $ ./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 .EE .in .SS "Fonte do programa" .\" SRC BEGIN (mbstowcs.c) \& .EX #include #include #include #include #include #include \& int main(int argc, char *argv[]) { size_t mbslen; /* Number of multibyte characters in source */ wchar_t *wcs; /* Pointer to converted wide character string */ \& if (argc < 3) { fprintf(stderr, "Usage: %s \en", argv[0]); exit(EXIT_FAILURE); } \& /* Apply the specified locale. */ \& if (setlocale(LC_ALL, argv[1]) == NULL) { perror("setlocale"); exit(EXIT_FAILURE); } \& /* Calculate the length required to hold argv[2] converted to a wide character string. */ \& mbslen = mbstowcs(NULL, argv[2], 0); if (mbslen == (size_t) \-1) { perror("mbstowcs"); exit(EXIT_FAILURE); } \& /* Describe the source string to the user. */ \& printf("Length of source string (excluding terminator):\en"); printf(" %zu bytes\en", strlen(argv[2])); printf(" %zu multibyte characters\en\en", mbslen); \& /* Allocate wide character string of the desired size. Add 1 to allow for terminating null wide character (L\[aq]\e0\[aq]). */ \& wcs = calloc(mbslen + 1, sizeof(*wcs)); if (wcs == NULL) { perror("calloc"); exit(EXIT_FAILURE); } \& /* Convert the multibyte character string in argv[2] to a wide character string. */ \& if (mbstowcs(wcs, argv[2], mbslen + 1) == (size_t) \-1) { perror("mbstowcs"); exit(EXIT_FAILURE); } \& printf("Wide character string is: %ls (%zu characters)\en", wcs, mbslen); \& /* Now do some inspection of the classes of the characters in the wide character string. */ \& 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(\[aq]\en\[aq]); } \& exit(EXIT_SUCCESS); } .EE .\" SRC END .SH "VEJA TAMBÉM" \fBmblen\fP(3), \fBmbsrtowcs\fP(3), \fBmbtowc\fP(3), \fBwcstombs\fP(3), \fBwctomb\fP(3) .PP .SH TRADUÇÃO A tradução para português brasileiro desta página man foi criada por Felipe M Pereira , André Luiz Fassone e Rafael Fontenelle . . .PP Esta tradução é uma documentação livre; leia a .UR https://www.gnu.org/licenses/gpl-3.0.html Licença Pública Geral GNU Versão 3 .UE ou posterior para as condições de direitos autorais. Nenhuma responsabilidade é aceita. .PP Se você encontrar algum erro na tradução desta página de manual, envie um e-mail para .MT debian-l10n-portuguese@lists.debian.org a lista de discussão de tradutores .ME .