WCSLIB 4.17: wcsprintf.h File Reference

# wcsprintf.h File Reference

`#include <stdio.h>`

Go to the source code of this file.

## Defines
#define | WCSPRINTF_PTR(str1, ptr, str2)
| Print addresses in a consistent way.
## Functions
int | wcsprintf_set (FILE *wcsout)
| Set output disposition for wcsprintf() and wcsfprintf().
int | wcsprintf (const char *format,...)
| Print function used by WCSLIB diagnostic routines.
int | wcsfprintf (FILE *stream, const char *format,...)
| Print function used by WCSLIB diagnostic routines.
const char * | wcsprintf_buf (void)
| Get the address of the internal string buffer.

## Detailed Description

These routines allow diagnostic output from celprt(), linprt(), prjprt(), spcprt(), tabprt(), wcsprt(), and wcserr_prt() to be redirected to a file or captured in a string buffer. Those routines all use wcsprintf() for output. Likewise wcsfprintf() is used by wcsbth() and wcspih(). Both functions may be used by application programmers to have other output go to the same place.

## Define Documentation

#define WCSPRINTF_PTR | ( | str1,
|  | ptr,
|  | str2 |  | ) |

Value:

    if (ptr) { \
        wcsprintf("%s%#lx%s", (str1), (unsigned long)(ptr), (str2)); \
      } else { \
        wcsprintf("%s0x0%s", (str1), (str2)); \
      }

WCSPRINTF_PTR() is a preprocessor macro used to print addresses in a consistent way.

On some systems the "p" format descriptor renders a NULL pointer as the string "0x0". On others, however, it produces "0" or even "(nil)". On some systems a non-zero address is prefixed with "0x", on others, not.

The WCSPRINTF_PTR() macro ensures that a NULL pointer is always rendered as "0x0" and that non-zero addresses are prefixed with "0x" thus providing consistency, for example, for comparing the output of test programs.

## Function Documentation

int wcsprintf_set | ( | FILE * | wcsout | ) |

wcsprintf_set() sets the output disposition for wcsprintf() which is used by the celprt(), linprt(), prjprt(), spcprt(), tabprt(), wcsprt(), and wcserr_prt() routines, and for wcsfprintf() which is used by wcsbth() and wcspih().

Parameters:

  `[in]` | wcsout | Pointer to an output stream that has been opened for writing, e.g. by the fopen() stdio library function, or one of the predefined stdio output streams - stdout and stderr. If zero (NULL), output is written to an internally-allocated string buffer, the address of which may be obtained by wcsprintf_buf().

Returns:
  Status return value:
  - 0: Success.

int wcsprintf | ( | const char * | format,
|  |  | ... |
| ) |  |  |

wcsprintf() is used by celprt(), linprt(), prjprt(), spcprt(), tabprt(), wcsprt(), and wcserr_prt() for diagnostic output which by default goes to stdout. However, it may be redirected to a file or string buffer via wcsprintf_set().

Parameters:

  `[in]` | format | Format string, passed to one of the printf(3) family of stdio library functions.
  `[in]` | ... | Argument list matching format, as per printf(3).

Returns:
  Number of bytes written.

int wcsfprintf | ( | FILE * | stream,
|  | const char * | format,
|  |  | ... |
| ) |  |  |

wcsfprintf() is used by wcsbth(), and wcspih() for diagnostic output which they send to stderr. However, it may be redirected to a file or string buffer via wcsprintf_set().

Parameters:

  `[in]` | stream | The output stream if not overridden by a call to wcsprintf_set().
  `[in]` | format | Format string, passed to one of the printf(3) family of stdio library functions.
  `[in]` | ... | Argument list matching format, as per printf(3).

Returns:
  Number of bytes written.

wcsprintf_buf | ( | void |  | ) |

wcsprintf_buf() returns the address of the internal string buffer created when wcsprintf_set() is invoked with its FILE* argument set to zero.

Returns:
  Address of the internal string buffer. The user may free this buffer by calling wcsprintf_set() with a valid FILE*, e.g. stdout. The free() stdlib library function must NOT be invoked on this const pointer.