WPRINTF(3)

NOME
wprintf, fwprintf, swprintf, vwprintf, vfwprintf, vswprintf - conversão de saída formatada de caracteres largos

SINÓPSE
#include <stdio.h>
#include <wchar.h>

int wprintf (const wchar_t* format, ...);
int fwprintf (FILE* stream, const wchar_t* format, ...);
int swprintf (wchar_t* wcs, size_t maxlen,
              const wchar_t* format, ...);

#include <stdarg.h>

int vwprintf (const wchar_t* format, va_list args);
int vfwprintf (FILE* stream, const wchar_t* format, va_list args);
int vswprintf (wchar_t* wcs, size_t maxlen,
               const wchar_t* format, va_list args);

DESCRIÇÃO
A família de funções wprintf é a equivalente para caracteres largos à família de funções printf. Ela realiza a saída formatada de caracteres largos.

As funções wprintf e vwprintf realizam saída de caracteres largos para stdout. stdout não deve ser orientado a byte; veja a função fwide para maiores informações.

As funções fwprintf e vfwprintf realizam saída de caracteres largos para stream. stream não deve ser orientada a byte; veja função fwide para maiores informações.

As funções swprintf e vswprintf realizam saída de caracteres largos para um array de caracteres largos. O programador deve garantir que há espaço suficiente para no mínimo maxlen caracteres largos em wcs.

Estas funções são como as funções printf, vprintf, fprintf, vfprintf, sprintf, vsprintf exceto pelas seguintes diferenças:

•   A format é uma seqüencia de caracteres largos.

•   A saída consiste de caracteres largos, não bytes.

•   swprintf e vswprintf recebem um argumento maxlen, sprintf e vsprintf não recebem. (snprintf e vsnprintf recebem um argumento maxlen, mas estas funções não retornam -1 quando ocorre um estouro de 'buffer' no GNU/Linux.)

O tratamento de caracteres de conversão c e s é diferente:

c   Se nenhum modificador l está presente, o argumento int é convertido para um caractere largo por uma chamada a para a função btowc, e o caractere largo resultante é escrito. Se um modificador l está presente, o argumento wint_t (caractere largo) é escrito.

s   Se nenhum modificador l está presente: O argumento 'const char *' é esperado como um ponteiro para um tipo de array de caracteres (ponteiro para uma seqüencia) contendo uma seqüência de caracteres multibyte começando no estado de transição inicial. Caracteres do array são convertidos para caracteres largos (cada um por uma chamada à função mbrtowc com um estado de conversão iniciando no estado inicial antes do primeiro byte). Os caracteres largos resultantes são escritos até (mas não incluindo) o caractere largo terminador nulo. Se uma precisão é especificado, nenhum caractere largo a mais que o número especificado é escrito. Note que a precisão determina o número de wide characters escritos, não o número de bytes ou posições de tela. O array deve conter um byte terminador nulo, a não ser que a precisão seja dada e ela seja tão pequena que o número de caracteres largos convertidos a alcance antes que o fim do array seja alcançado. -- Se um modificador l está presente: O argumento 'const wchar_t *' é esperado como um ponteiro para um array de caracteres largos. Caracteres largos do array são escritos até (mas não incluindo) um caractere largo terminador nulo. Se uma precisão é especificada, nenhum caractere largo a mais do que o número especifica é escrito. O array deve conter um caractere largo terminador nulo, a não ser que a precisão seja dada e ela seja menor ou igual ao número de caracteres largos no array.

VALORES RETORNADOS
As funções retornam o número de caracteres largos escritos, excluindo-se o caractere largo terminador nulo no caso das funções swprintf e vswprintf. Elas retornam -1 quando ocorre um erro.

DE ACORDO COM
ISO/ANSI C, UNIX98.

VEJA TAMBÉM
printf(3), fprintf(3), snprintf(3), fputwc(3), fwide(3), wscanf(3).

NOTAS
O comportamento de wprintf etc. depende da categoria LC_CTYPE da localização atual.

Se a seqüencia format contém caracteres largos não-ASCII, o programa funcionará corretamente apenas se a categoria LC_CTYPE da localização atual em tempo de execução for a mesma que a categoria LC_CTYPE da localização atual em tempo de compilação. Isto é porque a representação wchar_t é dependente de plataforma e da localização. (A GNU libc representa caracteres largos usando seu ponto de código Unicode (ISO-10646), mas outras plataformas não o fazem. Ademais, o uso de nomes de caracteres universais ISO C99 da forma \unnnn não resolve este problema.) Portanto, em programas internacionalizados, a seqüencia format deve consistir apenas de caracteres largos ASCII, ou deve ser construído em tempo de execução de forma internacionalizada (ou seja, usando gettext ou iconv, seguido de mbstowcs).

TRADUZIDO POR LDP-BR em 28/05/2001.

  Tradução:
Felipe M Pereira <Felipe.Pereira@ic.unicamp.br>

  Revisão.:
Ricardo C.O.Freitas <english.quest@best-service.com>