<?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> &gt; <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", &amp;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>