LIBVECPF(3)

NAME
libvecpf - The Vector Printf Library

SYNOPSIS
#include <stdio.h>

int printf(const char *format, ...);
int fprintf(FILE *stream, const char *format, ...);
int sprintf(char *str, const char *format, ...);
int snprintf(char *str, size_t size, const char *format, ...);

DESCRIPTION
This library extends the printf() function, via a printf-hooks callback mechanism in GLIBC, so that it may format Vector data types for display.

  Additional length modifiers under Altivec/VMX
The following additional length modifiers are supported on platforms that have the Altivec/VMX (Power ISA 2.01 with Vector extensions). Since the VSX facility is predicated on VMX support these additional length modifiers are also supported on platforms that have the VSX facility. In this section the term, `integer conversion' stands for the d, i, o, u, x, X, and c conversions. The term, `floating point conversion' stands for the f, F, e, E, g, G, a, and A conversions.

vl, lv
    (vee-ell,ell-vee) A following integer conversion corresponds to a 16 byte vector composed of four vector unsigned ints or vector signed ints.

vh, hv
    A following integer conversions corresponds to a 16 byte vector composed of eight vector unsigned shorts or vector signed shorts.

v   A following integer conversion corresponds to a 16 byte vector composed of sixteen vector unsigned chars or vector signed chars. A following floating point conversion corresponds to a 16 byte vector composed of four vector float single-precision floating point values.

  Additional length modifiers under VSX (Power ISA 2.06)
The following additional length modifiers are ONLY supported on platforms that have the VSX facility. In this section the term, `floating point conversion' stands for the f, F, e, E, g, G, a, and A conversions.

vv  (vee-vee) A following floating point conversion corresponds to a 16 byte vector composed of two vector double double-precision floating point values.

  conversion specifiers
The following integer printf conversion specifiers are supported by libvecpf:
d, i, o, u, x, X, c
The following floating point printf conversion specifiers are supported by libvecpf:
f, F, e, E, g, G, a, A

  valid simple format strings under AltiVec/VMX

%vld, %lvd
    Output a vector of four signed ints in signed decimal notation.

%vli, %lvi
    Same as %vld and %lvd.

%vlu, %lvu
    Output a vector of four unsigned ints in unsigned decimal notation.

%vlo, %lvo
    Output a vector of four unsigned ints in unsigned octal notation.

%vlx, %lvx
    Output a vector of four unsigned ints in unsigned hexidecimal (x) notation where the letters abcdef are used.

%vlX, %lvX
    Output a vector of four unsigned ints in unsigned hexidecimal (X) notation where the letters ABCDEF are used.

%vhd, %hvd
    Output a vector of eight signed shorts in signed decimal notation.

%vhi, %hvi
    Same as %vhd and %hvd.

%vhu,%hvu
    Output a vector of eight unsigned shorts in unsigned decimal notation.

%vho, %hvo
    Output a vector of eight unsigned shorts in unsigned octal notation.

%vhx, %hvx
    Output a vector of eight unsigned shorts in unsigned hexidecimal 'x' notation where the letters abcdef are used.

%vhX, %hvX
    Output a vector of eight unsigned shorts in unsigned hexidecimal (X) notation where the letters ABCDEF are used.

%vd Output a vector of sixteen signed chars in signed decimal notation.

%vi Same as %vd.

%vu Output a vector of sixteen unsigned chars in unsigned decimal notation.

%vo Output a vector of sixteen unsigned chars in unsigned octal notation.

%vx Output a vector of sixteen unsigned chars in unsigned hexidecimal 'x' notation where the letters abcdef are used.

%vX Output a vector of sixteen unsigned chars in unsigned hexidecimal (X) notation where the letters ABCDEF are used.

%vc Output a vector of sixteen unsigned chars as characters.

%ve, %vE
    Output a vector of four single-precision floats in the manner indicated in man printf(3) in The conversion specifier section, under the e and E specifiers, respectively.

%vf, %vF
    Output a vector of four single-precision floats in the manner indicated in man printf(3) in The conversion specifier section, under the f and F specifiers, respectively.

%vg, %vG
    Output a vector of four single-precision floats in the manner indicated in man printf(3) in The conversion specifier section, under the g and G specifiers, respectively.

%va, %vA
    Output a vector of four single-precision floats in the manner indicated in man printf(3) in The conversion specifier section, under the a and A specifiers, respectively.

  valid simple format strings under VSX

%vve, %vvE
    Output a vector of two double-precision doubles in the manner indicated in man printf(3) in The conversion specifier section, under the e and E specifiers, respectively.

%vvf, %vvF
    Output a vector of two double-precision doubles in the manner indicated in man printf(3) in The conversion specifier section, under the f and F specifiers, respectively.

%vvg, %vvG
    Output a vector of two double-precision doubles in the manner indicated in man printf(3) in The conversion specifier section, under the g and G specifiers, respectively.

%vva, %vvA
    Output a vector of two double-precision doubles in the manner indicated in man printf(3) in The conversion specifier section, under the a and A specifiers, respectively.

CODE EXAMPLES
#include <stdio.h>
#include <altivec.h>
int main() {
  vector double d = { -1111.12304912348f, 4567.987654f };
  printf("%16.16vvf, d);
  return 0;
}

  Warnings
Using the additional printf length modifiers defined by this library in a program will cause the GCC compiler to complain in the following manner when compiled with -Wall:
warning: unknown conversion type character ‘v’ in format
This warning can be supressed with the -Wno-format compiler switch. Only suppress warnings with care.

LINKING EXAMPLES

  dynamic linking
"gcc -maltivec -O3 m32 -g -Wall -o foo foo.c -mcpu=power7 -lvecpf -Wno-format"

  static linking
Compiling an application and linking it against the static library libvecpf.a will expose a default feature of the link editor (ld) which purges unused symbols. The link editor sees constructors as unused in this context and purges them from the final archive. This will prevent the registration of the printf-hook callback mechanism and printf will not support Vector data types. In order to prevent the link editor from purging the libvecpf constructor on the final link of a static linking operation explicitly tell it to not purge the constructor by passing
-Wl,-u,__libvecpf_init
during the link stage as in the following example:
gcc -static -maltivec -O3 -m32 -g -Wall -o foo foo.c -mcpu=power7 -Wl,-u,__libvecpf_init -lvecpf -Wno-format

DEPENDENCIES
GLIBC printf-hooks support didn't go into GLIBC until version 2.10.

LIMITATIONS
Libvecpf only supports the default separator; as things are today the GLIBC printf-hooks mechanism doesn't allow separator flags to be changed.

RATIONALE

REFERENCES

Power ISA™ Version 2.06

AltiVec™ Technology Programming Interface Manual, Freescale Semiconductor, 1999.

Power Architecture® 32-bit Application Binary Interface Supplement 1.0 - Linux® & Embedded

SEE ALSO
printf(3)

REPORTING BUGS

Email bug reports to Ryan S. Arnold <rsa@linux.vnet.ibm.com>.

AUTHORS
This manual page was written by Ryan S. Arnold <rsa@linux.vnet.ibm.com>.