| <?xml version="1.0" encoding="UTF-8"?> | |
| <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "xhtml1-transitional.dtd"> | |
| <!-- saved from url=(0013)about:internet --> | |
| <?xml-stylesheet type="text/xsl" href="mathml.xsl"?><html xmlns="http://www.w3.org/1999/xhtml" xmlns:pref="http://www.w3.org/2002/Math/preference" xmlns:xlink="http://www.w3.org/1999/xlink" pref:renderer="mathplayer-dl"> | |
| <head> | |
| <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /> | |
| <style xmlns="" type="text/css"> | |
| /* This style sets a margin around the entire page */ | |
| html, body { | |
| margin: 10px; | |
| } | |
| p { | |
| font: normal 16px verdana, sans-serif; | |
| margin: 0; | |
| padding-bottom:12px; | |
| } | |
| h1 { | |
| font: bold 25px verdana, sans-serif; | |
| margin-top: 0; | |
| margin-bottom: 3px; | |
| padding-top: 0; | |
| padding-bottom: 0; | |
| } | |
| h2 { | |
| font: bold 19px verdana, sans-serif; | |
| margin-top: 28px; | |
| margin-bottom: 3px; | |
| padding-top: 0; | |
| padding-bottom: 0; | |
| } | |
| h3 { | |
| font: bold 19px verdana, sans-serif !important; | |
| margin-top: 28px; | |
| margin-bottom: 3px; | |
| padding-top: 0; | |
| padding-bottom: 0; | |
| } | |
| li { | |
| font: normal 16px verdana, sans-serif; | |
| margin-top: 0; | |
| margin-bottom: 18px; | |
| padding-top: 0; | |
| padding-bottom: 0; | |
| } | |
| .pdparam { | |
| font: italic 16px verdana, sans-serif; | |
| } | |
| .term { | |
| font: italic 16px verdana, sans-serif; | |
| font-weight: normal; | |
| } | |
| .type { | |
| font: normal 16px verdana, sans-serif !important; | |
| } | |
| .parameter { | |
| font-style: italic; | |
| } | |
| a:link, a:visited { | |
| color: blue; | |
| text-decoration: none; | |
| font: normal 16px; | |
| } | |
| a:hover { | |
| background-color: #FFFF99; | |
| font: normal 16px; | |
| } | |
| div.funcsynopsis { | |
| text-align: left; | |
| background-color: #e6e6e6; | |
| font: normal 16px verdana, sans-serif; | |
| padding-top: 10px; | |
| padding-bottom: 10px; | |
| } | |
| div.funcsynopsis table { | |
| border-collapse: separate; | |
| font: normal 16px verdana, sans-serif; | |
| } | |
| div.funcsynopsis td { | |
| background-color: #e6e6e6; | |
| border: 0 solid #000; | |
| padding: 1px; | |
| font: normal 16px verdana, sans-serif; | |
| } | |
| div.refsect1 { | |
| font-family: verdana, sans-serif; | |
| font-size: 16px; | |
| } | |
| code.constant { | |
| font: normal 16px courier new, monospace !important; | |
| } | |
| span.errorname { | |
| font: normal 16px verdana, sans-serif !important; | |
| } | |
| code.function { | |
| font: bold 16px verdana, sans-serif !important; | |
| } | |
| b.fsfunc { | |
| font: bold 16px verdana, sans-serif !important; | |
| } | |
| code.varname { | |
| font: italic 16px verdana, sans-serif; | |
| } | |
| code.replaceable { | |
| font: italic 16px courier new, monospace; | |
| } | |
| code.funcdef { | |
| font: normal 16px verdana, sans-serif !important; | |
| } | |
| .citerefentry { | |
| font: normal 16px verdana, sans-serif !important; | |
| } | |
| .parameter { | |
| font-style: italic; | |
| } | |
| code.fsfunc { | |
| font: normal 16px verdana, sans-serif !important; | |
| } | |
| /* PARAMETER: This style controls spacing between the terms in Parameter section */ | |
| dt { | |
| margin-top: 15px; | |
| } | |
| /* TABLES: These styles apply to all tables OTHER than the Synopsis and Example tables */ | |
| div.refsect1 table { | |
| width: 100%; | |
| margin-top: 10px; | |
| background-color: #FFF; | |
| border-collapse: collapse; | |
| border-color: #000; | |
| border-width: 1px; | |
| font: normal 16px verdana, sans-serif; | |
| } | |
| div.refsect1 th { | |
| border-collapse: collapse; | |
| border-color: #000; | |
| border-width: 1px; | |
| font: bold 16px verdana, sans-serif; | |
| } | |
| div.refsect1 td { | |
| background-color: #FFF; | |
| padding: 5px; | |
| vertical-align: text-top; | |
| border-collapse: collapse; | |
| border-color: #000; | |
| border-width: 1px; | |
| font: normal 16px verdana, sans-serif; | |
| } | |
| div.refsect1 p{ | |
| font: normal 16px verdana, sans-serif; | |
| margin-top: 8px; | |
| margin-bottom: 8px; | |
| padding-top: 0; | |
| padding-bottom: 0; | |
| } | |
| /* EXAMPLE: These styles apply only to the Example section */ | |
| div.refsect2 { | |
| font: normal 16px courier new, monospace !important; | |
| } | |
| div.refsect2 table { | |
| margin-top: 0; | |
| background-color: #e6e6e6; | |
| width: 100%; | |
| border: 0 solid #000; | |
| padding: 2px; | |
| font: normal 16px courier new, monospace !important; | |
| } | |
| div.refsect2 td { | |
| background-color: #e6e6e6; | |
| font: normal 16px courier new, monospace !important; | |
| white-space:pre; | |
| } | |
| /* COPYRIGHT: This style formats the text of the copyright statement at the bottom of the page */ | |
| div.refsect3 { | |
| font: normal 11px verdana, sans-serif; | |
| margin-top: 50px; | |
| margin-bottom: 20px; | |
| padding-top: 0; | |
| padding-bottom: 0; | |
| } | |
| </style> | |
| <title>printf Function</title> | |
| <meta name="generator" content="DocBook XSL Stylesheets V1.79.1" /> | |
| <meta name="keywords" content="printf Function" /> | |
| </head> | |
| <body> | |
| <div class="refentry"> | |
| <a id="id-1"></a> | |
| <div class="titlepage"></div> | |
| <div xmlns="" class="refnamediv"> | |
| <a xmlns="http://www.w3.org/1999/xhtml" id="printfFunction"></a> | |
| <h1> | |
| printf Function | |
| </h1> | |
| <p> | |
| The OpenCL C programming language implements the <code xmlns="http://www.w3.org/1999/xhtml" class="function">printf</code> function. | |
| </p> | |
| </div> | |
| <div class="refsynopsisdiv"> | |
| <h2></h2> | |
| <div class="funcsynopsis"> | |
| <table xmlns="" border="0" summary="Function synopsis" cellspacing="0" cellpadding="0"> | |
| <tr valign="bottom"> | |
| <td> | |
| <code xmlns="http://www.w3.org/1999/xhtml" class="funcdef"> | |
| <a class="link" href="scalarDataTypes.html" target="pagedisplay">int</a> | |
| <strong class="fsfunc">printf</strong> | |
| (</code> | |
| <td>constant | |
| <a xmlns="http://www.w3.org/1999/xhtml" class="link" href="scalarDataTypes.html" target="pagedisplay">char</a> | |
| * restrict <var xmlns="http://www.w3.org/1999/xhtml" class="pdparam">format</var>, ... | |
| <code>)</code></td> | |
| </td> | |
| </tr> | |
| </table> | |
| </div> | |
| </div> | |
| <div class="refsect1"> | |
| <a id="description"></a> | |
| <h2>Description</h2> | |
| <p> | |
| The <code class="function">printf</code> built-in function writes output to | |
| an implementation-defined stream such as stdout under control of the | |
| string pointed to by <code class="varname">format</code> 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 <code class="function">printf</code> | |
| function returns when the end of the format string is encountered. | |
| </p> | |
| </div> | |
| <div class="refsect1"> | |
| <a id="notes"></a> | |
| <h2>Notes</h2> | |
| <p> | |
| <code class="function">printf</code> returns 0 if it was executed successfully | |
| and -1 otherwise. | |
| </p> | |
| <h4><a id="id-1.6.3"></a><code class="function">printf</code> output synchronization</h4> | |
| <p> | |
| When the event that is associated with a particular kernel invocation is completed, | |
| the output of all <code class="function">printf</code>() calls executed by this kernel | |
| invocation is flushed to the implementation-defined output stream. Calling | |
| <a class="citerefentry" href="clFinish.html"><span class="citerefentry"><span class="refentrytitle">clFinish</span></span></a> on a command | |
| queue flushes all pending output by <code class="function">printf</code> in previously enqueued | |
| and completed commands to the implementation-defined output stream. In the case that | |
| <code class="function">printf</code> 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. | |
| </p> | |
| <h4><a id="id-1.6.5"></a><code class="function">printf</code> format string</h4> | |
| <p> | |
| 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. | |
| </p> | |
| <p> | |
| Each conversion specification is introduced by the character %. After the %, the | |
| following appear in sequence: | |
| </p> | |
| <div class="itemizedlist"> | |
| <ul class="itemizedlist" style="list-style-type: disc; "> | |
| <li class="listitem" style="list-style-type: disc"> | |
| Zero or more <code class="varname">flags</code> (in any order) that modify the meaning | |
| of the conversion specification. | |
| </li> | |
| <li class="listitem" style="list-style-type: disc"> | |
| An optional minimum <code class="varname">field width</code>. 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. | |
| </li> | |
| <li class="listitem" style="list-style-type: disc"> | |
| An optional <code class="varname">precision</code> 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. | |
| </li> | |
| <li class="listitem" style="list-style-type: disc"> | |
| An optional <code class="varname">vector specifier</code>. | |
| </li> | |
| <li class="listitem" style="list-style-type: disc"> | |
| A <code class="varname">length modifier</code> that specifies the size of the argument. The | |
| <code class="varname">length modifier</code> 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 <code class="varname">vector specifier</code> is not specified, | |
| the <code class="varname">length modifier</code> is optional. | |
| </li> | |
| <li class="listitem" style="list-style-type: disc"> | |
| A <code class="varname">conversion specifier</code> character that specifies the type of | |
| conversion to be applied. | |
| </li> | |
| </ul> | |
| </div> | |
| <p> | |
| The flag characters and their meanings are: | |
| </p> | |
| <div class="informaltable"> | |
| <table class="informaltable" border="1"> | |
| <colgroup> | |
| <col align="left" class="col1" /> | |
| <col align="left" class="col2" /> | |
| </colgroup> | |
| <tbody> | |
| <tr> | |
| <td align="left"> | |
| <span class="emphasis"> | |
| <em>-</em> | |
| </span> | |
| </td> | |
| <td align="left"> | |
| The result of the conversion is left-justified within the field. (It | |
| is right-justified if this flag is not specified.) | |
| </td> | |
| </tr> | |
| <tr> | |
| <td align="left"> | |
| <span class="emphasis"> | |
| <em>+</em> | |
| </span> | |
| </td> | |
| <td align="left"> | |
| 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. | |
| </td> | |
| </tr> | |
| <tr> | |
| <td align="left"> | |
| <span class="emphasis"> | |
| <em>space</em> | |
| </span> | |
| </td> | |
| <td align="left"> | |
| 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 <span class="emphasis"><em>space</em></span> and + flags both appear, | |
| the <code class="varname">space</code> flag is ignored. | |
| </td> | |
| </tr> | |
| <tr> | |
| <td align="left"> | |
| <span class="emphasis"> | |
| <em>#</em> | |
| </span> | |
| </td> | |
| <td align="left"> | |
| The result is converted to an "alternative form". For <span class="emphasis"><em>o</em></span> 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. | |
| </td> | |
| </tr> | |
| <tr> | |
| <td align="left"> | |
| <span class="emphasis"> | |
| <em>0</em> | |
| </span> | |
| </td> | |
| <td align="left"> | |
| 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 <span class="emphasis"><em>0</em></span> and | |
| <span class="emphasis"><em>-</em></span> 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. | |
| </td> | |
| </tr> | |
| </tbody> | |
| </table> | |
| </div> | |
| <p> | |
| The vector specifier and its meaning is: | |
| </p> | |
| <div class="informaltable"> | |
| <table class="informaltable" border="1"> | |
| <colgroup> | |
| <col align="left" class="col1" /> | |
| <col align="left" class="col2" /> | |
| </colgroup> | |
| <tbody> | |
| <tr> | |
| <td align="left">v<em class="replaceable"><code>n</code></em></td> | |
| <td align="left"> | |
| 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 | |
| <em class="replaceable"><code>n</code></em> 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: | |
| <p> value1 C value2 C ... C value<em class="replaceable"><code>n</code></em> </p> | |
| <p> | |
| where C is a separator character. The value for this separator | |
| character is a comma. | |
| </p> | |
| </td> | |
| </tr> | |
| </tbody> | |
| </table> | |
| </div> | |
| <p> | |
| If the vector specifier is not used, the length modifiers and their meanings are: | |
| </p> | |
| <div class="informaltable"> | |
| <table class="informaltable" border="1"> | |
| <colgroup> | |
| <col align="left" class="col1" /> | |
| <col align="left" class="col2" /> | |
| </colgroup> | |
| <tbody> | |
| <tr> | |
| <td align="left">hh</td> | |
| <td align="left"> | |
| 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 | |
| <span class="type">char</span> or <span class="type">uchar</span> before printing). | |
| </td> | |
| </tr> | |
| <tr> | |
| <td align="left">h</td> | |
| <td align="left"> | |
| Specifies that a following d, i, o, u, x, or X conversion specifier | |
| applies to a <span class="type">short</span> or <span class="type">ushort</span> argument (the | |
| argument will have been promoted according to the integer promotions, | |
| but its value shall be converted to <span class="type">short</span> or <span class="type">unsigned | |
| short</span> before printing). | |
| </td> | |
| </tr> | |
| <tr> | |
| <td align="left">l (ell)</td> | |
| <td align="left"> | |
| 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. | |
| </td> | |
| </tr> | |
| </tbody> | |
| </table> | |
| </div> | |
| <p> | |
| If the vector specifier is used, the length modifiers and their meanings are: | |
| </p> | |
| <div class="informaltable"> | |
| <table class="informaltable" border="1"> | |
| <colgroup> | |
| <col align="left" class="col1" /> | |
| <col align="left" class="col2" /> | |
| </colgroup> | |
| <tbody> | |
| <tr> | |
| <td align="left">hh</td> | |
| <td align="left"> | |
| Specifies that a following d, i, o, u, x, or X conversion | |
| specifier applies to a char<em class="replaceable"><code>n</code></em> or | |
| uchar<em class="replaceable"><code>n</code></em> argument (the argument will not | |
| be promoted). | |
| </td> | |
| </tr> | |
| <tr> | |
| <td align="left">h</td> | |
| <td align="left"> | |
| Specifies that a following d, i, o, u, x, or X conversion | |
| specifier applies to a short<em class="replaceable"><code>n</code></em> or | |
| ushort<em class="replaceable"><code>n</code></em> 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<em class="replaceable"><code>n</code></em> argument if the | |
| <a class="citerefentry" href="cl_khr_fp16.html"><span class="citerefentry"><span class="refentrytitle">cl_khr_fp16</span></span></a> | |
| extension is supported. | |
| </td> | |
| </tr> | |
| <tr> | |
| <td align="left">hl</td> | |
| <td align="left"> | |
| 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<em class="replaceable"><code>n</code></em> or uint<em class="replaceable"><code>n</code></em> | |
| argument; that a following a, A, e, E, f, F, g, or G conversion | |
| specifier applies to a float<em class="replaceable"><code>n</code></em> argument. | |
| </td> | |
| </tr> | |
| <tr> | |
| <td align="left">l (ell)</td> | |
| <td align="left"> | |
| Specifies that a following d, i, o, u, x, or X conversion | |
| specifier applies to a long<em class="replaceable"><code>n</code></em> or | |
| ulong<em class="replaceable"><code>n</code></em> argument; that a following | |
| a, A, e, E, f, F, g, or G conversion specifier applies to | |
| a double<em class="replaceable"><code>n</code></em> 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. | |
| </td> | |
| </tr> | |
| </tbody> | |
| </table> | |
| </div> | |
| <p> | |
| 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. | |
| </p> | |
| <p> | |
| If a length modifier appears with any conversion specifier other than as specified | |
| above, the behavior is undefined | |
| </p> | |
| <p> | |
| The conversion specifiers and their meanings are: | |
| </p> | |
| <div class="informaltable"> | |
| <table class="informaltable" border="1"> | |
| <colgroup> | |
| <col align="left" class="col1" /> | |
| <col align="left" class="col2" /> | |
| </colgroup> | |
| <tbody> | |
| <tr> | |
| <td align="left">d,i</td> | |
| <td align="left"> | |
| The int, char<em class="replaceable"><code>n</code></em>, | |
| short<em class="replaceable"><code>n</code></em>, int<em class="replaceable"><code>n</code></em> | |
| or long<em class="replaceable"><code>n</code></em> argument is converted to signed | |
| decimal in the style <span class="emphasis"><em>[−]dddd</em></span>. 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. | |
| </td> | |
| </tr> | |
| <tr> | |
| <td align="left">o,u,x,X</td> | |
| <td align="left"> | |
| The unsigned int, uchar<em class="replaceable"><code>n</code></em>, | |
| ushort<em class="replaceable"><code>n</code></em>, uint<em class="replaceable"><code>n</code></em> | |
| or ulong<em class="replaceable"><code>n</code></em> argument is converted to unsigned | |
| octal (o), unsigned decimal (u), or unsigned hexadecimal notation (x | |
| or X) in the style <span class="emphasis"><em>dddd</em></span>; 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. | |
| </td> | |
| </tr> | |
| <tr> | |
| <td align="left">f,F</td> | |
| <td align="left"> | |
| A double, half<em class="replaceable"><code>n</code></em>, | |
| float<em class="replaceable"><code>n</code></em> or double<em class="replaceable"><code>n</code></em> | |
| argument representing a floating-point number is converted to decimal | |
| notation in the style <em class="replaceable"><code>[−]ddd.ddd</code></em>, | |
| 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<em class="replaceable"><code>n</code></em>, float<em class="replaceable"><code>n</code></em> | |
| or double<em class="replaceable"><code>n</code></em> argument representing an infinity | |
| is converted in one of the styles [-]inf or [-]infinity — which style | |
| is implementation-defined. A double, half<em class="replaceable"><code>n</code></em>, | |
| float<em class="replaceable"><code>n</code></em> or double<em class="replaceable"><code>n</code></em> | |
| argument representing a NaN is converted in one of the styles [- | |
| ]nan or [-]nan(<em class="replaceable"><code>n-char-sequence</code></em>) — 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 <em class="replaceable"><code>space</code></em> flag characters have their | |
| usual meaning; the # and 0 flag characters have no effect. | |
| </td> | |
| </tr> | |
| <tr> | |
| <td align="left">e,E</td> | |
| <td align="left"> | |
| A double, half<em class="replaceable"><code>n</code></em>, | |
| float<em class="replaceable"><code>n</code></em> or double<em class="replaceable"><code>n</code></em> | |
| argument representing a floating-point number is converted in the style | |
| <em class="replaceable"><code>[−]d.ddd</code></em> e±<em class="replaceable"><code>dd</code></em>, | |
| 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<em class="replaceable"><code>n</code></em>, float<em class="replaceable"><code>n</code></em> | |
| or double<em class="replaceable"><code>n</code></em> argument representing an infinity | |
| or NaN is converted in the style of an f or F conversion specifier | |
| </td> | |
| </tr> | |
| <tr> | |
| <td align="left">g,G</td> | |
| <td align="left"> | |
| A double, half<em class="replaceable"><code>n</code></em>, | |
| float<em class="replaceable"><code>n</code></em> or double<em class="replaceable"><code>n</code></em> | |
| 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 | |
| <em class="replaceable"><code>P</code></em> 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 <code class="varname">X</code>: | |
| — if <code class="varname">P</code> > <code class="varname">X</code> ≥ −4, the | |
| conversion is with style f (or F) and precision <code class="varname">P</code> | |
| − (<code class="varname">X</code> + 1). — otherwise, the conversion is with | |
| style e (or E) and precision <code class="varname">P</code> − 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<em class="replaceable"><code>n</code></em>, float<em class="replaceable"><code>n</code></em> or | |
| double<em class="replaceable"><code>n</code></em> e argument representing an infinity | |
| or NaN is converted in the style of an f or F conversion specifier. | |
| </td> | |
| </tr> | |
| <tr> | |
| <td align="left">a,A</td> | |
| <td align="left"> | |
| A double, half<em class="replaceable"><code>n</code></em>, | |
| float<em class="replaceable"><code>n</code></em> or double<em class="replaceable"><code>n</code></em> | |
| argument representing a floating-point number is converted in the style | |
| <em class="replaceable"><code>[−]0xh.hhhh</code></em> p±<em class="replaceable"><code>d</code></em>, | |
| 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<em class="replaceable"><code>n</code></em>, | |
| float<em class="replaceable"><code>n</code></em> or double<em class="replaceable"><code>n</code></em> | |
| 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. | |
| </td> | |
| </tr> | |
| </tbody> | |
| </table> | |
| </div> | |
| <p> | |
| 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. | |
| </p> | |
| <div class="informaltable"> | |
| <table class="informaltable" border="1"> | |
| <colgroup> | |
| <col align="left" class="col1" /> | |
| <col align="left" class="col2" /> | |
| </colgroup> | |
| <tbody> | |
| <tr> | |
| <td align="left">c</td> | |
| <td align="left"> | |
| The int argument is converted to an unsigned char, and the resulting character is written. | |
| </td> | |
| </tr> | |
| <tr> | |
| <td align="left">s</td> | |
| <td align="left"> | |
| The argument shall be a literal string. No special provisions are made | |
| for multibyte characters. The behavior of <code class="function">printf</code> | |
| 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. | |
| </td> | |
| </tr> | |
| <tr> | |
| <td align="left">p</td> | |
| <td align="left"> | |
| 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. | |
| </td> | |
| </tr> | |
| <tr> | |
| <td align="left">%</td> | |
| <td align="left"> | |
| A % character is written. No argument is converted. The complete conversion | |
| specification shall be %%. | |
| </td> | |
| </tr> | |
| </tbody> | |
| </table> | |
| </div> | |
| <p> | |
| 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. | |
| </p> | |
| <p> | |
| 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. | |
| </p> | |
| <p> | |
| For a and A conversions, the value is correctly rounded to a hexadecimal floating | |
| number with the given precision. | |
| </p> | |
| <h4><a id="id-1.6.26"></a>Differences between OpenCL C and C99 <code class="function">printf</code></h4> | |
| <div class="itemizedlist"> | |
| <ul class="itemizedlist" style="list-style-type: disc; "> | |
| <li class="listitem" style="list-style-type: disc"> | |
| The l modifier followed by a c conversion specifier or s conversion specifier | |
| is not supported by OpenCL C. | |
| </li> | |
| <li class="listitem" style="list-style-type: disc"> | |
| The ll, j, z, t, and L length modifiers are not supported by OpenCL C but are reserved. | |
| </li> | |
| <li class="listitem" style="list-style-type: disc"> | |
| The n conversion specifier is not supported by OpenCL C but is reserved. | |
| </li> | |
| <li class="listitem" style="list-style-type: disc"> | |
| OpenCL C adds the optional v<em class="replaceable"><code>n</code></em> vector specifier to support printing of vector types. | |
| </li> | |
| <li class="listitem" style="list-style-type: disc"> | |
| 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 <code class="constant">CL_DEVICE_DOUBLE_FP_CONFIG</code>. If the double data type is | |
| not supported, the argument will be a float instead of a double. | |
| </li> | |
| <li class="listitem" style="list-style-type: disc"> | |
| For the embedded profile, the l length modifier is supported only if 64-bit integers are supported. | |
| </li> | |
| <li class="listitem" style="list-style-type: disc"> | |
| In OpenCL C, <code class="function">printf</code> returns 0 if it was executed successfully | |
| and -1 otherwise vs. C99 where <code class="function">printf</code> returns the number | |
| of characters printed or a negative value if an output or encoding error occurred. | |
| </li> | |
| <li class="listitem" style="list-style-type: disc"> | |
| In OpenCL C, the conversion specifier s can only be used for arguments that are literal strings. | |
| </li> | |
| </ul> | |
| </div> | |
| </div> | |
| <div class="refsect2"> | |
| <a id="example1"></a> | |
| <h3> | |
| Examples | |
| </h3> | |
| <div class="informaltable"> | |
| <table class="informaltable" border="0"> | |
| <colgroup> | |
| <col align="left" class="col1" /> | |
| </colgroup> | |
| <tbody> | |
| <tr> | |
| <td align="left"> | |
| 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 | |
| </td> | |
| </tr> | |
| </tbody> | |
| </table> | |
| </div> | |
| <p> | |
| A few examples of valid use cases of <code class="function">printf</code> for the conversion | |
| specifier s are given below. The argument value must be a pointer to a literal string. | |
| </p> | |
| <div class="informaltable"> | |
| <table class="informaltable" border="0"> | |
| <colgroup> | |
| <col align="left" class="col1" /> | |
| </colgroup> | |
| <tbody> | |
| <tr> | |
| <td align="left"> | |
| kernel void my_kernel( ... ) | |
| { | |
| printf("%s\n", "this is a test string\n"); | |
| } | |
| </td> | |
| </tr> | |
| </tbody> | |
| </table> | |
| </div> | |
| <p> | |
| A few examples of invalid use cases of <code class="function">printf</code> for the conversion | |
| specifier s are given below: | |
| </p> | |
| <div class="informaltable"> | |
| <table class="informaltable" border="0"> | |
| <colgroup> | |
| <col align="left" class="col1" /> | |
| </colgroup> | |
| <tbody> | |
| <tr> | |
| <td align="left"> | |
| 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]); | |
| } | |
| </td> | |
| </tr> | |
| </tbody> | |
| </table> | |
| </div> | |
| <p> | |
| 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: | |
| </p> | |
| <div class="informaltable"> | |
| <table class="informaltable" border="0"> | |
| <colgroup> | |
| <col align="left" class="col1" /> | |
| </colgroup> | |
| <tbody> | |
| <tr> | |
| <td align="left"> | |
| 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) | |
| } | |
| </td> | |
| </tr> | |
| </tbody> | |
| </table> | |
| </div> | |
| </div> | |
| <div class="refsect1"> | |
| <a id="specification"></a> | |
| <h2>Specification</h2> | |
| <p> | |
| <img src="pdficon_small1.gif" /> | |
| <a href="https://www.khronos.org/registry/cl/specs/opencl-2.1-openclc.pdf#page=115" target="OpenCL Spec">OpenCL Specification</a> | |
| </p> | |
| </div> | |
| <div xmlns="" class="refsect3" lang="en" xml:lang="en"><a xmlns="http://www.w3.org/1999/xhtml" id="Copyright"></a><h4 xmlns="http://www.w3.org/1999/xhtml"></h4><img xmlns="http://www.w3.org/1999/xhtml" src="KhronosLogo.jpg" /><p xmlns="http://www.w3.org/1999/xhtml"></p>Copyright © 2007-2015 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. | |
| </div> | |
| </div> | |
| </body> | |
| </html> |