fwide() — Set stream orientation

Standards

Standards / Extensions	C or C++	Dependencies
ISO C Amendment ISO/ANSI C++ C99 Single UNIX Specification, Version 3 Language Environment	both	z/OS® V1R7

Format

#define _MSE_PROTOS 
#include <stdio.h>
#include <wchar.h>

int fwide(FILE *stream, int mode);

#define _OPEN_SYS_UNLOCKED_EXT 1
#include <wchar.h>

int fwide_unlocked(FILE *stream, int mode);

General description

fwide() determines the orientation of the stream pointed to by stream. If mode is greater than 0, the function attempts to make the stream wide-oriented. If mode is less than 0, the function attempts to make the stream byte-oriented. Otherwise, mode is 0 and the function does not alter the orientation of the stream, rather the function returns the current orientation of the stream.

If the orientation of the stream has already been determined, fwide() will not change it.

Streams opened as type=record or type=blocked do not have orientation.

VSAM data sets and CICS® transient data queues do not have orientation. Use of fwide() against streams referring to VSAM data sets or CICS transient data queues will be unsuccessful.

An application wishing to check for error situations should set errno to 0, then call fwide(), then check errno. If errno is non-zero assume an error has occurred.

fwide_unlocked() is functionally equivalent to fwide() with the exception that it is not thread-safe. This function can safely be used in a multithreaded application if and only if it is called while the invoking thread owns the (FILE*) object, as is the case after a successful call to either the flockfile() or ftrylockfile() function.

Special considerations for C++: The interaction of fwide() and a C++ I/O stream is undefined.

Usage notes

The runtime library does not prevent using byte-oriented I/O functions on a wide-oriented stream, using wide-oriented I/O functions on a byte-oriented stream, or any other mixed orientation usage. The behavior of an application doing so is undefined. As a result, the orientation of a stream reported by fwide() might not be consistent with the I/O functions that are being used. The stream orientation first set using fwide() itself, or through the first I/O operation on the stream is what will be returned. For example, if fwide() is used to set the orientation as byte-oriented, but only wide-oriented I/O functions are used on the stream, the orientation of the stream remains byte-oriented even though no mixing of I/O functions has occurred.

Returned value

If successful, fwide() returns a value greater than 0 if the stream has wide-orientation after the call. It returns a value less than 0 if the stream has byte-orientation, or 0 if the stream has no orientation after the call.

When unsuccessful, fwide() returns 0 and sets errno to one of the following:

EBADF – The stream specified by stream was not valid.