/************************************************************************

  *

  * printf.h - declarations of the rw_printf family of functions

  *

  * $Id: printf.h 278837 2005-09-05 20:57:44Z sebor $

  *

  ************************************************************************

  *

  * Copyright (c) 1994-2005 Quovadx,  Inc., acting through its  Rogue Wave

  * Software division. Licensed under the Apache License, Version 2.0 (the

  * "License");  you may  not use this file except  in compliance with the

  * License.    You    may   obtain   a   copy   of    the   License    at

  * http://www.apache.org/licenses/LICENSE-2.0.    Unless   required    by

  * applicable law  or agreed to  in writing,  software  distributed under

  * the License is distributed on an "AS IS" BASIS,  WITHOUT WARRANTIES OR

  * CONDITIONS OF  ANY KIND, either  express or implied.  See  the License

  * for the specific language governing permissions  and limitations under

  * the License.

  * 

  **************************************************************************/

 #ifndef RW_PRINTF_H_INCLUDED

 #define RW_PRINTF_H_INCLUDED

 #include <testdefs.h>

 struct rw_file;

 // the equivalent of stdout and stderr

 extern _TEST_EXPORT rw_file* const rw_stdout;

 extern _TEST_EXPORT rw_file* const rw_stderr;

 /************************************************************************

  * Formatted file output.

  ************************************************************************/

 /**

  *  Prints to rw_stdout.

  */

 _TEST_EXPORT int

 rw_printf (const char*, ...);

 /**

  * Prints to a file.

  */

 _TEST_EXPORT int

 rw_fprintf (rw_file*, const char*, ...);

 /************************************************************************

  * Formatted string output.

  ************************************************************************/

 /**

  * Prints to a character buffer.

  */

 _TEST_EXPORT int

 rw_sprintf (char*, const char*, ...);

 /**

  * Prints to a character buffer of given size.

  */

 _TEST_EXPORT int

 rw_snprintf (char*, _RWSTD_SIZE_T, const char*, ...);

 /************************************************************************

  * Formatted string output into a dynamically allocated buffer.

  ************************************************************************/

 /**

  * Prints to a dynamically allocated character buffer.

  *

  * @param fmt  Format specifier.

  *

  * @return  On success, returns a pointer to the dynamically allocated

  *          character buffer. Otherwise, returns 0.

  */

 _TEST_EXPORT char*

 rw_sprintfa (const char* fmt, ...);

 /**

  * Prints to a dynamically allocated character buffer.

  *

  * @param buf  A pointer to character buffer where the function should

  *        store its output.

  * @param bufise  The size of the character buffer in bytes.

  *

  * @return  On success, if the size of the supplied buffer was sufficient

  *          to format all characters including the terminating NUL, returns

  *          buf. Otherwise, if the size of the supplied buffer was not

  *          sufficient, returns a pointer to the newly allocated character

  *          buffer of sufficient size. Returns 0 on failure.

  */

 _TEST_EXPORT char*

 rw_snprintfa (char *buf, _RWSTD_SIZE_T bufsize, const char* fmt, ...);

 /**

  * Prints to a dynamically allocated character buffer of sufficient size.

  * Provided for portability with the BSD and GNU C libraries:

  *

  * http://www.freebsd.org/cgi/man.cgi?query=asprintf

  * http://www.openbsd.org/cgi-bin/man.cgi?query=asprintf

  * http://netbsd.gw.com/cgi-bin/man-cgi?asprintf++NetBSD-current

  * http://www.gnu.org/software/libc/manual/html_node/Dynamic-Output.html

  *

  * @param pbuf  Pointer to a pointer to character set by the caller to

  *        to address of the inital character buffer, or 0 of no such

  *        buffer exists. The function sets the pointer to a the address

  *        of the dynamically allocated character buffer, or leaves it

  *        unchanged if it doesn't allocate any buffer.

  * @param pbufsize  Pointer to a size_t set by the caller to the size of

  *        the inital character buffer. The function sets the value pointed

  *        to by this argument to the size of the dynamically allocated

  *        character buffer, or leaves it unchanged if it doesn't allocate

  *        any buffer.

  * @param fmt  Format specifier.

  *        The format specifier string has the same syntax as C99 sprintf

  *        (see 7.19.6.1 of ISO/IEC 9899:1999) with the following extensions:

  *

  *        %n$          where n is a integer (see IEEE Std 1003.1)

  *        %m           the value of strerror(errno)

  *

  *        %{?}         if clause (extracts an int)

  *        %{:}         else clause

  *        %{;}         end of if/else clause

  *        %{#s}        quoted narrow character string

  *        %{#ls}       quoted wide character string

  *        %{$envvar}   value of an environment variable envvar

  *        %{f}         function pointer

  *        %{M}         member pointer

  *        %{#m}        name of the errno constant (such as EINVAL)

  *        %{n}         buffer size

  *        %{S}         pointer to std::string

  *        %{lS}        pointer to std::wstring

  *        %{tm}        pointer to struct tm

  *        %{InJ}       where n is one of { 8, 16, 32, 64 } and J { d, o, x, X }

  *

  * @return  On success, returns the number of characters formatted into

  *          the buffer, otherwise -1.

  */

 _TEST_EXPORT int

 rw_asnprintf (char** pbuf, _RWSTD_SIZE_T *pbufsize, const char *fmt, ...);

 #endif   // RW_PRINTF_H_INCLUDED