The printf
built-in function writes output to
an implementation-defined stream such as stdout under control of the
string pointed to by format
that specifies how
subsequent arguments are converted for output. If there are insufficient
arguments for the format, the behavior is undefined. If the format is
exhausted while arguments remain, the excess arguments are evaluated
(as always) but are otherwise ignored. The printf
function returns when the end of the format string is encountered.
printf
returns 0 if it was executed successfully
and -1 otherwise.
printf
output synchronization
When the event that is associated with a particular kernel invocation is completed,
the output of all printf
() calls executed by this kernel
invocation is flushed to the implementation-defined output stream. Calling
clFinish on a command
queue flushes all pending output by printf
in previously enqueued
and completed commands to the implementation-defined output stream. In the case that
printf
is executed from multiple work-items concurrently, there
is no guarantee of ordering with respect to written data. For example, it is valid
for the output of a work-item with a global id (0,0,1) to appear intermixed with the
output of a work-item with a global id (0,0,4) and so on.
printf
format stringThe format shall be a character sequence, beginning and ending in its initial shift state. The format is composed of zero or more directives: ordinary characters (not %), which are copied unchanged to the output stream; and conversion specifications, each of which results in fetching zero or more subsequent arguments, converting them, if applicable, according to the corresponding conversion specifier, and then writing the result to the output stream. As format is in the constant address space it must be resolvable at compile time and thus cannot be dynamically created by the executing program, itself.
Each conversion specification is introduced by the character %. After the %, the following appear in sequence:
flags
(in any order) that modify the meaning
of the conversion specification.
field width
. If the converted value has
fewer characters than the field width, it is padded with spaces (by default)
on the left (or right, if the left adjustment flag, described later, has been
given) to the field width. The field width takes the form of a nonnegative decimal
integer.) Note that 0 is taken as a flag, not as the beginning of a field width.
precision
that gives the minimum number of digits
to appear for the d, i, o, u, x, and X conversions, the number of digits to
appear after the decimal point character for a, A, e, E, f, and F conversions,
the maximum number of significant digits for the g and G conversions, or the
maximum number of bytes to be written for s conversions. The precision takes
the form of a period (.) followed by an optional decimal integer; if only the
period is specified, the precision is taken as zero. If a precision appears
with any other conversion specifier, the behavior is undefined.
vector specifier
.
length modifier
that specifies the size of the argument. The
length modifier
is required with a vector specifier and together
specifies the vector type. Implicit conversions between vector types are disallowed
(as per section 6.2.1). If the vector specifier
is not specified,
the length modifier
is optional.
conversion specifier
character that specifies the type of
conversion to be applied.
The flag characters and their meanings are:
- | The result of the conversion is left-justified within the field. (It is right-justified if this flag is not specified.) |
+ | The result of a signed conversion always begins with a plus or minus sign. (It begins with a sign only when a negative value is converted if this flag is not specified.) The results of all floating conversions of a negative zero, and of negative values that round to zero, include a minus sign. |
space |
If the first character of a signed conversion is not a sign, or if
a signed conversion results in no characters, a space is prefixed to
the result. If the space and + flags both appear,
the space flag is ignored.
|
# | The result is converted to an "alternative form". For o conversion, it increases the precision, if and only if necessary, to force the first digit of the result to be a zero (if the value and precision are both 0, a single 0 is printed). For x (or X) conversion, a nonzero result has 0x (or 0X) prefixed to it. For a, A, e, E, f, F, g, and G conversions, the result of converting a floating-point number always contains a decimal-point character, even if no digits follow it. (Normally, a decimal-point character appears in the result of these conversions only if a digit follows it.) For g and G conversions, trailing zeros are not removed from the result. For other conversions, the behavior is undefined. |
0 | For d, i, o, u, x, X, a, A, e, E, f, F, g, and G conversions, leading zeros (following any indication of sign or base) are used to pad to the field width rather than performing space padding, except when converting an infinity or NaN. If the 0 and - flags both appear, the 0 flag is ignored. For d, i, o, u, x, and X conversions, if a precision is specified, the 0 flag is ignored. For other conversions, the behavior is undefined. |
The vector specifier and its meaning is:
vn |
Specifies that a following a, A, e, E, f, F, g, G, d, i, o, u,
x, or X conversion specifier applies to a vector argument, where
n is the size of the vector and must be 2,
3, 4, 8 or 16. The vector value is displayed in the following general
form:
value1 C value2 C ... C value where C is a separator character. The value for this separator character is a comma. |
If the vector specifier is not used, the length modifiers and their meanings are:
hh | Specifies that a following d, i, o, u, x, or X conversion specifier applies to a char or uchar argument (the argument will have been promoted according to the integer promotions, but its value shall be converted to char or uchar before printing). |
h | Specifies that a following d, i, o, u, x, or X conversion specifier applies to a short or ushort argument (the argument will have been promoted according to the integer promotions, but its value shall be converted to short or unsigned short before printing). |
l (ell) | Specifies that a following d, i, o, u, x, or X conversion specifier applies to a long or ulong argument. The l modifier is supported by the full profile. For the embedded profile, the l modifier is supported only if 64-bit integers are supported by the device. |
If the vector specifier is used, the length modifiers and their meanings are:
hh |
Specifies that a following d, i, o, u, x, or X conversion
specifier applies to a charn or
ucharn argument (the argument will not
be promoted).
|
h |
Specifies that a following d, i, o, u, x, or X conversion
specifier applies to a shortn or
ushortn argument (the argument will not
be promoted); that a following a, A, e, E, f, F, g, or G conversion
specifier applies to a halfn argument if the
cl_khr_fp16
extension is supported.
|
hl |
This modifier can only be used with the vector specifier. Specifies
that a following d, i, o, u, x, or X conversion specifier applies to a
intn or uintn
argument; that a following a, A, e, E, f, F, g, or G conversion
specifier applies to a floatn argument.
|
l (ell) |
Specifies that a following d, i, o, u, x, or X conversion
specifier applies to a longn or
ulongn argument; that a following
a, A, e, E, f, F, g, or G conversion specifier applies to
a doublen argument. The l modifier
is supported by the full profile. For the embedded profile, the l
modifier is supported only if 64-bit integers or double-precision
floating-point are supported by the device.
|
If a vector specifier appears without a length modifier, the behavior is undefined. The vector data type described by the vector specifier and length modifier must match the data type of the argument; otherwise the behavior is undefined.
If a length modifier appears with any conversion specifier other than as specified above, the behavior is undefined
The conversion specifiers and their meanings are:
d,i |
The int, charn ,
shortn , intn
or longn argument is converted to signed
decimal in the style [−]dddd. The precision
specifies the minimum number of digits to appear; if the value being
converted can be represented in fewer digits, it is expanded with
leading zeros. The default precision is 1. The result of converting
a zero value with a precision of zero is no characters.
|
o,u,x,X |
The unsigned int, ucharn ,
ushortn , uintn
or ulongn argument is converted to unsigned
octal (o), unsigned decimal (u), or unsigned hexadecimal notation (x
or X) in the style dddd; the letters abcdef are
used for x conversion and the letters ABCDEF for X conversion. The
precision specifies the minimum number of digits to appear; if the
value being converted can be represented in fewer digits, it is
expanded with leading zeros. The default precision is 1. The result
of converting a zero value with a precision of zero is no characters.
|
f,F |
A double, halfn ,
floatn or doublen
argument representing a floating-point number is converted to decimal
notation in the style [−]ddd.ddd ,
where the number of digits after the decimal-point character is
equal to the precision specification. If the precision is missing,
it is taken as 6; if the precision is zero and the # flag is not
specified, no decimal-point character appears. If a decimal-point
character appears, at least one digit appears before it. The
value is rounded to the appropriate number of digits. A double,
halfn , floatn
or doublen argument representing an infinity
is converted in one of the styles [-]inf or [-]infinity — which style
is implementation-defined. A double, halfn ,
floatn or doublen
argument representing a NaN is converted in one of the styles [-
]nan or [-]nan(n-char-sequence ) — which style, and the meaning
of any n-charsequence, is implementation-defined. The F conversion
specifier produces INF, INFINITY, or NAN instead of inf, infinity, or
nan, respectively. When applied to infinite and NaN values, the -,
+, and space flag characters have their
usual meaning; the # and 0 flag characters have no effect.
|
e,E |
A double, halfn ,
floatn or doublen
argument representing a floating-point number is converted in the style
[−]d.ddd e±dd ,
where there is one digit (which is nonzero if the argument is nonzero)
before the decimal-point character and the number of digits after it is
equal to the precision; if the precision is missing, it is taken as 6; if
the precision is zero and the # flag is not specified, no decimal-point
character appears. The value is rounded to the appropriate number of
digits. The E conversion specifier produces a number with E instead
of e introducing the exponent. The exponent always contains at least
two digits, and only as many more digits as necessary to represent
the exponent. If the value is zero, the exponent is zero. A double,
halfn , floatn
or doublen argument representing an infinity
or NaN is converted in the style of an f or F conversion specifier
|
g,G |
A double, halfn ,
floatn or doublen
argument representing a floating-point number is converted in
style f or e (or in style F or E in the case of a G conversion
specifier), depending on the value converted and the precision. Let
P equal the precision if nonzero, 6 if
the precision is omitted, or 1 if the precision is zero. Then, if a
conversion with style E would have an exponent of X :
— if P > X ≥ −4, the
conversion is with style f (or F) and precision P
− (X + 1). — otherwise, the conversion is with
style e (or E) and precision P − 1. Finally,
unless the # flag is used, any trailing zeros are removed from the
fractional portion of the result and the decimal-point character
is removed if there is no fractional portion remaining. A double,
halfn , floatn or
doublen e argument representing an infinity
or NaN is converted in the style of an f or F conversion specifier.
|
a,A |
A double, halfn ,
floatn or doublen
argument representing a floating-point number is converted in the style
[−]0xh.hhhh p±d ,
where there is one hexadecimal digit (which is nonzero if the argument
is a normalized floating-point number and is otherwise unspecified)
before the decimal-point character) and the number of hexadecimal digits
after it is equal to the precision; if the precision is missing, then
the precision is sufficient for an exact representation of the value;
if the precision is zero and the # flag is not specified, no decimal
point character appears. The letters abcdef are used for a conversion
and the letters ABCDEF for A conversion. The A conversion specifier
produces a number with X and P instead of x and p. The exponent
always contains at least one digit, and only as many more digits as
necessary to represent the decimal exponent of 2. If the value is zero,
the exponent is zero. A double, halfn ,
floatn or doublen
argument representing an infinity or NaN is converted in the style
of an f or F conversion specifier. Binary implementations can choose
the hexadecimal digit to the left of the decimal-point character so
that subsequent digits align to nibble (4-bit) boundaries.
|
NOTE: The conversion specifiers e,E,g,G,a,A convert a float or half argument that is a scalar type to a double only if the double data type is supported. If the double data type is not supported, the argument will be a float instead of a double and the half type will be converted to a float.
c | The int argument is converted to an unsigned char, and the resulting character is written. |
s |
The argument shall be a literal string. No special provisions are made
for multibyte characters. The behavior of printf
with the s conversion specifier is undefined if the argument value
is not a pointer to a literal string. Characters from the literal
string array are written up to (but not including) the terminating
null character. If the precision is specified, no more than that many
bytes are written. If the precision is not specified or is greater
than the size of the array, the array shall contain a null character.
|
p | The argument shall be a pointer to void. The pointer can refer to a memory region in the global, constant, local or private address space. The value of the pointer is converted to a sequence of printing characters in an implementation-defined manner. |
% | A % character is written. No argument is converted. The complete conversion specification shall be %%. |
If a conversion specification is invalid, the behavior is undefined. If any argument is not the correct type for the corresponding conversion specification, the behavior is undefined.
In no case does a nonexistent or small field width cause truncation of a field; if the result of a conversion is wider than the field width, the field is expanded to contain the conversion result.
For a and A conversions, the value is correctly rounded to a hexadecimal floating number with the given precision.
printf
n
vector specifier to support printing of vector types.
CL_DEVICE_DOUBLE_FP_CONFIG
. If the double data type is
not supported, the argument will be a float instead of a double.
printf
returns 0 if it was executed successfully
and -1 otherwise vs. C99 where printf
returns the number
of characters printed or a negative value if an output or encoding error occurred.
float4 f = (float4)(1.0f, 2.0f, 3.0f, 4.0f); uchar4 uc = (uchar4)(0xFA, 0xFB, 0xFC, 0xFD); printf("f4 = %2.2v4hlf\n", f); printf("uc = %#v4hhx\n", uc); // The above two calls print the following: f4 = 1.00,2.00,3.00,4.00 uc = 0xfa,0xfb,0xfc,0xfd |
A few examples of valid use cases of printf
for the conversion
specifier s are given below. The argument value must be a pointer to a literal string.
kernel void my_kernel( ... ) { printf("%s\n", "this is a test string\n"); } |
A few examples of invalid use cases of printf
for the conversion
specifier s are given below:
kernel void my_kernel(global char *s, ... ) { printf("%s\n", s); constant char *p = "this is a test string\n"; printf("%s\n", p); printf("%s\n", &p[3]); } |
A few examples of invalid use cases of printf where data types given by the vector specifier and length modifier do not match the argument type are given below:
kernel void my_kernel(global char *s, … ) { uint2 ui = (uint2)(0x12345678, 0x87654321); printf("unsigned short value = (%#v2hx)\n", ui) printf("unsigned char value = (%#v2hhx)\n", ui) } |