RtPrintf

RtPrintf prints formatted output to the standard output stream or console window (see Remarks below for RTSS vs Windows output behaviors).

Syntax

INT RtPrintf(
    LPCSTR lpFormat [,argument, . . .]
);

Parameters

lpFormat

The format control (with optional arguments).

Return Value

The number of characters printed if the function succeeds, a negative value if an error occurs

Remarks

APIs that write to the RTX64 Console, including C/C++ Runtime library APIs, such as printf, std::cout, and std::cerr, may not return immediately in the following scenarios.

• When no user is logged on. This can happen when the RTX64 Subsystem is configured to start when Windows boots and if real-time applications are configured to start when the Subsystem starts.
• When a user is logged on via Remote Desktop Connection but disconnects before an RTX64 Console opens on the desktop of the remote session.

If real-time applications are expected to produce large amounts of console output, we recommend avoiding the scenarios listed above.

RtPrintf is similar to printf, but RtPrintf does not require the C Runtime library and can work with any combination of run-time libraries. This function does not support floating point conversions in the RTSS environment.

RtPrintf formats and prints a series of characters and values to the standard output stream, stdout, or to the RTX64 Console, depending on the application type:

• In RTSS applications, RtPrintf/RtWprintf only write to the RTX64 Console (never to stdout). If you redirect stdout to a file with freopen, RtPrintf/RtWprintf will continue to write to the RTX64 console, but printf/wprintf (and their related APIs) will write to the file.
• In Windows applications, RtPrintf/RtWPrintf only write to stdout (never to the RTX64 Console). If you redirect stdout to a file with freopen, RtPrintf/RtWprintf will write to the file (because stdout was redirected).

If arguments follow the format string, the format string must contain specifications that determine the output format for the arguments.

The format argument consists of ordinary characters, escape sequences, and (if arguments follow format) format specifications. The ordinary characters and escape sequences are copied in order of their appearance.

Format specifications always begin with a percent sign (%) and are read left to right. When RtPrintf encounters the first format specification (if any), it converts the value of the first argument after format and outputs it accordingly. The second format specification causes the second argument to be converted and output, and so on. If there are more arguments than there are format specifications, the extra arguments are ignored. The results are undefined if there are not enough arguments for all the format specifications.

Example

RtPrintf("Line one\n\t\tLine two\n");

produces the output:

Line one

  Line two

Format Specification Fields (RtPrintf and RtWprintf)

A format specification, which consists of optional and required fields, has the following form:

%[flags] [width] .precision] [{h|l|L}]type

Each field of the format specification is a single character or number signifying a particular format option. The simplest format specification contains only the percent sign and a type character (for example, %s). If a percent sign is followed by a character that has no meaning as a format field, the character is copied. For example, to print a percent-sign character, use %%.

Required format field: The type character, which appears after the optional format fields, is the only required format field. It determines whether the associated argument is interpreted as a character, a string, or a number, as shown in the table that follows.

In the RTSS environment, the following limitations apply:

• The maximum output size is 512 characters. If more than 512 characters will be output, all characters after the 512th are truncated.

NOTE: The types C and S, and the behavior of c and s with RtPrintf and RtWprintf are consistent with Microsoft extensions for printf and are not ANSI compatible.

Type character	Argument	Output format
%%		A literal '%' character
%c	Integer	For RtPrintf, specifies a single-byte character. For RtWprintf, specifies a wide character.
%C	Integer	For RtPrintf, specifies a wide character. For RtWprintf, specifies a single-byte character.
%d	Integer	Signed decimal integer.
%i	Integer	Signed decimal integer.
%o	Integer	Unsigned octal integer.
%u	Integer	Unsigned decimal integer.
%x	Integer	Unsigned hexadecimal integer, using "abcdef."
%X	Integer	Unsigned hexadecimal integer, using "ABCDEF."
%e	Floating-point	Not supported
%E	Floating-point	Not supported
%f	Floating-point	Not supported
%F	Floating-point	Not supported
%g	Floating-point	Not supported
%G	Floating-point	Not supported
%a	Floating-point	Not supported
%A	Floating-point	Not supported
%p	Pointer type	Display the argument as an address in hexadecimal digits.
%s	String	For RtPrintf, specifies a single-byte character string. For RtWprintf, specifies a wide character string. Characters are printed up to the first null character or until the precision value is reached.
%S	String	For RtPrintf, specifies a wide character string. For RtWprintf, specifies a single-byte character string. Characters are printed up to the first null character or until the precision value is reached.
%Z	ANSI_STRING structure	When the address of an ANSI_STRING or UNICODE_STRING structure is passed as the argument, display the string contained in the buffer pointed to by the Buffer field of the structure. Use a size modifier prefix of w to specify a UNICODE_STRING argument—for example, %wZ (see below). The Length field of the structure must be set to the length, in bytes, of the string. The MaximumLength field of the structure must be set to the length, in bytes, of the buffer. Typically, the Z type character is used only in driver debugging functions that use a conversion specification, such as dbgPrint and kdPrint.
%wZ	UNICODE_STRING structure	Specify a UNICODE_STRING argument (see %Z above).

Optional format fields: The optional fields, which appear before the type character, control other aspects of the formatting, as shown in the list that follows.

flags

Optional character(s) that control justification of output and print of signs, blanks, decimal points, and octal and hexadecimal prefixes. More than one flag can appear in a format specification.

width

Optional number that specifies the minimum number of characters.

precision

Optional number that specifies the maximum number of characters printed for all or part of the output field or the minimum number of digits printed for integer values.

H|l| L

Optional prefixes to type that specify the size of the argument.

See Also:

• RtAtoi
• RtWPrintf
• RtWtoi