printf, fprintf, sprintf, snprintf, wsprintf, vprintf, vfprintf, vsprintf, vwsprintf, ou vdprintf Subroutine

Propósito

Imprime saída formatada.

Biblioteca

Biblioteca C Padrão (libc.a) ou a Biblioteca C Padrão com duplas de 128 bits (libc128.a)

Sintaxe

#include <stdio.h>

int printf (Format, [Value, ...])
const char *Format;

int fprintf (Stream, Format, [Value, ...])
FILE *Stream;
const char *Format;

int sprintf (String, Format, [Value, ...])
char *String;
const char *Format;

int snprintf (String, Number, Format, [Value, . . .])
char *String;
int Number;
const char *Format;

#include <stdarg.h>

int vprintf (Format, Value)
const char *Format;
va_list Value;

int vfprintf (Stream, Format, Value)
FILE *Stream;
const char *Format;
va_list Value;

int vsprintf (String, Format, Value)
char *String;
const char *Format;
va_list Value;

int vdprintf (fildes, Format, Value);
int fildes;
const char *Format;
va_list Value;

#include <wchar.h>

int vwsprintf (String, Format, Value)
wchar_t *String;
const char *Format;
va_list Value;

int wsprintf (String, Format, [Value, ...])
wchar_t *String;
const char *Format;

Descrição

O subroutine printf converte, formatos e grava os valores de parâmetro Value , sob controle do parâmetro Format , para o fluxo de saída padrão. A subroutine printf fornece tipos de conversão para manipular pontos de código e códigos de caracteres de largura wchar_t .

O subroutine fprintf converte, formatos e grava os valores de parâmetro Value , sob controle do parâmetro Format , para o fluxo de saída especificado pelo parâmetro Stream . Esta subroutine fornece tipos de conversão para manipular pontos de código e códigos de caracteres de largura wchar_t .

O subroutine sprintf converte, formata e armazena os valores de parâmetro Value , sob controle do parâmetro Format , em bytes consecutivos, iniciando no endereço especificado pelo parâmetro String . A subroutina sprintf coloca um caractere nulo (\0) no final. Você deve garantir que o espaço de armazenamento suficiente esteja disponível para conter a sequência formatada. Esta subroutine fornece tipos de conversão para manipular pontos de código e códigos de caracteres de largura wchar_t .

O subroutine snprintf converte, formatos e armazena os valores de parâmetro Value , sob controle do parâmetro Format , em bytes consecutivos, iniciando no endereço especificado pelo parâmetro String . A subroutina snprintf coloca um caractere nulo (\0) no final. Você deve garantir que o espaço de armazenamento suficiente esteja disponível para conter a sequência formatada. Esta subroutine fornece tipos de conversão para manipular pontos de código e códigos de caracteres de largura wchar_t . A subroutine snprintf é idêntica à subroutina sprintf com a adição do parâmetro Number , que afirma o tamanho do buffer referido pelo parâmetro String .

O subroutine de wsprintf converte, formatos e armazena os valores de parâmetro Value , sob controle do parâmetro Format , em caracteres wchar_t consecutivos iniciando no endereço especificado pelo parâmetro String . A subroutina wsprintf coloca um caractere nulo (\0) no final. O processo de chamada deve garantir que o espaço de armazenamento suficiente esteja disponível para conter a sequência formatada. A unidade de largura de campo é especificada como o número de caracteres wchar_t . O subroutine wsprintf é o mesmo que o subroutine printf , exceto que o parâmetro String para a subroutine wsprintf usa uma string de códigos de caracteres de wchar_t de caracteres.

Todas as subroutines acima funcionam chamando a subroutine _doprnt , usando instalações de argumento de comprimento variável dos macros varargs .

Os vdprintf, vprintf, vfprintf, vsprintfe vwsprintf subroutines format e escreva listas de parâmetros de macros varargs . Estas subroutines são as mesmas do drpintf, printf, fprintf, sprintf, snprintfe subroutines de wsprintf , respectivamente, exceto que não são chamadas com um número variável de parâmetros. Em vez disso, eles são chamados com um ponteiro de lista de parâmetros conforme definido pelos macros varargs .

Parâmetros

Número

Especifica o número de bytes em uma string a ser copiada ou transformada.

Valor

Especifica 0 ou mais argumentos que mapeam diretamente para os objetos no parâmetro Format .

Fluxo

Especifica o fluxo de saída.

Sequência

Especifica o endereço inicial.

Formato

Uma sequência de caracteres que contém dois tipos de objetos:

• Caracteres simples, que são copiados para o fluxo de saída.
• Especificações de conversão, cada uma delas faz com que 0 ou mais itens sejam recuperados da lista de parâmetros Valor . No caso das subroutines vprintf, vfprintf, vsprintfe vwsprintf , cada especificação de conversão faz com que 0 ou mais itens sejam recuperados das listas de parâmetros de macros varargs .

  Se a lista de parâmetros Value não contém itens suficientes para o parâmetro Format , os resultados são imprevisíveis. Se mais parâmetros permanecem após o parâmetro de Formato inteiro ter sido processado, a subroutine ignora-os.

  Cada especificação de conversão no parâmetro Format tem os seguintes elementos:

• A% (sinal de percentual).
• 0 ou mais opções, que modificam o significado da especificação de conversão. Os caracteres de opção e seus significados são:

  '

  Formata as porções de número inteiro resultantes de i, d, u, f, g e G conversões decimais com milands_sep caracteres de agrupamento. Para outras conversões o comportamento é indefinido. Esta opção usa o caráter de agrupamento não monetário.

  -

  Esquerda-justifica o resultado da conversão dentro de campo.

  +

  Inicia-se o resultado de uma conversão assinada com um + (sinal de mais) ou-(sinal de menos).

  caractere de espaço

  Prefixa um caractere de espaço para o resultado se o primeiro caractere de uma conversão assinada não for um sinal. Se ambos os caracteres de opção de espaço-espaço e + aparecer, a opção espaço-caracteres será ignorada.

  #

  Converte o valor para um formulário alternativo. Para as conversões c, d, s, e u , a opção não tem efeito. Para a conversão o , aumenta a precisão para forçar o primeiro dígito do resultado a ser um 0. Para as conversões x e X , um resultado não zero tem um prefixo 0x ou 0X . Para as conversões e, E, f, ge G , o resultado sempre contém um ponto decimal, mesmo que nenhum algarismo o acompanhais. Para as conversões g e G , as 0's trailing's não são removidas do resultado.

  0

  Pads à largura de campo com os principais 0's (seguindo qualquer indicação de sinal ou base) para d, i, o, u, x, X, e, E, f, ge G conversões; o campo não é espaço-acolchado. Se as opções 0 e - aparecidas, a opção 0 é ignorada. Para d, i, o u, x, e X conversões, se uma precisão for especificada, a opção 0 também é ignorada. Se as opções 0 e ' aparecer, agrupar caracteres são inseridos antes que o campo seja acoleado. Para outras conversões, os resultados não são confiáveis.

  B

  Especifica um caractere sem op.

  n

  Especifica um caractere sem op.

  J

  Especifica um caractere sem op.

• Uma cadeia de dígito decimal opcional que especifica a largura do campo mínimo. Se o valor convertido tiver menos caracteres do que a largura do campo, o campo é acolado na esquerda para o comprimento especificado pela largura do campo. Se a opção - (esquerdas esquerdas) for especificada, o campo é acolado à direita.
• Uma precisão opcional. A precisão é um . (ponto) seguido de uma sequência de dígitos decimais. Se nenhuma precisão for especificada, o valor padrão é 0. A precisão especifica os seguintes limites:
  • Número mínimo de dígitos para aparecer para as conversões d, i, o, u, xou X .
  • Número de dígitos para aparecer após o ponto decimal para as conversões e, Ee f .
  • Número máximo de algaridades significativas para conversões g e G .
  • Número máximo de bytes a serem impressos a partir de uma string em conversões s e S .
  • Número máximo de bytes, convertidos da matriz wchar_t , para serem impressos a partir das conversões S . Apenas caracteres completos são impressos.
• An opcional l (lowercase L), ll (lowercase LL), hou L especificadora indica um dos seguintes:
  • Um h opcional especificando que um especificador de conversão de d, eu, u, o, xou X , aplica-se a um parâmetro curta int ou curta int unsigned Valor (o parâmetro terá sido promovido de acordo com as promoções integrais, e seu valor será convertido em um curta int ou curta int unsigned antes da impressão).
  • Um h opcional especificando que um especificador de conversão n subsequente aplica-se a um ponteiro a um parâmetro short int .
  • Um l opcional (lowercase L) especificando que um especificador de conversão d, eu, u, o, xou X , aplica-se a um parâmetro longa int ou longo int unsigned .
  • Um l opcional (lowercase L) especificando que um especificador de conversão n subsequente aplica-se a um ponteiro a um parâmetro long int .
  • Um ll opcional (lowercase LL) especificando que um d, i, u, o, xou X especificador de conversão aplica-se a um parâmetro long long int ou unsigned long long int .
  • Um ll opcional (lowercase LL) especificando que um especificador de conversão n subsequente aplica-se a um ponteiro a um parâmetro long long int .
  • Um L opcional especificando que um seguinte e, E, f, gou G especificador de conversão aplica-se a um parâmetro long double . Se vinculado a libc.a, long double será o mesmo que double (64bits). Se vinculado a libc128.a e libc.a, long double será de 128 bits
• Um especificador opcional H, Dou DD indica uma das conversões a seguir:
  • Um H opcional especificando que um seguinte especificador e, E, f, F, gou G , aplica-se a um parâmetro _Decimal32 .
  • Um D opcional especificando que um seguinte especificador e, E, f, F, gou G , aplica-se a um parâmetro _Decimal64 .
  • Um DD opcional especificando que um seguinte especificador e, E, f, F, gou G , aplica-se a um parâmetro _Decimal128 .
• Um vlopcional, lv, vh, hv ou v especificador indica uma das seguintes conversões do tipo de dados vetores:
  • Um v opcional especificando que um especificador de conversão de e, E, f, g, G, aou A , aplica-se a um parâmetro vector float . Ele consome um argumento e interpreta os dados como uma série de quatro componentes flutuantes de 4-byte pontos flutuantes.
  • Um v opcional especificando que um especificador de conversão c, d, i, u, o, xou X , aplica-se a um parâmetro vector signed char, vector unsigned charou vector bool char . Ele consome um argumento e interpreta os dados como uma série de dezesseis componentes de 1-byte.
  • Um opcional vl ou lv especificando que um especificador de conversão de d, i, u, o, xou X , aplica-se a um parâmetro vector signed int, vector unsigned intou vector bool . Ele consome um argumento e interpreta os dados como uma série de quatro componentes inteiros de 4-byte bits.
  • Um vh opcional ou hv especificando que um seguinte d, i, u, o, xou X specifier de conversão aplica-se a um parâmetro vector signed short ou vector unsigned short . Ele consome um argumento e interpreta os dados como uma série de oito componentes inteiros de 2-byte.
  • Para qualquer um dos especificadores precedentes, um caractere separador opcional pode ser especificado imediatamente precedendo o especificador de tamanho do vetor. Se nenhum separador for especificado, o separador padrão é um espaço a menos que a conversão seja c, caso em que o separador padrão é nulo. O conjunto de separadores opcionais suportados são , (vírgula), ; (ponto e vírgula), : (dois colon) e _ (sublinhado).
• Os caracteres a seguir indicam o tipo de conversão a ser aplicada:

  %

  Não executa nenhuma conversão. Imprime (%).

  d ou i

  Aceita um parâmetro Value especificando um número inteiro e converte-o para notação decimal assinada. A precisão especifica o número mínimo de digitos a aparecer. Se o valor que está sendo convertido pode ser representado em menos dígitos, ele é expandido com os principais 0's. A precisão padrão é 1. O resultado da conversão de um valor de 0 com uma precisão de 0 é uma sequência nula. Especificar uma largura de campo com um 0 como um caractere de liderança faz com que o valor de largura de campo seja preenchida com os 0 principais's.

  u

  Aceita um parâmetro Value especificando um inteiro não assinado e converte-o para notação decimal não assinada. A precisão especifica o número mínimo de digitos a aparecer. Se o valor que está sendo convertido pode ser representado em menos dígitos, ele é expandido com os principais 0's. A precisão padrão é 1. O resultado da conversão de um valor de 0 com uma precisão de 0 é uma sequência nula. Especificar uma largura de campo com um 0 como um caractere de liderança faz com que o valor de largura de campo seja preenchida com os 0 principais's.

  o

  Aceita um parâmetro Value especificando um inteiro não assinado e converte-o em notação octal não assinada. A precisão especifica o número mínimo de digitos a aparecer. Se o valor que está sendo convertido pode ser representado em menos dígitos, ele é expandido com os principais 0's. A precisão padrão é 1. O resultado da conversão de um valor de 0 com uma precisão de 0 é uma sequência nula. Especificar um campo-largura com um 0 como um caractere de liderança faz com que o valor da largura do campo seja preenchida com os 0 principais's. Um valor octal para largura de campo não está implícito.

  x ou X

  Aceita um parâmetro Value especificando um inteiro não assinado e converte-o para notação hexadecimal não assinada. As letras abcdef são usadas para a conversão x e as letras ABCDEF são usadas para a conversão X . A precisão especifica o número mínimo de digitos a aparecer. Se o valor que está sendo convertido pode ser representado em menos dígitos, ele é expandido com os principais 0's. A precisão padrão é 1. O resultado da conversão de um valor de 0 com uma precisão de 0 é uma sequência nula. Especificar uma largura de campo com um 0 como um caractere de liderança faz com que o valor de largura de campo seja preenchida com os 0 principais's.

  f

  Aceita um parâmetro Value especificando uma dupla e converte-a em notação decimal no formato [-]ddd.ddd. O número de algaritos após o ponto decimal é igual à especificação de precisão. Se nenhuma precisão for especificada, seis algarías são saída. Se a precisão for 0, nenhum ponto decimal aparece.

  e ou E

  Aceita um parâmetro Value especificando um duplo e o converte no formato exponencial [-]d.ddde+/-dd. Um dígito existe antes do ponto decimal, e o número de algarismos após o ponto decimal é igual à especificação de precisão. A especificação de precisão pode estar na faixa de 0-17 dígitos. Se nenhuma precisão for especificada, seis algarías são saída. Se a precisão for 0, nenhum ponto decimal aparece. O caractere de conversão E produz um número com E em vez de e antes do expoente. O expoente sempre contém pelo menos dois algaríos.

  g ou G

  Aceita um parâmetro Value especificando uma dupla e converte-a no estilo dos caracteres de conversão e, Eou f , com a precisão especificando o número de dígitos significativos. Trailing 0's são removidos do resultado. Um ponto decimal aparece apenas se for seguido por um dígito. O estilo usado depende do valor convertido. O estilo e (E, se G for o sinalizador usado) resulta somente se o expoente resultante da conversão for menor que -4, ou se for maior ou igual à precisão. Se uma precisão explícita for 0, ela é tomada como 1.

  c

  Aceita e imprime um parâmetro Value especificando um inteiro convertido para um tipo de dados unsigned char .

  C

  Aceita e imprime um parâmetro Value especificando um código de caracteres amplo wchar_t . O código de caracteres amplo wchar_t especificado pelo parâmetro Value é convertido em uma matriz de bytes representando um caractere e esse caractere é escrito; o parâmetro Value é escrito sem conversão ao usar a subroutina wsprintf .

  s

  Aceita um parâmetro Value como uma string (pointer de caracteres), e caracteres da string são impressos até que um caractere nulo (\0) seja encontrado ou o número de bytes indicados pela precisão seja atingido. Se nenhuma precisão for especificada, todos os bytes até o primeiro caractere nulo são impressos. Se o ponteiro string especificado pelo parâmetro Value tiver um valor nulo, os resultados não são confiáveis.

  S

  Aceita um parâmetro Value correspondente como um ponteiro para uma string wchar_t . Caracteres da sequência são impressos (sem conversão) até que um caractere nulo (\0) seja encontrado ou o número de caracteres amplos indicado pela precisão seja atingido. Se nenhuma precisão for especificada, todos os caracteres até o primeiro caractere nulo são impressos. Se o ponteiro string especificado pelo parâmetro Value tiver um valor de null, os resultados não são confiáveis.

  P

  Aceita um ponteiro para anular. O valor do ponteiro é convertido para uma sequência de caracteres imprimíveis, o mesmo que um hexadecimal não assinado (x).

  n

  Aceita um ponteiro para um inteiro no qual está escrito o número de caracteres (códigos de caracteres amplos no caso da subroutine de wsprintf ) gravado no fluxo de saída por esta chamada. Nenhum argumento é convertido.

 

Uma largura de campo ou precisão pode ser indicada por um * (asterisco) em vez de uma sequência de algarismos. Neste caso, um parâmetro Value inteiro fornece a largura de campo ou precisão. O parâmetro Valor convertido para saída não é recuperado até que a letra de conversão seja atingida, portanto, os parâmetros especificando largura de campo ou precisão devem aparecer antes do valor (se houver) a ser convertido.

Se o resultado de uma conversão for mais largo que a largura do campo, o campo será expandido para conter o resultado convertido e não ocorrerá o truncamento. No entanto, uma pequena largura de campo ou precisão pode causar truncamento à direita.

O printf, fprintf, sprintf, snprintf, wsprintf, vprintf, vfprintf, vsprintfou vwsprintf subroutine permite a inserção de um caractere de radix dependente de linguagem na cadeia de saída. O caractere radix é definido por dados específicos da linguagem na categoria LC_NUMÉRICA do locale do programa. No locale C, ou em um locale onde o caractere radix não é definido, o caractere de radix padronizado para um. (ponto).

Depois que qualquer uma dessas subroutines for executada com sucesso, e antes da próxima conclusão bem-sucedida de uma chamada para a subroutine fclose ou fflush no mesmo fluxo ou para a subroutine exit ou abort , ost_ctimeest_mtimeos campos do arquivo estão marcados para atualização.

Os especificadores de conversão e, E, f, ge G representam os valores especiais de ponto flutuante da seguinte forma:

A representação do + (sinal de mais) depende de se a opção de formatação de caracteres + ou espaço-de-caracteres é especificada.

Estas subroutines podem manipular uma string de formato que possibilita que o sistema processe elementos da lista de parâmetros em ordem variável. Em tal caso, o caractere de conversão normal% (sinal de percentual) é substituído por %dígito$, em que dígito é um número decimal na faixa a partir de 1 para o valor NL_ARGMAX . A conversão é então aplicada ao argumento especificado, em vez de para o próximo argumento não utilizado. Este recurso prevê a definição de strings de formato em uma ordem apropriada para linguagens específicas. Quando a ordenação de variáveis é usada a especificação * (asterisco) para largura de campo em precisão é substituída por %dígito$. Se você usar o recurso de ordenação de variáveis, você deve especificá-lo para todas as conversões.

Aplicam-se os seguintes critérios:

• O formato passado para as extensões NLS pode conter o formato da conversão ou o número de argumento explícito ou implícito. No entanto, esses formulários não podem ser misturados dentro de uma única string de formato, exceto para %% (sinal de percentual duplo).
• O valor n não deve ter zeros iniciais.
• Se %n$ for usado, %1$ para %n- 1$ inclusivo deve ser usado.
• O n em %n$ está na faixa a partir de 1 para o valor NL_ARGMAX , inclusive. Consulte o arquivo limits.h para obter mais informações sobre o valor NL_ARGMAX .
• Argumentos numerados na lista de argumentos podem ser referenciados quantas vezes for necessário.
• A especificação * (asterisco) para largura de campo ou precisão não é permitida com a ordem variável %n$ formato; em vez disso, é usado o formato *m$ .

Valores De Retorno

Após a conclusão bem-sucedida, as subroutines printf, fprintf, vprintfe vfprintf retornam o número de bytes transmitidos (não incluindo o caractere nulo [\0] no caso das subroutines sprintfe vsprintf ). Se um erro foi encontrado, um valor negativo é saída.

Após a conclusão bem-sucedida, a subroutina snprintf retorna o número de bytes gravados no parâmetro String (excluindo o byte null terminante). Se os caracteres de saída forem descartados porque a saída excedeu o parâmetro Número no comprimento, então a subroutina snprintf retorna o número de bytes que teria sido gravado no parâmetro String se o parâmetro Número tivesse sido grande o suficiente (excluindo o byte null terminating).

Após a conclusão bem-sucedida, as subroutines wsprintf e vwsprintf retornam o número de caracteres amplos transmitidos (não incluindo o caractere nulo de caracteres amplos [\0]). Se um erro foi encontrado, um valor negativo é saída.

Códigos De Erro

O printf, fprintf, sprintf, snprintf, ou wsprintf subroutine não é bem sucedido se o arquivo especificado pelo parâmetro Stream estiver sem buffer ou o buffer precisa ser flushed e um ou mais dos seguintes são verdadeiros:

O printf, fprintf, sprintf, snprintfou wsprintf subroutine pode não ser bem sucedido se um ou mais dos seguintes forem verdadeiros:

Exemplos

O exemplo a seguir demonstra como a subroutine vfprintf pode ser usada para escrever uma rotina de erro:

#include <stdio.h>
#include <stdarg.h>
/* The error routine should be called with the
     syntax:       */
/* error(routine_name, Format
     [, value, . . . ]); */
/*VARARGS0*/
void error(char *fmt, . . .);
/* **  Note that the function name and
     Format arguments cannot be **
     separately declared because of the **
     definition of varargs.  */  {
   va_list args;

   va_start(args, fmt);
   /*
   ** Display the name of the function
      that called the error routine   */
   fprintf(stderr, "ERROR in %s: ",
      va_arg(args, char *));   /*
   ** Display the remainder of the message
   */
   fmt = va_arg(args, char *);
   vfprintf(fmt, args);
   va_end(args);
    abort();  }