fwprintf() — Format Data as Wide Characters and Write to a Stream
Format
#include <stdio.h>
#include <wchar.h>
int fwprintf(FILE *stream, const wchar_t *format, argument-list);
Language Level
ANSI
Threadsafe
Yes
Locale Sensitive
The behavior of this function might be affected by the LC_CTYPE and LC_NUMERIC categories of the current locale, and might also be affected by the LC_UNI_CTYPE and LC_UNI_NUMERIC categories of the current locale if LOCALETYPE(*LOCALEUCS2) or LOCALETYPE(*LOCALEUTF) is specified on the compilation command. This function is not available when LOCALETYPE(*CLD) is specified on the compilation command. For more information, see Understanding CCSIDs and Locales.
Integrated File System Interface
This function is not available when SYSIFCOPT(*NOIFSIO) is specified on the compilation command.
Wide Character Function
See Wide Characters for more information.
Description
The fwprintf()
function
writes output to the stream pointed to by stream, under control
of the wide string pointed to by format. The format string
specifies how subsequent arguments are converted for output.
The fwprintf()
function
converts each entry in argument-list according
to the corresponding wide-character format specifier in format.
If insufficient arguments exist for the format, the behavior
is undefined. If the format is exhausted while arguments remain, the fwprintf()
function
evaluates the excess arguments, but otherwise ignores them. The fwprintf()
function
returns when it encounters the end of the format string.
The format comprises zero or more directives: ordinary
wide characters (not %) and conversion specifications. Conversion
specifications are processed as if they were replaced in the format
string by wide-character strings. The wide-character strings are the
result of fetching zero or more subsequent arguments and then converting
them, if applicable, according to the corresponding conversion specifier.
The fwprintf()
function
then writes the expanded wide-character format string to the output
stream.
fwprintf()
function
has the same form and function as the format string for printf()
,
with the following exceptions: - %c (without an l prefix) converts an integer argument to wchar_t,
as if by calling the
btowc()
function. - %s (without an l prefix) converts an array of multibyte characters
to an array of wchar_t, as if by calling the
mbrtowc()
function. The array is written up to, but not including, the terminating null character, unless the precision specifies a shorter output. - %ls and %S write an array of wchar_t. The array is written up to, but not including, the ending null character, unless the precision specifies a shorter output.
- Any width or precision specified for %c, %s, %ls, and %S indicates the number of characters rather than the number of bytes.
If a conversion specification is invalid, the behavior is undefined.
If any argument is, or points to, a union or an aggregate (except for an array of char type using %s conversion, an array of wchar_t type using %ls conversion, or a pointer using %p conversion), the behavior is undefined.
In no case does a nonexistent, or small field width, cause truncation of a field; if the conversion result is wider than the field width, the field is expanded to contain the conversion result.
Return Value
The fwprintf()
function
returns the number of wide characters transmitted. If an output error
occurred, it returns a negative value.
Example
#include <stdio.h>
#include <wchar.h>
#include <locale.h>
int count [10] = {1, 5, 8, 3, 0, 3, 5, 6, 8, 10};
int main(void)
{
int i,j;
FILE *stream; /* Open the stream for writing */
if (NULL == (stream = fopen("/QSYS.LIB/LIB.LIB/WCHAR.FILE/WCHAR.MBR","wb")))
perror("fopen error");
for (i=0; i < sizeof(count) / sizeof(count[0]); i++)
{
for (j = 0; j < count[i]; j++)
fwprintf(stream, L"*"); /* Print asterisk */
fwprintf(stream, L"\n"); /* Move to the next line */
}
fclose (stream);
}
/* The member WCHAR of file WCHAR will contain:
*
*****
********
***
***
*****
******
********
**********
*/
Unicode example
#include <stdio.h>
#include <stdlib.h>
#include <locale.h>
/* This program is compile LOCALETYPE(*LOCALEUCS2) and */
/* SYSIFCOPT(*IFSIO) */
int main(void)
{
FILE *stream;
wchar_t wc = 0x0058; /* UNICODE X */
char c1 = 'c';
char *s1 = "123";
wchar_t ws[4];
setlocale(LC_ALL,
"/QSYS.LIB/EN_US.LOCALE"); /* a CCSID 37 locale */
ws[0] = 0x0041; /* UNICODE A */
ws[1] = (wchar_t)0x0042; /* UNICODE B */
ws[2] = (wchar_t)0x0043; /* UNICODE C */
ws[3] = (wchar_t)0x0000;
stream = fopen("myfile.dat", "wb+");
/* lc and ls take wide char as input and just copies then */
/* to the file. So the file would look like this */
/* after the below fwprintf statement: */
/* 0058002000200020004100420043 */
/* 0020 is UNICODE blank */
fwprintf(stream, L"%lc %ls",wc,ws);
/* c and s take multibyte as input and produce UNICODE */
/* In this case c1 and s1 are CCSID 37 characters based */
/* on the setlocale above. So the characters are */
/* converted from CCSID 37 to UNICODE and will look */
/* like this in hex after the following fwprintf */
/* statement: 0063002000200020003100320033 */
/* 0063 is a UNICODE c 0031 is a UNICODE 1 and so on */
fwprintf(stream, L"%c %s",c1,s1);
/* Now lets try width and precision. 6ls means write */
/* 6 wide characters so we will pad with 3 UNICODE */
/* blanks and %.2s means write no more then 2 wide */
/* characters. So we get an output that looks like */
/* this: 00200020002000410042004300310032 */
fwprintf(stream, L"%6ls%.2s",ws,s1);
}
Related Information
- fprintf() — Write Formatted Data to a Stream
- printf() — Print Formatted Characters
- vfprintf() — Print Argument Data to Stream
- vprintf() — Print Argument Data
- btowc() — Convert Single Byte to Wide Character
- mbrtowc() — Convert a Multibyte Character to a Wide Character (Restartable)
- vfwprintf() — Format Argument Data as Wide Characters and Write to a Stream
- vswprintf() — Format and Write Wide Characters to Buffer
- wprintf() — Format Data as Wide Characters and Print
- <stdarg.h>
- <wchar.h>