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

Finalidad

Imprime la salida formateada.

Biblioteca

Biblioteca C estándar (libc.a) o Biblioteca C estándar con dobles largos de 128 bits (libc128.a)

Sintaxis

#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;

Descripción

La subrutina printf convierte, formatea y escribe los valores del parámetro Valor , bajo el control del parámetro Formato , en la corriente de salida estándar. La subrutina printf proporciona tipos de conversión para manejar elementos de código y códigos de caracteres de ancho wchar_t .

La subrutina fprintf convierte, formatea y escribe los valores del parámetro Valor , bajo control del parámetro Formato , en la corriente de salida especificada por el parámetro Corriente . Esta subrutina proporciona tipos de conversión para manejar elementos de código y códigos de caracteres anchos wchar_t .

La subrutina sprintf convierte, formatea y almacena los valores del parámetro Valor , bajo control del parámetro Formato , en bytes consecutivos, empezando por la dirección especificada por el parámetro Serie . La subrutina sprintf coloca un carácter nulo (\0) al final. Debe asegurarse de que haya suficiente espacio de almacenamiento disponible para contener la serie formateada. Esta subrutina proporciona tipos de conversión para manejar elementos de código y códigos de caracteres anchos wchar_t .

La subrutina snprintf convierte, formatea y almacena los valores del parámetro Valor , bajo control del parámetro Formato , en bytes consecutivos, empezando por la dirección especificada por el parámetro Serie . La subrutina snprintf coloca un carácter nulo (\0) al final. Debe asegurarse de que haya suficiente espacio de almacenamiento disponible para contener la serie formateada. Esta subrutina proporciona tipos de conversión para manejar elementos de código y códigos de caracteres anchos wchar_t . La subrutina snprintf es idéntica a la subrutina sprintf con la adición del parámetro Número , que indica el tamaño del almacenamiento intermedio al que hace referencia el parámetro Serie .

La subrutina wsprintf convierte, formatea y almacena los valores del parámetro Valor , bajo el control del parámetro Formato , en caracteres wchar_t consecutivos a partir de la dirección especificada por el parámetro Serie . La subrutina wsprintf coloca un carácter nulo (\0) al final. El proceso de llamada debe asegurarse de que haya suficiente espacio de almacenamiento disponible para contener la serie formateada. La unidad de ancho de campo se especifica como el número de caracteres wchar_t . La subrutina wsprintf es la misma que la subrutina printf , excepto que el parámetro Serie para la subrutina wsprintf utiliza una serie de códigos de caracteres anchos wchar_t .

Todas las subrutinas anteriores funcionan llamando a la subrutina _doprnt , utilizando recursos de argumentos de longitud variable de las macros varargs .

Las subrutinas vdprintf, vprintf, vfprintf, vsprintfy vwsprintf formatean y escriben listas de parámetros de macros varargs . Estas subrutinas son las mismas que las subrutinas drpintf, printf, fprintf, sprintf, snprintfy wsprintf , respectivamente, excepto que no se llaman con un número variable de parámetros. En su lugar, se llaman con un puntero de lista de parámetros tal como lo definen las macros varargs .

Parámetros

Número

Especifica el número de bytes de una serie que se va a copiar o transformar.

VALOR

Especifica 0 o más argumentos que se correlacionan directamente con los objetos en el parámetro Formato .

Flujo

Especifica la corriente de salida.

serie

Especifica la dirección inicial.

Formato

Serie de caracteres que contiene dos tipos de objetos:

• Caracteres sin formato, que se copian en la corriente de salida.
• Especificaciones de conversión, cada una de las cuales hace que se recuperen 0 o más elementos de la lista de parámetros Valor . En el caso de las subrutinas vprintf, vfprintf, vsprintfy vwsprintf , cada especificación de conversión hace que se recuperen 0 o más elementos de las listas de parámetros de macros varargs .

  Si la lista de parámetros Valor no contiene suficientes elementos para el parámetro Formato , los resultados son imprevisibles. Si quedan más parámetros después de que se haya procesado todo el parámetro Format , la subrutina los ignora.

  Cada especificación de conversión del parámetro Formato tiene los elementos siguientes:

• Un% (signo de porcentaje).
• 0 o más opciones, que modifican el significado de la especificación de conversión. Los caracteres de opción y sus significados son:

  '

  Formatea las partes enteras resultantes de las conversiones decimales i, d, u, f, g y G con caracteres de agrupación thousands_sep . Para otras conversiones, el comportamiento no está definido. Esta opción utiliza el carácter de agrupación no monetaria.

  -

  Justifica a la izquierda el resultado de la conversión dentro del campo.

  +

  Empieza el resultado de una conversión con signo con un signo + (signo más) o-(signo menos).

  carácter de espacio

  Prefija un carácter de espacio al resultado si el primer carácter de una conversión firmada no es un signo. Si aparecen el carácter de espacio y los caracteres de opción + , se ignora la opción de carácter de espacio.

  #

  Convierte el valor en un formato alternativo. Para las conversiones c, d, sy u , la opción no tiene ningún efecto. Para la conversión o , aumenta la precisión para forzar que el primer dígito del resultado sea un 0. Para las conversiones x y X , un resultado distinto de cero tiene un prefijo 0x o 0X . Para las conversiones e, E, f, gy G , el resultado siempre contiene una coma decimal, aunque no le siga ningún dígito. Para las conversiones g y G , los 0 finales no se eliminan del resultado.

  0

  Rellena la anchura del campo con 0 iniciales (después de cualquier indicación de signo o base) para las conversiones d, i, o, u, x, X, e, E, f, gy G ; el campo no se rellena con espacios. Si aparecen las opciones 0 y - , se ignora la opción 0 . Para las conversiones d, i, o u, xy X , si se especifica una precisión, la opción 0 también se ignora. Si aparecen las opciones 0 y ' , los caracteres de agrupación se insertan antes de rellenar el campo. Para otras conversiones, los resultados no son fiables.

  B

  Especifica un carácter sin operación.

  N

  Especifica un carácter sin operación.

  J

  Especifica un carácter sin operación.

• Serie de dígito decimal opcional que especifica el ancho mínimo del campo. Si el valor convertido tiene menos caracteres que el ancho de campo, el campo se rellena a la izquierda hasta la longitud especificada por el ancho de campo. Si se especifica la opción - (justificar a la izquierda), el campo se rellena a la derecha.
• Una precisión opcional. La precisión es un . (punto) seguido de una serie de dígito decimal. Si no se especifica ninguna precisión, el valor predeterminado es 0. La precisión especifica los límites siguientes:
  • Número mínimo de dígitos que deben aparecer para las conversiones d, i, o, u, xo X .
  • Número de dígitos que deben aparecer después de la coma decimal para las conversiones e, Ey f .
  • Número máximo de dígitos significativos para las conversiones g y G .
  • Número máximo de bytes que deben imprimirse desde una serie en conversiones s y S .
  • Número máximo de bytes, convertidos desde la matriz wchar_t , que se imprimirán desde las conversiones S . Sólo se imprimen los caracteres completos.
• Un l opcional (en minúsculas L), ll (en minúsculas LL), ho el especificador L indica uno de los siguientes:
  • Una h opcional que especifica que un especificador de conversión d, i, u, o, xo X subsiguiente se aplica a un parámetro short int o unsigned short int Value (el parámetro se habrá promocionado de acuerdo con las promociones integrales, y su valor se convertirá a short int o unsigned short int antes de imprimir).
  • Una h opcional que especifica que un especificador de conversión n posterior se aplica a un puntero a un parámetro short int .
  • Un l opcional (en minúsculas L) que especifica que un especificador de conversión d, i, u, o, xo X posterior se aplica a un parámetro long int o unsigned long int .
  • Un l opcional (en minúsculas L) que especifica que un especificador de conversión n posterior se aplica a un puntero a un parámetro long int .
  • Un ll opcional ( LLen minúsculas) que especifica que un especificador de conversión d, i, u, o, xo X posterior se aplica a un parámetro long long int o unsigned long long int .
  • Un ll opcional ( LLen minúsculas) que especifica que un especificador de conversión n posterior se aplica a un puntero a un parámetro long long int .
  • Una L opcional que especifica que un especificador de conversión e, E, f, go G siguiente se aplica a un parámetro long double . Si se enlaza con libc.a, long double es el mismo que double (64bits). Si se enlaza con libc128.a y libc.a, long double es de 128 bits.
• Un especificador opcional H, Do DD indica una de las conversiones siguientes:
  • Un H opcional que especifica que un especificador de conversión e, E, f, F, go G siguiente se aplica a un parámetro _Decimal32 .
  • Una D opcional que especifica que un especificador de conversión e, E, f, F, go G siguiente se aplica a un parámetro _Decimal64 .
  • Un DD opcional que especifica que un especificador de conversión e, E, f, F, go G siguiente se aplica a un parámetro _Decimal128 .
• Un especificador opcional vl, lv, vh, hv o v indica una de las siguientes conversiones de tipo de datos de vector:
  • Un v opcional que especifica que un especificador de conversión e, E, f, g, G, ao A se aplica a un parámetro vector float . Consume un argumento e interpreta los datos como una serie de cuatro componentes de coma flotante de 4 bytes.
  • Un v opcional que especifica que un especificador de conversión c, d, i, u, o, xo X siguiente se aplica a un parámetro vector signed char, vector unsigned charo vector bool char . Consume un argumento e interpreta los datos como una serie de dieciséis componentes de 1 byte.
  • Un vl o lv opcional que especifica que un especificador de conversión d, i, u, o, xo X siguiente se aplica a un parámetro vector signed int, vector unsigned into vector bool . Consume un argumento e interpreta los datos como una serie de cuatro componentes enteros de 4 bytes.
  • Un vh o hv opcional que especifica que un especificador de conversión d, i, u, o, xo X se aplica a un parámetro vector signed short o vector unsigned short . Consume un argumento e interpreta los datos como una serie de ocho componentes enteros de 2 bytes.
  • Para cualquiera de los especificadores anteriores, se puede especificar un carácter separador opcional inmediatamente antes del especificador de tamaño de vector. Si no se especifica ningún separador, el separador predeterminado es un espacio a menos que la conversión sea c, en cuyo caso el separador predeterminado es nulo. El conjunto de separadores opcionales soportados son , (coma), ; (punto y coma), : (dos puntos) y _ (subrayado).
• Los siguientes caracteres indican el tipo de conversión que se va a aplicar:

  %

  No realiza ninguna conversión. Imprime (%).

  d o i

  Acepta un parámetro Valor que especifica un entero y lo convierte en notación decimal con signo. La precisión especifica el número mínimo de dígitos que deben aparecer. Si el valor que se está convirtiendo se puede representar en menos dígitos, se expande con 0 iniciales. La precisión predeterminada es 1. El resultado de convertir un valor de 0 con una precisión de 0 es una serie nula. Si se especifica un ancho de campo con 0 como carácter inicial, el valor de ancho de campo se rellena con 0 iniciales.

  u

  Acepta un parámetro Valor que especifica un entero sin signo y lo convierte en notación decimal sin signo. La precisión especifica el número mínimo de dígitos que deben aparecer. Si el valor que se está convirtiendo se puede representar en menos dígitos, se expande con 0 iniciales. La precisión predeterminada es 1. El resultado de convertir un valor de 0 con una precisión de 0 es una serie nula. Si se especifica un ancho de campo con 0 como carácter inicial, el valor de ancho de campo se rellena con 0 iniciales.

  o

  Acepta un parámetro Valor que especifica un entero sin signo y lo convierte en notación octal sin signo. La precisión especifica el número mínimo de dígitos que deben aparecer. Si el valor que se está convirtiendo se puede representar en menos dígitos, se expande con 0 iniciales. La precisión predeterminada es 1. El resultado de convertir un valor de 0 con una precisión de 0 es una serie nula. Si se especifica un ancho de campo con 0 como carácter inicial, el valor de ancho de campo se rellena con 0 iniciales. Un valor octal para el ancho de campo no está implícito.

  x o X

  Acepta un parámetro Valor que especifica un entero sin signo y lo convierte en notación hexadecimal sin signo. Las letras abcdef se utilizan para la conversión x y las letras ABCDEF se utilizan para la conversión X . La precisión especifica el número mínimo de dígitos que deben aparecer. Si el valor que se está convirtiendo se puede representar en menos dígitos, se expande con 0 iniciales. La precisión predeterminada es 1. El resultado de convertir un valor de 0 con una precisión de 0 es una serie nula. Si se especifica un ancho de campo con 0 como carácter inicial, el valor de ancho de campo se rellena con 0 iniciales.

  f

  Acepta un parámetro Valor que especifica un doble y lo convierte a notación decimal con el formato [-]ddd.ddd. El número de dígitos después de la coma decimal es igual a la especificación de precisión. Si no se especifica ninguna precisión, se generan seis dígitos. Si la precisión es 0, no aparece ninguna coma decimal.

  e o E

  Acepta un parámetro Valor que especifica un valor doble y lo convierte a la forma exponencial [-]d.ddde+/-dd. Existe un dígito antes de la coma decimal y el número de dígitos después de la coma decimal es igual a la especificación de precisión. La especificación de precisión puede estar en el rango de 0 a 17 dígitos. Si no se especifica ninguna precisión, se generan seis dígitos. Si la precisión es 0, no aparece ninguna coma decimal. El carácter de conversión E genera un número con E en lugar de e antes del exponente. El exponente siempre contiene al menos dos dígitos.

  g o G

  Acepta un parámetro Valor que especifica un doble y lo convierte al estilo de los caracteres de conversión e, Eo f , con la precisión que especifica el número de dígitos significativos. Los 0 finales se eliminan del resultado. Un separador decimal sólo aparece si va seguido de un dígito. El estilo utilizado depende del valor convertido. El estilo e(E, si G es la bandera utilizada) sólo resulta si el exponente resultante de la conversión es menor que -4, o si es mayor o igual que la precisión. Si una precisión explícita es 0, se toma como 1.

  c

  Acepta e imprime un parámetro Valor que especifica un entero convertido a un tipo de datos unsigned char .

  C

  Acepta e imprime un parámetro Valor que especifica un código de caracteres de ancho wchar_t . El código de caracteres anchos wchar_t especificado por el parámetro Valor se convierte en una matriz de bytes que representa un carácter y ese carácter se escribe; el parámetro Valor se escribe sin conversión cuando se utiliza la subrutina wsprintf .

  s

  Acepta un parámetro Valor como una serie (puntero de caracteres), y los caracteres de la serie se imprimen hasta que se encuentra un carácter nulo (\0) o se alcanza el número de bytes indicado por la precisión. Si no se especifica ninguna precisión, se imprimen todos los bytes hasta el primer carácter nulo. Si el puntero de serie especificado por el parámetro Valor tiene un valor nulo, los resultados no son fiables.

  O

  Acepta un parámetro Valor correspondiente como puntero a una serie wchar_t . Los caracteres de la serie se imprimen (sin conversión) hasta que se encuentra un carácter nulo (\0) o se alcanza el número de caracteres anchos indicado por la precisión. Si no se especifica ninguna precisión, se imprimen todos los caracteres hasta el primer carácter nulo. Si el puntero de serie especificado por el parámetro Valor tiene un valor nulo, los resultados no son fiables.

  p

  Acepta un puntero para anular. El valor del puntero se convierte en una secuencia de caracteres imprimibles, igual que un hexadecimal sin signo (x).

  n

  Acepta un puntero a un entero en el que se escribe el número de caracteres (códigos de caracteres anchos en el caso de la subrutina wsprintf ) escritos en la corriente de salida por esta llamada. No se convierte ningún argumento.

 

Un ancho o precisión de campo se puede indicar mediante un * (asterisco) en lugar de una serie de dígitos. En este caso, un parámetro Valor entero proporciona el ancho o la precisión del campo. El parámetro Valor convertido para la salida no se recupera hasta que se alcanza la letra de conversión, por lo que los parámetros que especifican el ancho o la precisión del campo deben aparecer antes del valor (si lo hay) que se va a convertir.

Si el resultado de una conversión es más ancho que el ancho del campo, el campo se expande para contener el resultado convertido y no se produce ningún truncamiento. Sin embargo, un pequeño ancho de campo o precisión puede provocar un truncamiento a la derecha.

La subrutina printf, fprintf, sprintf, snprintf, wsprintf, vprintf, vfprintf, vsprintfo vwsprintf permite la inserción de un carácter de raíz dependiente del idioma en la serie de salida. El carácter de raíz se define mediante datos específicos del idioma en la categoría LC_NUMERIC del entorno local del programa. En el entorno local C, o en un entorno local donde el carácter de raíz no está definido, el carácter de raíz toma el valor predeterminado de a. (punto).

Después de que cualquiera de estas subrutinas se ejecute correctamente, y antes de la siguiente finalización satisfactoria de una llamada a la subrutina fclose o fflush en la misma corriente o a la subrutina exit o abort , last_ctimeyst_mtimelos campos del archivo están marcados para actualización.

Los especificadores de conversión e, E, f, gy G representan los valores de coma flotante especiales de la forma siguiente:

La representación del signo + (signo más) depende de si se especifica la opción + o de formato de caracteres de espacio.

Estas subrutinas pueden manejar una serie de formato que permite al sistema procesar elementos de la lista de parámetros en orden variable. En tal caso, el carácter de conversión normal% (signo de porcentaje) se sustituye por %dígito$, donde dígito es un número decimal en el rango de 1 al valor NL_ARGMAX . A continuación, la conversión se aplica al argumento especificado, en lugar de al siguiente argumento no utilizado. Esta característica proporciona la definición de series de formato en un orden adecuado para idiomas específicos. Cuando se utiliza el orden de variables, la especificación * (asterisco) para el ancho de campo en precisión se sustituye por %dígito$. Si utiliza la característica de ordenación de variables, debe especificarla para todas las conversiones.

Se aplican los criterios siguientes:

• El formato pasado a las extensiones NLS puede contener el formato de la conversión o el número de argumento explícito o implícito. Sin embargo, estos formularios no se pueden mezclar dentro de una sola serie de formato, excepto para %% (signo de porcentaje doble).
• El valor n no debe tener ceros iniciales.
• Si se utiliza %n$ , se debe utilizar %1$ a %n- 1$ inclusive.
• n en %n$ está en el rango de 1 al valor NL_ARGMAX , ambos incluidos. Consulte el archivo limits.h para obtener más información sobre el valor NL_ARGMAX .
• Se puede hacer referencia a los argumentos numerados en la lista de argumentos tantas veces como sea necesario.
• La especificación * (asterisco) para la anchura o precisión de campo no está permitida con el formato %n$ de orden variable; en su lugar, se utiliza el formato *m$ .

Valores de retorno

Al finalizar correctamente, las subrutinas printf, fprintf, vprintfy vfprintf devuelven el número de bytes transmitidos (sin incluir el carácter nulo [\0] en el caso de las subrutinas sprintfy vsprintf ). Si se ha encontrado un error, se genera un valor negativo.

Tras una finalización satisfactoria, la subrutina snprintf devuelve el número de bytes escritos en el parámetro Serie (excluyendo el byte nulo de terminación). Si los caracteres de salida se descartan porque la salida ha superado el parámetro Número en longitud, la subrutina snprintf devuelve el número de bytes que se habrían grabado en el parámetro Serie si el parámetro Número hubiera sido lo suficientemente grande (excluyendo el byte nulo de terminación).

Tras una finalización satisfactoria, las subrutinas wsprintf y vwsprintf devuelven el número de caracteres anchos transmitidos (sin incluir el carácter ancho nulo [\0]). Si se ha encontrado un error, se genera un valor negativo.

Códigos de error

La subrutina printf, fprintf, sprintf, snprintfo wsprintf no es satisfactoria si el archivo especificado por el parámetro Stream no está en el almacenamiento intermedio o si el almacenamiento intermedio debe vaciarse y se cumplen una o varias de las siguientes condiciones:

La subrutina printf, fprintf, sprintf, snprintfo wsprintf puede no ser satisfactoria si se cumplen una o varias de las siguientes condiciones:

Ejemplos

El ejemplo siguiente muestra cómo se puede utilizar la subrutina vfprintf para escribir una rutina de error:

#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();  }