1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
|
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook MathML Module V1.1b1//EN"
"http://www.oasis-open.org/docbook/xml/mathml/1.1CR1/dbmathml.dtd">
<refentry>
<refentryinfo>
<keywordset>
<keyword>printf Function</keyword>
</keywordset>
</refentryinfo>
<refmeta>
<refentrytitle>
printf Function
</refentrytitle>
<refmiscinfo>
<copyright>
<year>2007-2011</year>
<holder>The Khronos Group Inc.
Permission is hereby granted, free of charge, to any person obtaining a
copy of this software and/or associated documentation files (the
"Materials"), to deal in the Materials without restriction, including
without limitation the rights to use, copy, modify, merge, publish,
distribute, sublicense, and/or sell copies of the Materials, and to
permit persons to whom the Materials are furnished to do so, subject to
the condition that this copyright notice and permission notice shall be included
in all copies or substantial portions of the Materials.</holder>
</copyright>
</refmiscinfo>
<manvolnum>3</manvolnum>
</refmeta>
<!-- ================================ SYNOPSIS -->
<refnamediv id="printfFunction">
<refname>
printf Function
</refname>
<refpurpose>
The OpenCL C programming language implements the <function>printf</function> function.
</refpurpose>
</refnamediv>
<refsynopsisdiv xmlns:xlink="http://www.w3.org/1999/xlink"><title></title>
<funcsynopsis>
<funcprototype>
<funcdef>
<link xlink:href="scalarDataTypes.html">int</link>
<function>printf</function>
</funcdef>
<paramdef>constant
<link xlink:href="scalarDataTypes.html">char</link>
* restrict<parameter>format</parameter>, ...
</paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<!-- ================================ PARAMETERS -->
<!-- ================================ DESCRIPTION -->
<refsect1 id="description"><title>Description</title>
<para>
The <function>printf</function> built-in function writes output to
an implementation-defined stream such as stdout under control of the
string pointed to by <varname>format</varname> 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 <function>printf</function>
function returns when the end of the format string is encountered.
</para>
</refsect1>
<!-- ================================ NOTES -->
<refsect1 id="notes"><title>Notes</title>
<para>
<function>printf</function> returns 0 if it was executed successfully
and -1 otherwise.
</para>
<bridgehead><function>printf</function> output synchronization</bridgehead>
<para>
When the event that is associated with a particular kernel invocation is completed,
the output of all <function>printf</function>() calls executed by this kernel
invocation is flushed to the implementation-defined output stream. Calling
<citerefentry><refentrytitle>clFinish</refentrytitle></citerefentry> on a command
queue flushes all pending output by <function>printf</function> in previously enqueued
and completed commands to the implementation-defined output stream. In the case that
<function>printf</function> 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.
</para>
<bridgehead><function>printf</function> format string</bridgehead>
<para>
The 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.
</para>
<para>
Each conversion specification is introduced by the character %. After the %, the
following appear in sequence:
</para>
<itemizedlist mark="disc">
<listitem>
Zero or more <varname>flags</varname> (in any order) that modify the meaning
of the conversion specification.
</listitem>
<listitem>
An optional minimum <varname>field width</varname>. 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.
</listitem>
<listitem>
An optional <varname>precision</varname> 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.
</listitem>
<listitem>
An optional <varname>vector specifier</varname>.
</listitem>
<listitem>
A <varname>length modifier</varname> that specifies the size of the argument. The
<varname>length modifier</varname> 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 <varname>vector specifier</varname> is not specified,
the <varname>length modifier</varname> is optional.
</listitem>
<listitem>
A <varname>conversion specifier</varname> character that specifies the type of
conversion to be applied.
</listitem>
</itemizedlist>
<para>
The flag characters and their meanings are:
</para>
<informaltable frame="all">
<tgroup cols="2" align="left" colsep="1" rowsep="1">
<colspec colname="col1" colnum="1" /> <colspec colname="col2" colnum="2" />
<tbody>
<row>
<entry><emphasis>-</emphasis></entry>
<entry>
The result of the conversion is left-justified within the field. (It
is right-justified if this flag is not specified.)
</entry>
</row>
<row>
<entry><emphasis>+</emphasis></entry>
<entry>
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.
</entry>
</row>
<row>
<entry><emphasis>space</emphasis></entry>
<entry>
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 <emphasis>space</emphasis> and + flags both appear,
the <varname>space</varname> flag is ignored.
</entry>
</row>
<row>
<entry><emphasis>#</emphasis></entry>
<entry>
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.
</entry>
</row>
<row>
<entry><emphasis>0</emphasis></entry>
<entry>
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 <emphasis>0</emphasis> and
<emphasis>-</emphasis> 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.
</entry>
</row>
</tbody>
</tgroup>
</informaltable>
<para>
The vector specifier and its meaning is:
</para>
<informaltable frame="all">
<tgroup cols="2" align="left" colsep="1" rowsep="1">
<colspec colname="col1" colnum="1" />
<colspec colname="col2" colnum="2" />
<tbody>
<row>
<entry>v<replaceable>n</replaceable></entry>
<entry>
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
<replaceable>n</replaceable> 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:
<para> value1 C value2 C ... C value<replaceable>n</replaceable> </para>
<para>
where C is a separator character. The value for this separator
character is a comma.
</para>
</entry>
</row>
</tbody>
</tgroup>
</informaltable>
<para>
If the vector specifier is not used, the length modifiers and their meanings are:
</para>
<informaltable frame="all">
<tgroup cols="2" align="left" colsep="1" rowsep="1">
<colspec colname="col1" colnum="1" />
<colspec colname="col2" colnum="2" />
<tbody>
<row>
<entry>hh</entry>
<entry>
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
<type>char</type> or <type>uchar</type> before printing).
</entry>
</row>
<row>
<entry>h</entry>
<entry>
Specifies that a following d, i, o, u, x, or X conversion specifier
applies to a <type>short</type> or <type>ushort</type> argument (the
argument will have been promoted according to the integer promotions,
but its value shall be converted to <type>short</type> or <type>unsigned
short</type> before printing).
</entry>
</row>
<row>
<entry>l (ell)</entry>
<entry>
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.
</entry>
</row>
</tbody>
</tgroup>
</informaltable>
<para>
If the vector specifier is used, the length modifiers and their meanings are:
</para>
<informaltable frame="all">
<tgroup cols="2" align="left" colsep="1" rowsep="1">
<colspec colname="col1" colnum="1" />
<colspec colname="col2" colnum="2" />
<tbody>
<row>
<entry>hh</entry>
<entry>
Specifies that a following d, i, o, u, x, or X conversion
specifier applies to a char<replaceable>n</replaceable> or
uchar<replaceable>n</replaceable> argument (the argument will not
be promoted).
</entry>
</row>
<row>
<entry>h</entry>
<entry>
Specifies that a following d, i, o, u, x, or X conversion
specifier applies to a short<replaceable>n</replaceable> or
ushort<replaceable>n</replaceable> argument (the argument will not
be promoted); that a following a, A, e, E, f, F, g, or G conversion
specifier applies to a half<replaceable>n</replaceable> argument if the
<citerefentry><refentrytitle>cl_khr_fp16</refentrytitle></citerefentry>
extension is supported.
</entry>
</row>
<row>
<entry>hl</entry>
<entry>
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
int<replaceable>n</replaceable> or uint<replaceable>n</replaceable>
argument; that a following a, A, e, E, f, F, g, or G conversion
specifier applies to a float<replaceable>n</replaceable> argument.
</entry>
</row>
<row>
<entry>l (ell)</entry>
<entry>
Specifies that a following d, i, o, u, x, or X conversion
specifier applies to a long<replaceable>n</replaceable> or
ulong<replaceable>n</replaceable> argument; that a following
a, A, e, E, f, F, g, or G conversion specifier applies to
a double<replaceable>n</replaceable> 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.
</entry>
</row>
</tbody>
</tgroup>
</informaltable>
<para>
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.
</para>
<para>
If a length modifier appears with any conversion specifier other than as specified
above, the behavior is undefined
</para>
<para>
The conversion specifiers and their meanings are:
</para>
<informaltable frame="all">
<tgroup cols="2" align="left" colsep="1" rowsep="1">
<colspec colname="col1" colnum="1" />
<colspec colname="col2" colnum="2" />
<tbody>
<row>
<entry>d,i</entry>
<entry>
The int, char<replaceable>n</replaceable>,
short<replaceable>n</replaceable>, int<replaceable>n</replaceable>
or long<replaceable>n</replaceable> argument is converted to signed
decimal in the style <emphasis>[−]dddd</emphasis>. 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.
</entry>
</row>
<row>
<entry>o,u,x,X</entry>
<entry>
The unsigned int, uchar<replaceable>n</replaceable>,
ushort<replaceable>n</replaceable>, uint<replaceable>n</replaceable>
or ulong<replaceable>n</replaceable> argument is converted to unsigned
octal (o), unsigned decimal (u), or unsigned hexadecimal notation (x
or X) in the style <emphasis>dddd</emphasis>; 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.
</entry>
</row>
<row>
<entry>f,F</entry>
<entry>
A double, half<replaceable>n</replaceable>,
float<replaceable>n</replaceable> or double<replaceable>n</replaceable>
argument representing a floating-point number is converted to decimal
notation in the style <replaceable>[−]ddd.ddd</replaceable>,
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,
half<replaceable>n</replaceable>, float<replaceable>n</replaceable>
or double<replaceable>n</replaceable> argument representing an infinity
is converted in one of the styles [-]inf or [-]infinity — which style
is implementation-defined. A double, half<replaceable>n</replaceable>,
float<replaceable>n</replaceable> or double<replaceable>n</replaceable>
argument representing a NaN is converted in one of the styles [-
]nan or [-]nan(<replaceable>n-char-sequence</replaceable>) — 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 <replaceable>space</replaceable> flag characters have their
usual meaning; the # and 0 flag characters have no effect.
</entry>
</row>
<row>
<entry>e,E</entry>
<entry>
A double, half<replaceable>n</replaceable>,
float<replaceable>n</replaceable> or double<replaceable>n</replaceable>
argument representing a floating-point number is converted in the style
<replaceable>[−]d.ddd</replaceable> e±<replaceable>dd</replaceable>,
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,
half<replaceable>n</replaceable>, float<replaceable>n</replaceable>
or double<replaceable>n</replaceable> argument representing an infinity
or NaN is converted in the style of an f or F conversion specifier
</entry>
</row>
<row>
<entry>g,G</entry>
<entry>
A double, half<replaceable>n</replaceable>,
float<replaceable>n</replaceable> or double<replaceable>n</replaceable>
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
<replaceable>P</replaceable> 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 <varname>X</varname>:
— if <varname>P</varname> > <varname>X</varname> ≥ −4, the
conversion is with style f (or F) and precision <varname>P</varname>
− (<varname>X</varname> + 1). — otherwise, the conversion is with
style e (or E) and precision <varname>P</varname> − 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,
half<replaceable>n</replaceable>, float<replaceable>n</replaceable> or
double<replaceable>n</replaceable> e argument representing an infinity
or NaN is converted in the style of an f or F conversion specifier.
</entry>
</row>
<row>
<entry>a,A</entry>
<entry>
A double, half<replaceable>n</replaceable>,
float<replaceable>n</replaceable> or double<replaceable>n</replaceable>
argument representing a floating-point number is converted in the style
<replaceable>[−]0xh.hhhh</replaceable> p±<replaceable>d</replaceable>,
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, half<replaceable>n</replaceable>,
float<replaceable>n</replaceable> or double<replaceable>n</replaceable>
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.
</entry>
</row>
</tbody>
</tgroup>
</informaltable>
<para>
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.
</para>
<informaltable frame="all">
<tgroup cols="2" align="left" colsep="1" rowsep="1">
<colspec colname="col1" colnum="1" />
<colspec colname="col2" colnum="2" />
<tbody>
<row>
<entry>c</entry>
<entry>
The int argument is converted to an unsigned char, and the resulting character is written.
</entry>
</row>
<row>
<entry>s</entry>
<entry>
The argument shall be a literal string. No special provisions are made
for multibyte characters. The behavior of <function>printf</function>
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.
</entry>
</row>
<row>
<entry>p</entry>
<entry>
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.
</entry>
</row>
<row>
<entry>%</entry>
<entry>
A % character is written. No argument is converted. The complete conversion
specification shall be %%.
</entry>
</row>
</tbody>
</tgroup>
</informaltable>
<para>
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.
</para>
<para>
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.
</para>
<para>
For a and A conversions, the value is correctly rounded to a hexadecimal floating
number with the given precision.
</para>
<bridgehead>Differences between OpenCL C and C99 <function>printf</function></bridgehead>
<itemizedlist mark="disc">
<listitem>
The l modifier followed by a c conversion specifier or s conversion specifier
is not supported by OpenCL C.
</listitem>
<listitem>
The ll, j, z, t, and L length modifiers are not supported by OpenCL C.
</listitem>
<listitem>
The n conversion specifier is not supported by OpenCL C but is reserved.
</listitem>
<listitem>
OpenCL C adds the optional v<replaceable>n</replaceable> vector specifier to support printing of vector types.
</listitem>
<listitem>
The conversion specifiers f, F, e, E, g, G, a, A convert a float argument to
a double only if the double data type is supported. Refer to the description
of <constant>CL_DEVICE_DOUBLE_FP_CONFIG</constant>. If the double data type is
not supported, the argument will be a float instead of a double.
</listitem>
<listitem>
For the embedded profile, the l length modifier is supported only if 64-bit integers are supported.
</listitem>
<listitem>
In OpenCL C, <function>printf</function> returns 0 if it was executed successfully
and -1 otherwise vs. C99 where <function>printf</function> returns the number
of characters printed or a negative value if an output or encoding error occurred.
</listitem>
<listitem>
In OpenCL C, the conversion specifier s can only be used for arguments that are literal strings.
</listitem>
</itemizedlist>
</refsect1>
<!-- ================================ EXAMPLE -->
<!-- DO NOT DELETE IN CASE AN EXAMPLE IS ADDED IN THE FUTURE -->
<!-- -->
<refsect2 id="example1">
<title>
Examples
</title>
<informaltable frame="none">
<tgroup cols="1" align="left" colsep="0" rowsep="0">
<colspec colname="col1" colnum="1" />
<tbody>
<row>
<entry>
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
</entry>
</row>
</tbody>
</tgroup>
</informaltable>
<para>
A few examples of valid use cases of <function>printf</function> for the conversion
specifier s are given below. The argument value must be a pointer to a literal string.
</para>
<informaltable frame="none">
<tgroup cols="1" align="left" colsep="0" rowsep="0">
<colspec colname="col1" colnum="1" />
<tbody>
<row>
<entry>
kernel void my_kernel( ... )
{
printf("%s\n", "this is a test string\n");
}
</entry>
</row>
</tbody>
</tgroup>
</informaltable>
<para>
A few examples of invalid use cases of <function>printf</function> for the conversion
specifier s are given below:
</para>
<informaltable frame="none">
<tgroup cols="1" align="left" colsep="0" rowsep="0">
<colspec colname="col1" colnum="1" />
<tbody>
<row>
<entry>
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]);
}
</entry>
</row>
</tbody>
</tgroup>
</informaltable>
<para>
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:
</para>
<informaltable frame="none">
<tgroup cols="1" align="left" colsep="0" rowsep="0">
<colspec colname="col1" colnum="1" />
<tbody>
<row>
<entry>
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)
}
</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</refsect2>
<!-- ================================ SPECIFICATION -->
<!-- Set the "uri" attribute in the <olink /> element to the "named destination" for the PDF page
-->
<refsect1 id="specification"><title>Specification</title>
<para>
<imageobject>
<imagedata fileref="pdficon_small1.gif" format="gif" />
</imageobject>
<olink uri="printfFunction">OpenCL Specification</olink>
</para>
</refsect1>
<!-- ================================ ALSO SEE
<refsect1 id="seealso"><title>Also see</title>
<para>
<citerefentry><refentrytitle>clFlush</refentrytitle></citerefentry>
</para>
</refsect1>-->
<!-- ================================ COPYRIGHT -->
<!-- Content included from copyright.inc.xsl -->
<refsect3 id="Copyright"><title></title>
<imageobject>
<imagedata fileref="KhronosLogo.jpg" format="jpg" />
</imageobject>
<para />
</refsect3>
<!-- 11-Nov-2011 -->
</refentry>
|
