printf ()- Imprimir caracteres formateados

Formato

#include <stdio.h>
int printf(const char *format-string, argument-list);

Nivel de idioma

ANSI

De hebra segura

Sí

Sensible al entorno local

El comportamiento de esta función puede verse afectado por las categorías LC_CTYPE y LC_NUMERIC del entorno local actual. El comportamiento también puede verse afectado por la categoría LC_UNI_CTYPE del entorno local actual si se especifica LOCALETYPE (*LOCALEUCS2) o LOCALETYPE (*LOCALEUTF) en el mandato de compilación. Para obtener más información, consulte Descripción de CCSID y entornos locales.

Descripción

La función printf() formatea e imprime una serie de caracteres y valores en la corriente de salida estándar stdout. Las especificaciones de formato, que empiezan con un signo de porcentaje (%), determinan el formato de salida para cualquier lista-argumentos que siga a la serie-formato. La serie-formato es una serie de caracteres de varios bytes que empieza y termina en su estado de desplazamiento inicial.

La serie-formato se lee de izquierda a derecha. Cuando se encuentra la primera especificación de formato, el valor del primer argumento después de la serie-formato se convierte e imprime de acuerdo con la especificación de formato. La segunda especificación de formato hace que el segundo argumento después de la serie-formato se convierta e imprima, y así sucesivamente hasta el final de la serie-formato. Si hay más argumentos que especificaciones de formato, los argumentos adicionales se evalúan y se ignoran. Los resultados no están definidos si no hay suficientes argumentos para todas las especificaciones de formato.

Una especificación de formato tiene el formato siguiente:

Las conversiones se pueden aplicar al enésimo argumento después de la serie-formato en la lista de argumentos, en lugar del siguiente argumento no utilizado. En este caso, el carácter de conversión% se sustituye por la secuencia %n$, donde n es un entero decimal en el rango de 1 a NL_ARGMAX, dando la posición del argumento en la lista de argumentos. Esta característica proporciona la definición de series de formato que seleccionan argumentos en un orden adecuado para idiomas específicos.

La especificación de formato alternativo tiene el formato siguiente:

Como alternativa, se pueden asignar entradas específicas en la lista de argumentos utilizando la especificación de formato descrita en el diagrama anterior. Esta especificación de formato y la especificación de formato anterior no se pueden mezclar en la misma llamada a printf(). De lo contrario, podrían producirse resultados imprevisibles.

El número de argumento es una constante entera positiva donde 1 hace referencia a la primera entrada de la lista de argumentos. El número de argumento no puede ser mayor que el número de entradas de la lista de argumentos, o de lo contrario los resultados no están definidos. El número de arg tampoco puede ser mayor que NL_ARGMAX.

En las series de formato que contienen la forma %n$ de las especificaciones de conversión, se puede hacer referencia a los argumentos numerados de la lista de argumentos desde la serie de formato tantas veces como sea necesario.

En las series de formato que contienen la forma %n$ de una especificación de conversión, un ancho o precisión de campo puede indicarse mediante la secuencia * m$, donde m es un entero decimal en el rango de 1 a NL_ARGMAX que proporciona la posición en la lista de argumentos (después del argumento de formato) de un argumento entero que contiene el ancho o precisión del campo, por ejemplo:

printf("%1$d:%2$.*3$d:%4$.*3$d\n", hour, min, precision, sec);

La serie de formato puede contener especificaciones de argumento numeradas (es decir, %n$ y * m$) o especificaciones de argumento no numeradas (es decir,% y *), pero normalmente no ambas. La única excepción a esto es que%% puede mezclarse con el formulario %n$. Los resultados de mezclar especificaciones de argumentos numerados y no numerados en una serie de serie de formato no están definidos. Cuando se utilizan especificaciones de argumentos numerados, la especificación del enésimo argumento requiere que todos los argumentos iniciales, desde el primero hasta el (n-1) th, se especifiquen en la serie de formato.

Cada campo de la especificación de formato es un único carácter o número que indica una opción de formato determinada. El carácter tipo , que aparece después del último campo de formato opcional, determina si el argumento asociado se interpreta como un carácter, una serie, un número o puntero. La especificación de formato más simple sólo contiene el signo de porcentaje y un carácter type (por ejemplo, %s).

Los siguientes campos opcionales controlan otros aspectos del formato:

Campo

Descripción

distintivos

Justificación de la salida y la impresión de signos, espacios en blanco, puntos decimales, prefijos octales y hexadecimales, y la semántica para la unidad de precisión wchar_t .

anchura

Número mínimo de bytes de salida.

precisión

Consulte la Tabla 2.

h, l, ll, L, H, D, DD

Tamaño de argumento esperado:

h: Un prefijo con los tipos d, i, o, u, x, Xy n que especifica que el argumento es un short int o unsigned short int.
l: Un prefijo con los tipos d, i, o, u, x, Xy n que especifica que el argumento es un long int o unsigned long int.
ll: Un prefijo con los tipos d, i, o, u, x, Xy n que especifica que el argumento es un long long int o unsigned long long int.
L: Un prefijo con los tipos a, A, e, E, f, F, go G que especifica que el argumento es long double.
H: Un prefijo con los tipos a, A, e, E, f, F, go G que especifica que el argumento es _Decimal32.
D: Un prefijo con los tipos a, A, e, E, f, F, go G que especifica que el argumento es _Decimal64.
DD: Un prefijo con los tipos a, A, e, E, f, F, go G que especifica que el argumento es _Decimal128.

Cada campo de la especificación de formato se describe en detalle a continuación. Si un signo de porcentaje (%) va seguido de un carácter que no tiene ningún significado como campo de formato, el comportamiento no está definido. Una excepción a este comportamiento es %%. Para imprimir un carácter de signo de porcentaje, utilice %%.

Los caracteres de tipo y sus significados se proporcionan en la tabla siguiente:

Tabla 1. Caracteres de tipo
Carácter	Argumento	Formato de salida
a	Coma flotante	Para números de coma flotante no decimales, valor con signo con el formato [-] 0xh.hhhhp [signo]ddd, donde h es un dígito hexadecimal único, hhh es uno o más dígitos hexadecimales, ddd es uno o más dígitos decimales y signo es + o-. El número de dígitos hexadecimales después de la coma decimal es igual a la precisión solicitada. Para los números de coma flotante decimal, si falta la precisión, se utiliza el formato de estilo f o e basándose en los criterios siguientes. El formato de estilo f se utiliza cuando el exponente cuántico del valor es menor o igual que 0 pero mayor o igual que-(n+ 5). El exponente cuántico de un número se puede determinar llamando a la función quantexp64(). n es el número de dígitos de la secuencia de dígitos (incluidos los ceros finales) cuando se ignora la coma decimal. Por ejemplo: 0.000005 contiene 1 dígito en la secuencia de dígitos, n = 1 0.0000050 contiene 2 dígitos en la secuencia de dígitos, n = 2 12.30 contiene 4 dígitos en la secuencia de dígitos, n = 4 La precisión es igual al valor absoluto del exponente cuántico del valor. El formato de estilo e se utiliza cuando el exponente cuántico del valor no satisface los criterios de estilo f . La precisión es igual a n-1. El formato de estilo e de un valor de coma flotante decimal es el mismo que el formato de estilo e de un valor de coma flotante no decimal con dos excepciones: a) si el valor es igual a 0, el exponente es igual al exponente cuántico del valor, y b) el exponente siempre se proporciona con el número mínimo de dígitos necesarios (es decir, el exponente nunca contiene un cero inicial). Por ejemplo: 0.0000000 produce 0e-7 -1870 produce -1.87e+3 Si el modificador de precisión está presente y al menos es tan grande como la precisión del valor, la conversión es como si faltara el modificador de precisión. Si el modificador de precisión está presente y es menor que la precisión del valor, el valor se redondea primero al número de dígitos especificado por el modificador de precisión. A continuación, el resultado se convierte como si faltara el modificador de precisión.
A	Coma flotante	Idéntico al formato a excepción de que se utilizan caracteres alfabéticos en mayúsculas en lugar de caracteres alfabéticos en minúsculas.
d, i	Entero	Entero decimal con signo.
u	Entero	Entero decimal sin signo.
o	Entero	Entero octal sin signo.
x	Entero	Entero hexadecimal sin signo, utilizando abcdef.
X	Entero	Entero hexadecimal sin signo, utilizando ABCDEF.
D (n, p)	Decimal empaquetado	Tiene el formato [-] dddd.dddd donde el número de dígitos después de la coma decimal es igual a la precisión de la especificación. Si falta la precisión, el valor predeterminado es p; si la precisión es cero y no se especifica el distintivo #, no aparece ningún carácter de coma decimal. Si n y p son *, un argumento de la lista de argumentos proporciona el valor. n y p deben preceder al valor que se formatea en la lista de argumentos. Al menos un carácter aparece antes de una coma decimal. El valor se redondea al número adecuado de dígitos.
f	Coma flotante	Valor firmado con el formato [-]dddd.dddd, donde dddd es uno o más dígitos decimales. El número de dígitos antes de la coma decimal depende de la magnitud del número. El número de dígitos después de la coma decimal es igual a la precisión solicitada.²
F	Coma flotante	Idéntico al formato f excepto que se utilizan caracteres alfabéticos en mayúsculas en lugar de caracteres alfabéticos en minúsculas.²
e	Coma flotante	Valor con signo con el formato [-]d.dddd e[signo]ddd, donde d es un dígito decimal único, dddd es uno o más dígitos decimales, ddd es 2 o más dígitos decimales y signo es + o-.²
E	Coma flotante	Idéntico al formato e , excepto que se utilizan caracteres alfabéticos en mayúsculas en lugar de caracteres alfabéticos en minúsculas.²
g	Coma flotante	Valor firmado impreso en formato f o e . El formato e sólo se utiliza cuando el exponente del valor es menor que -4 o mayor o igual que precisión. Los ceros finales se truncan y el separador decimal sólo aparece si le siguen uno o más dígitos.²
G	Coma flotante	Idéntico al formato g, excepto que se utilizan caracteres alfabéticos en mayúsculas en lugar de caracteres alfabéticos en minúsculas.²
c	Carácter (byte)	Carácter único.
s	Serie	Caracteres (bytes) impresos hasta el primer carácter nulo (\0) o hasta que se alcance la precisión .
n	Puntero a entero	Número de caracteres (bytes) grabados correctamente hasta ahora en la secuencia o el almacenamiento intermedio; este valor se almacena en el entero cuya dirección se proporciona como argumento.
p	Puntero	Puntero convertido a una secuencia de caracteres imprimibles. Puede ser uno de los siguientes: puntero de espacio puntero del sistema puntero de invocación puntero de procedimiento puntero de apertura puntero de suspensión puntero de datos puntero de etiqueta
lc o C	carácter ancho	El carácter (wchar_t) se convierte en un carácter de varios bytes como si fuera una llamada a wctomb (), y este carácter se imprime.¹
ls o S	carácter ancho	Los caracteres (wchar_t) hasta el primer carácter (wchar_t) nulo (L\0), o hasta que se alcance la precisión, se convierten a caracteres de varios bytes, como si una llamada a wcstombs (), y estos caracteres se imprimen. Si el argumento es una serie nula, se imprime (null).¹

Nota:

Consulte la documentación de la función wctomb() o la documentación de la función wcstombs() para obtener más información. También puede encontrar información adicional en Caracteres amplios.
Si no se utilizan los especificadores de tamaño de formato H, D o DD, sólo se garantizan 15 dígitos significativos de salida.

La lista siguiente muestra el formato de los valores impresos para los punteros IBM® i y proporciona una breve descripción de los componentes de los valores impresos.

Puntero de espacio: SPP:Context :Object :Offset :AG

Context: type, subtype and name of the context
Object: type, subtype and name of the object
Offset: offset within the space
AG: Activation group ID

Puntero del sistema: SYP:Context :Object :Auth :Index :AG

Context: type, subtipo y nombre del contexto
Objeto: tipo, subtipo y nombre del objeto
Auth: authority
Índice: Índice asociado con el puntero
AG: ID de grupo de activación

Puntero de invocación: IVP:Index :AG

Índice: Índice asociado con el puntero
AG: ID de grupo de activación

Puntero de procedimiento: PRP:Index :AG

Índice: Índice asociado con el puntero
AG: ID de grupo de activación

Puntero de suspensión: SUP:Index :AG

Índice: Índice asociado con el puntero
AG: ID de grupo de activación

Puntero de datos: DTP:Index :AG

Índice: Índice asociado con el puntero
AG: ID de grupo de activación

Puntero de etiqueta: LBP:Index :AG

Índice: Índice asociado con el puntero
AG: ID de grupo de activación

Puntero NULL: NULL

Las restricciones siguientes se aplican a la impresión y exploración de punteros en el sistema operativo IBM i :

Si se imprime un puntero y se vuelve a escanear desde el mismo grupo de activación, el puntero de retroceso escaneado se comparará con el puntero impreso.
Si una función de la familia scanf() explora un puntero que ha imprimido un grupo de activación diferente, la función de la familia scanf() establecerá el puntero en NULL.
Si un puntero se imprime en un entorno de teraespacio, sólo se imprime el valor hexadecimal del puntero. Estos resultados son los mismos que cuando se utiliza%#p.

El especificador de formato%#p tiene un rendimiento mucho mejor que el especificador de formato %p.

Consulte la publicación ILE C/C++ Programmer's Guide para obtener más información sobre cómo utilizar los punteros de IBM i .

Si un valor de coma flotante de INFINITY o Not-a-Number (NaN) se formatea utilizando el formato a, e, f o g, la serie de salida esinfinityonan. Si un valor de coma flotante de INFINITY o Not-A-Number (NaN) se formatea utilizando el formato A, E, F o G, la serie de salida esINFINITYoNAN.

Los caracteres flag y sus significados son los siguientes (observe que puede aparecer más de un flag en una especificación de formato):

Distintivo	Significado	Valor por omisión
-	Justifique a la izquierda el resultado dentro del ancho del campo.	Justificar a la derecha.
+	Prefije el valor de salida con un signo (+ o-) si el valor de salida es de un tipo con signo.	El signo sólo aparece para los valores con signo negativo (-).
en blanco('')	Prefije el valor de salida con un espacio en blanco si el valor de salida está firmado y es positivo. El distintivo + altera temporalmente el distintivo en blanco si aparecen ambos, y se generará un valor con signo positivo con un signo.	No está en blanco.
#	Cuando se utiliza con los formatos o, xo X , el distintivo # prefija cualquier valor de salida distinto de cero con 0, 0x o 0X, respectivamente.	Sin prefijo.
	Cuando se utiliza con los formatos D (n, p), a, A, e, E, f o F , el distintivo # fuerza al valor de salida a contener una coma decimal en todos los casos.	La coma decimal sólo aparece si le siguen los dígitos.
	Cuando se utiliza con los formatos g o G , el distintivo # fuerza al valor de salida a contener una coma decimal en todos los casos e impide el truncamiento de los ceros finales.	El separador decimal sólo aparece si le siguen los dígitos; los ceros finales se truncan.
	Cuando se utiliza con el formato ls o S, el distintivo # hace que la precisión se mida en caracteres, independientemente del tamaño del carácter. Por ejemplo, si se imprimen caracteres de un solo byte, una precisión de 4 daría como resultado la impresión de 4 bytes. Si se imprimen caracteres de doble byte, una precisión de 4 daría como resultado la impresión de 8 bytes.	La precisión indica el número máximo de bytes que se van a generar.
	Cuando se utiliza con el formato p , el distintivo # convierte el puntero a dígitos hexadecimales. Estos dígitos hexadecimales no se pueden volver a convertir en un puntero, a menos que sea en un entorno de teraespacio.	Puntero convertido a una secuencia de caracteres imprimibles.
0	Cuando se utiliza con los formatos d, i, D (n, p) o, u, x, X, a, A, e, E, f, F, go G , el distintivo 0 hace que los 0s iniciales rellenen la salida con el ancho de campo. El distintivo 0 se ignora si se especifica precisión para un entero o si se especifica el distintivo - .	Relleno de espacio. No hay relleno de espacio para D (n, p).

El distintivo # no debe utilizarse con los tipos c, lc, d, i, uo s .

Anchura es un entero decimal no negativo que controla el número mínimo de caracteres impresos. Si el número de caracteres (bytes) en el valor de salida es menor que el anchoespecificado, se añaden espacios en blanco a la izquierda o a la derecha (en función de si se especifica el distintivo - ) hasta que se alcanza el ancho mínimo.

Ancho nunca hace que se trunque un valor; si el número de caracteres (bytes) en el valor de salida es mayor que el anchoespecificado, o si no se especifica ancho , se imprimen todos los caracteres del valor (sujetos a la especificación precisión ).

Para el tipo ls o S, width se especifica en bytes. Si el número de bytes en el valor de salida es menor que el ancho especificado, se añaden blancos de un solo byte a la izquierda o a la derecha (en función de si se especifica el distintivo - ) hasta que se alcanza el ancho mínimo.

La especificación width puede ser un asterisco (*), en cuyo caso un argumento de la lista de argumentos proporciona el valor. El argumento width debe preceder al valor que se formatea en la lista de argumentos.

Precisión es un entero decimal no negativo precedido por un punto, que especifica el número de caracteres que deben imprimirse o el número de posiciones decimales. A diferencia de la especificación width , la precisión puede provocar el truncamiento del valor de salida o el redondeo de un valor de coma flotante o decimal empaquetado .

La especificación precision puede ser un asterisco (*), en cuyo caso un argumento de la lista de argumentos proporciona el valor. El argumento precision debe preceder al valor que se formatea en la lista de argumentos.

La interpretación del valor de precisión y el valor predeterminado cuando se omite la precisión dependen del tipo, tal como se muestra en la tabla siguiente:

Tabla 2. Valores de precisión
Tipo	Significado	Valor por omisión
a A	Para números de coma flotante no decimales, la precisión especifica el número de dígitos hexadecimales que se imprimirán después de la coma decimal. Para los números de coma flotante decimal, precisión especifica el número de dígitos significativos que deben imprimirse.	Para números de coma flotante no decimales, la precisión predeterminada es suficiente para una representación exacta del valor. Si la precisión es 0, no se imprime ninguna coma decimal. Para los números de coma flotante decimal, la precisión predeterminada es suficiente para una representación exacta del valor. Consulte la Tabla 1 para obtener más detalles sobre el formato utilizado.
i d u o x X	Precisión especifica el número mínimo de dígitos que deben imprimirse. Si el número de dígitos del argumento es menor que precisión, el valor de salida se rellena a la izquierda con ceros. El valor no se trunca cuando el número de dígitos supera la precisión.	Si la precisión es 0 o se omite por completo, o si el punto (.) aparece sin un número a continuación, la precisión se establece en 1.
f F D (n, p) e E	Precisión especifica el número de dígitos que deben imprimirse después de la coma decimal. El último dígito impreso se redondea.	La precisión predeterminada para f, F, e y E es seis. La precisión predeterminada para D (n, p) es p. Si la precisión es 0 o el punto aparece sin un número a continuación, no se imprime ninguna coma decimal.
g G	Precisión especifica el número máximo de dígitos significativos impresos.	Se imprimen todos los dígitos significativos. La precisión predeterminada es seis.
c	Sin efecto.	El carácter se imprime.
LC	Sin efecto.	El carácter wchar_t se convierte y se imprime el carácter multibyte resultante.
s	Precisión especifica el número máximo de caracteres (bytes) que deben imprimirse. Los caracteres (bytes) superiores a precisión no se imprimen.	Los caracteres se imprimen hasta que se encuentra un carácter nulo.
ls	Precisión especifica el número máximo de bytes que deben imprimirse. Los bytes que exceden la precisión no se imprimen; sin embargo, la integridad multibyte siempre se conserva.	Los caracteres wchar_t se convierten y se imprimen los caracteres multibyte resultantes.

Valor de retorno

La función printf() devuelve el número de bytes impresos. El valor de errno se puede establecer en:

valor: Significado
EBADMODE: La modalidad de archivo especificada no es válida.
CONVERTIR: Se ha producido un error de conversión.
EIOERROR: Se ha producido un error de E/S irrecuperable.
EIORECERR: Se ha producido un error de E/S irrecuperable.
EILSEQ: Se ha encontrado una secuencia de caracteres de varios bytes no válida.
EPUTANOGET: Se ha producido una operación de grabación no permitida después de una operación de lectura.
ESTDOUT: stdout no se puede abrir.

Nota: El carácter de raíz para la función printf() es sensible al entorno local. El carácter de raíz es la coma decimal que se utilizará para el carácter de distintivo # del parámetro de serie de formato para los tipos de formato D (n, p), a, A, e, E, f, F, g y G.

Ejemplos

Este ejemplo imprime datos en diversos formatos.

#include <stdio.h>                                               
#include <stdlib.h>                                              
                                                                 
int main(void)                                                   
{                                                                
    char ch = 'h', *string = "computer";                         
    int count = 234, hex = 0x10, oct = 010, dec = 10;            
    double fp = 251.7366;                                        
    wchar_t wc = (wchar_t)0x0058;                                
    wchar_t ws[4];                                                       
                                                     
    printf("1234567890123%n4567890123456789\n\n", &count);          
    printf("Value of count should be 13; count = %d\n\n", count);   
    printf("%10c%5c\n", ch, ch);                                    
    printf("%25s\n%25.4s\n\n", string, string);                     
    printf("%f    %.2f    %e    %E\n\n", fp, fp, fp, fp);           
    printf("%i    %i     %i\n\n", hex, oct, dec);                   
}                                                                   
/*****************  Output should be similar to:  ***************** 
                                                                    
234   +234    000234     EA    ea     352                           
                                                                    
12345678901234567890123456789                                       
                                                                    
Value of count should be 13; count = 13                             
 
                                                                      
  h    h                                                              
          computer                                                    
              comp                                                    
                                                                      
251.736600    251.74    2.517366e+02    2.517366E+02                  
                                                                      
16    8     10                                                        
 
*******************************************************************/

Ejemplo que utiliza printf()

     #include <stdio.h>
     #include <stdlib.h>
     #include <locale.h>
     /* This program is compiled with LOCALETYPE(*LOCALEUCS2) and             */
     /* SYSIFCOPT(*IFSIO)                                               */
     /* We will assume the locale setting is the same as the CCSID of the */
     /* job.  We will also assume any files involved have a CCSID of      */
     /* 65535 (no convert).  This way if printf goes to the screen or     */
     /* a file the output will be the same.                               */
    int main(void)
    {
        wchar_t wc = 0x0058;     /* UNICODE X */
        wchar_t ws[4];
        setlocale(LC_ALL,
         "/QSYS.LIB/EN_US.LOCALE"); /* a CCSID 37 locale */
        ws[0] = 0x0041;        /* UNICODE A   */
        ws[1] = (wchar_t)0x0042;        /* UNICODE B   */
        ws[2] = (wchar_t)0x0043;        /* UNICODE C   */
        ws[3] = (wchar_t)0x0000;
        /* The output displayed is CCSID 37  */
        printf("%lc   %ls\n\n",wc,ws);
        printf("%lc   %.2ls\n\n",wc,ws);

        /* Now let's try a mixed-byte CCSID example  */
        /* You would need a device that can handle mixed bytes to  */
        /* display this correctly.                         */

        setlocale(LC_ALL,
        "/QSYS.LIB/JA_JP.LOCALE");/* a CCSID 5026 locale */

        /* big A means an A that takes up 2 bytes on the screen   */
        /* It will look bigger then single byte A                 */
        ws[0] = (wchar_t)0xFF21;        /* UNICODE big A   */
        ws[1] = (wchar_t)0xFF22;        /* UNICODE big B   */
        ws[2] = (wchar_t)0xFF23;        /* UNICODE big C   */
        ws[3] = (wchar_t)0x0000;
        wc = 0xff11;                    /* UNICODE big 1   */

        printf("%lc   %ls\n\n",wc,ws);

        /* The output of this printf is not shown below and it   */
        /* will differ depending on the device you display it on,*/
        /* but if you looked at the string in hex it would look  */
        /* like this:  0E42F10F404040400E42C142C242C30F          */
        /* 0E is shift out, 0F is shift in, and 42F1 is the      */
        /* big 1 in CCSID   5026  */

        printf("%lc   %.4ls\n\n",wc,ws);

        /* The output of this printf is not shown below either. */
        /* The hex would look like:                             */
        /* 0E42F10F404040400E42C10F                             */
        /* Since the precision is in bytes we only get 4 bytes  */
        /* of the string.         */

        printf("%lc   %#.2ls\n\n",wc,ws);

        /* The output of this printf is not shown below either. */
        /* The hex would look like:                             */
        /* 0E42F10F404040400E42C142C20F                         */
        /* The # means precision is in characters reguardless   */
        /* of size.  So we get 2 characters of the string.      */
    }
 /*****************  Output should be similar to:  *****************


 X     ABC

 X     AB

 *******************************************************************/