Node:Formatted Output Functions, Next:, Previous:Formatted Output Strings, Up:Formatted Output


Functions

Each of the following functions is similar to the corresponding C library function. The basic printf forms take a variable argument list. The vprintf forms take an argument pointer, see Variadic Functions, or man 3 va_start.

It should be emphasised that if a format string is invalid, or the arguments don't match what the format specifies, then the behaviour of any of these functions will be unpredictable. GCC format string checking is not available, since it doesn't recognise the GMP extensions.

The file based functions gmp_printf and gmp_fprintf will return -1 to indicate a write error. All the functions can return -1 if the C library printf variant in use returns -1, but this shouldn't normally occur.

int gmp_printf (const char *fmt, ...) Function
int gmp_vprintf (const char *fmt, va_list ap) Function
Print to the standard output stdout. Return the number of characters written, or -1 if an error occurred.

int gmp_fprintf (FILE *fp, const char *fmt, ...) Function
int gmp_vfprintf (FILE *fp, const char *fmt, va_list ap) Function
Print to the stream fp. Return the number of characters written, or -1 if an error occurred.

int gmp_sprintf (char *buf, const char *fmt, ...) Function
int gmp_vsprintf (char *buf, const char *fmt, va_list ap) Function
Form a null-terminated string in buf. Return the number of characters written, excluding the terminating null.

No overlap is permitted between the space at buf and the string fmt.

These functions are not recommended, since there's no protection against exceeding the space available at buf.

int gmp_snprintf (char *buf, size_t size, const char *fmt, ...) Function
int gmp_vsnprintf (char *buf, size_t size, const char *fmt, va_list ap) Function
Form a null-terminated string in buf. No more than size bytes will be written. To get the full output, size must be enough for the string and null-terminator.

The return value is the total number of characters which ought to have been produced, excluding the terminating null. If retval >= size then the actual output has been truncated to the first size-1 characters, and a null appended.

No overlap is permitted between the region {buf,size} and the fmt string.

Notice the return value is in ISO C99 snprintf style. This is so even if the C library vsnprintf is the older GLIBC 2.0.x style.

int gmp_asprintf (char **pp, const char *fmt, ...) Function
int gmp_vasprintf (char *pp, const char *fmt, va_list ap) Function
Form a null-terminated string in a block of memory obtained from the current memory allocation function (see Custom Allocation). The block will be the size of the string and null-terminator. Put the address of the block in *pp. Return the number of characters produced, excluding the null-terminator.

Unlike the C library asprintf, gmp_asprintf doesn't return -1 if there's no more memory available, it lets the current allocation function handle that.

int gmp_obstack_printf (struct obstack *ob, const char *fmt, ...) Function
int gmp_obstack_vprintf (struct obstack *ob, const char *fmt, va_list ap) Function
Append to the current obstack object, in the same style as obstack_printf. Return the number of characters written. A null-terminator is not written.

fmt cannot be within the current obstack object, since the object might move as it grows.

These functions are available only when the C library provides the obstack feature, which probably means only on GNU systems, see Obstacks.