coreutils: printf invocation

1 
1 15.2 ‘printf’: Format and print data
1 ====================================
1 
1 ‘printf’ does formatted printing of text.  Synopsis:
1 
1      printf FORMAT [ARGUMENT]...
1 
1    ‘printf’ prints the FORMAT string, interpreting ‘%’ directives and
1 ‘\’ escapes to format numeric and string arguments in a way that is
11 mostly similar to the C ‘printf’ function.  ⇒‘printf’ format
 directives (libc)Output Conversion Syntax, for details.  The
1 differences are listed below.
1 
1    Due to shell aliases and built-in ‘printf’ functions, using an
1 unadorned ‘printf’ interactively or in a script may get you different
1 functionality than that described here.  Invoke it via ‘env’ (i.e., ‘env
1 printf ...’) to avoid interference from the shell.
1 
1    • The FORMAT argument is reused as necessary to convert all the given
1      ARGUMENTs.  For example, the command ‘printf %s a b’ outputs ‘ab’.
1 
1    • Missing ARGUMENTs are treated as null strings or as zeros,
1      depending on whether the context expects a string or a number.  For
1      example, the command ‘printf %sx%d’ prints ‘x0’.
1 
1    • An additional escape, ‘\c’, causes ‘printf’ to produce no further
1      output.  For example, the command ‘printf 'A%sC\cD%sF' B E’ prints
1      ‘ABC’.
1 
1    • The hexadecimal escape sequence ‘\xHH’ has at most two digits, as
1      opposed to C where it can have an unlimited number of digits.  For
1      example, the command ‘printf '\x07e'’ prints two bytes, whereas the
1      C statement ‘printf ("\x07e")’ prints just one.
1 
1    • An additional directive ‘%b’, prints its argument string with ‘\’
1      escapes interpreted in the same way as in the FORMAT string, except
1      that octal escapes are of the form ‘\0OOO’ where OOO is 0 to 3
1      octal digits.  If ‘\OOO’ is nine-bit value, ignore the ninth bit.
1      If a precision is also given, it limits the number of bytes printed
1      from the converted string.
1 
1    • An additional directive ‘%q’, prints its argument string in a
1      format that can be reused as input by most shells.  Non-printable
1      characters are escaped with the POSIX proposed ‘$''’ syntax, and
1      shell metacharacters are quoted appropriately.  This is an
1      equivalent format to ‘ls --quoting=shell-escape’ output.
1 
1    • Numeric arguments must be single C constants, possibly with leading
1      ‘+’ or ‘-’.  For example, ‘printf %.4d -3’ outputs ‘-0003’.
1 
1    • If the leading character of a numeric argument is ‘"’ or ‘'’ then
1      its value is the numeric value of the immediately following
1      character.  Any remaining characters are silently ignored if the
1      ‘POSIXLY_CORRECT’ environment variable is set; otherwise, a warning
1      is printed.  For example, ‘printf "%d" "'a"’ outputs ‘97’ on hosts
1      that use the ASCII character set, since ‘a’ has the numeric value
1      97 in ASCII.
1 
1    A floating-point argument must use a period before any fractional
1 digits, but is printed according to the ‘LC_NUMERIC’ category of the
1 current locale.  For example, in a locale whose radix character is a
1 comma, the command ‘printf %g 3.14’ outputs ‘3,14’ whereas the command
1 ‘printf %g 3,14’ is an error.  ⇒Floating point.
1 
1    ‘printf’ interprets ‘\OOO’ in FORMAT as an octal number (if OOO is 1
1 to 3 octal digits) specifying a byte to print, and ‘\xHH’ as a
1 hexadecimal number (if HH is 1 to 2 hex digits) specifying a character
1 to print.  Note however that when ‘\OOO’ specifies a number larger than
1 255, ‘printf’ ignores the ninth bit.  For example, ‘printf '\400'’ is
1 equivalent to ‘printf '\0'’.
1 
1    ‘printf’ interprets two character syntaxes introduced in ISO C 99:
1 ‘\u’ for 16-bit Unicode (ISO/IEC 10646) characters, specified as four
1 hexadecimal digits HHHH, and ‘\U’ for 32-bit Unicode characters,
1 specified as eight hexadecimal digits HHHHHHHH.  ‘printf’ outputs the
1 Unicode characters according to the ‘LC_CTYPE’ locale.  Unicode
1 characters in the ranges U+0000...U+009F, U+D800...U+DFFF cannot be
1 specified by this syntax, except for U+0024 ($), U+0040 (@), and U+0060
1 ()̀.
1 
1    The processing of ‘\u’ and ‘\U’ requires a full-featured ‘iconv’
1 facility.  It is activated on systems with glibc 2.2 (or newer), or when
1 ‘libiconv’ is installed prior to this package.  Otherwise ‘\u’ and ‘\U’
1 will print as-is.
1 
11    The only options are a lone ‘--help’ or ‘--version’.  ⇒Common
 options.  Options must precede operands.
1 
1    The Unicode character syntaxes are useful for writing strings in a
1 locale independent way.  For example, a string containing the Euro
1 currency symbol
1 
1      $ env printf '\u20AC 14.95'
1 
1 will be output correctly in all locales supporting the Euro symbol
1 (ISO-8859-15, UTF-8, and others).  Similarly, a Chinese string
1 
1      $ env printf '\u4e2d\u6587'
1 
1 will be output correctly in all Chinese locales (GB2312, BIG5, UTF-8,
1 etc).
1 
1    Note that in these examples, the ‘printf’ command has been invoked
1 via ‘env’ to ensure that we run the program found via your shell’s
1 search path, and not a shell alias or a built-in function.
1 
1    For larger strings, you don’t need to look up the hexadecimal code
1 values of each character one by one.  ASCII characters mixed with \u
1 escape sequences is also known as the JAVA source file encoding.  You
1 can use GNU recode 3.5c (or newer) to convert strings to this encoding.
1 Here is how to convert a piece of text into a shell script which will
1 output this text in a locale-independent way:
1 
1      $ LC_CTYPE=zh_CN.big5 /usr/local/bin/printf \
1          '\u4e2d\u6587\n' > sample.txt
1      $ recode BIG5..JAVA < sample.txt \
1          | sed -e "s|^|/usr/local/bin/printf '|" -e "s|$|\\\\n'|" \
1          > sample.sh
1 
1    An exit status of zero indicates success, and a nonzero value
1 indicates failure.
1