GNU Info

(libc.info)Parsing a Template String

---

Next: Example of Parsing Prev: Variable Arguments Output Up: Formatted Output

---

Enter node , (file) or (file)node

Parsing a Template String
-------------------------

   You can use the function `parse_printf_format' to obtain information
about the number and types of arguments that are expected by a given
template string.  This function permits interpreters that provide
interfaces to `printf' to avoid passing along invalid arguments from
the user's program, which could cause a crash.

   All the symbols described in this section are declared in the header
file `printf.h'.

 - Function: size_t parse_printf_format (const char *TEMPLATE, size_t
          N, int *ARGTYPES)
     This function returns information about the number and types of
     arguments expected by the `printf' template string TEMPLATE.  The
     information is stored in the array ARGTYPES; each element of this
     array describes one argument.  This information is encoded using
     the various `PA_' macros, listed below.

     The argument N specifies the number of elements in the array
     ARGTYPES.  This is the maximum number of elements that
     `parse_printf_format' will try to write.

     `parse_printf_format' returns the total number of arguments
     required by TEMPLATE.  If this number is greater than N, then the
     information returned describes only the first N arguments.  If you
     want information about additional arguments, allocate a bigger
     array and call `parse_printf_format' again.

   The argument types are encoded as a combination of a basic type and
modifier flag bits.

 - Macro: int PA_FLAG_MASK
     This macro is a bitmask for the type modifier flag bits.  You can
     write the expression `(argtypes[i] & PA_FLAG_MASK)' to extract
     just the flag bits for an argument, or `(argtypes[i] &
     ~PA_FLAG_MASK)' to extract just the basic type code.

   Here are symbolic constants that represent the basic types; they
stand for integer values.

`PA_INT'
     This specifies that the base type is `int'.

`PA_CHAR'
     This specifies that the base type is `int', cast to `char'.

`PA_STRING'
     This specifies that the base type is `char *', a null-terminated
     string.

`PA_POINTER'
     This specifies that the base type is `void *', an arbitrary
     pointer.

`PA_FLOAT'
     This specifies that the base type is `float'.

`PA_DOUBLE'
     This specifies that the base type is `double'.

`PA_LAST'
     You can define additional base types for your own programs as
     offsets from `PA_LAST'.  For example, if you have data types `foo'
     and `bar' with their own specialized `printf' conversions, you
     could define encodings for these types as:

          #define PA_FOO  PA_LAST
          #define PA_BAR  (PA_LAST + 1)

   Here are the flag bits that modify a basic type.  They are combined
with the code for the basic type using inclusive-or.

`PA_FLAG_PTR'
     If this bit is set, it indicates that the encoded type is a
     pointer to the base type, rather than an immediate value.  For
     example, `PA_INT|PA_FLAG_PTR' represents the type `int *'.

`PA_FLAG_SHORT'
     If this bit is set, it indicates that the base type is modified
     with `short'.  (This corresponds to the `h' type modifier.)

`PA_FLAG_LONG'
     If this bit is set, it indicates that the base type is modified
     with `long'.  (This corresponds to the `l' type modifier.)

`PA_FLAG_LONG_LONG'
     If this bit is set, it indicates that the base type is modified
     with `long long'.  (This corresponds to the `L' type modifier.)

`PA_FLAG_LONG_DOUBLE'
     This is a synonym for `PA_FLAG_LONG_LONG', used by convention with
     a base type of `PA_DOUBLE' to indicate a type of `long double'.

   For an example of using these facilities, see Note: Example of
Parsing.