WCSLIB: wcsprintf.h File Reference

WCSLIB 8.9

Loading...
Searching...
No Matches
Macros | Functions
wcsprintf.h File Reference
`#include <inttypes.h>`
`#include <stdio.h>`

Go to the source code of this file.

## Macros
#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

Routines in this suite 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.

## Macro Definition Documentation

## ◆ WCSPRINTF_PTR

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

Value:
if (ptr) { \
wcsprintf("%s%#" PRIxPTR "%s", (str1), (uintptr_t)(ptr), (str2)); \
} else { \
wcsprintf("%s0x0%s", (str1), (str2)); \
}

Print addresses in a consistent way.

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

## ◆ wcsprintf_set()

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

Set output disposition for wcsprintf() and wcsfprintf().

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(). In threaded execution, thread-local storage (TLS) is used for the buffer and its indices and this may be used to aggregate messages for each thread prior to output. The buffer must be freed prior to the termination of the thread by calling wcsprintf_set() with a valid FILE*, e.g. stdout.

Returns
  Status return value:
  - 0: Success.

## ◆ wcsprintf()

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

Print function used by WCSLIB diagnostic routines.

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.

## ◆ wcsfprintf()

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

Print function used by WCSLIB diagnostic routines.

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()

const char * wcsprintf_buf | ( | void |  | ) |

Get the address of the internal string buffer.

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 directly on this const pointer.