| <?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.0-openclc.pdf#namedest=printfFunction" 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> |
