Guardian Native C Library Calls Reference Manual (G06.28+, H06.04+)

__ns_fset_file_state(3) Guardian Native C Library Calls Reference Manual
NAME
__ns_fset_file_state - Sets the file state information for a file opened for ANSI I/O
LIBRARY
G-series native nonPIC Guardian processes: $SYSTEM.SYSTEM.CRTLNS
G-series native PIC Guardian processes: $SYSTEM.SYSTEM.CRTLNS2
H-series native Guardian processes: $SYSTEM.ZDLLnnn.CRTLNSE
SYNOPSIS
#include <crtlns.h>
long __ns_fset_file_state (
FILE *stream,
__ns_std_io_file_state *file_state);
PARAMETERS
stream Specifies a file opened for ANSI I/O.
file_state Points to a variable that stores the file state information.
DESCRIPTION
The __ns_fset_file_state function sets the file state information for a file opened for ANSI I/O.
This function can be called within Guardian processes only. When used in a program compiled
by the TNS compiler, this function can be called by Guardian modules (modules compiled for the
Guardian environment) only.
This function is called from the backup process to update its state information for the file. Before
calling this function, the primary process must have first called the __ns_fget_file_state() func-
tion to retrieve the file state information and sent the state information to the backup process.
The variable containing the file state information, not the pointer to the variable, must be sent
from the primary process to the backup process.
The only meaningful operations on file state information are retrieving with the
__ns_fget_file_state( ) function, setting with the __ns_fset_file_state() function, and copying
with an assignment statement or a copy function from the C run-time library. The results of
manipulating components of the file state information are undefined.
The buffer for file operations is not part of the file state. This affects the input and output streams:
• For input streams, the file position is a component of the file state. The
__ns_fset_file_state( ) function updates the file position for the backup process to the file
position of the primary process at the time the __ns_fget_file_state() function was
called. Thus, buffering is not an issue for an input stream from a disk device. For all
other input streams, buffered but unread input is lost. For these nondisk input streams,
you can disable buffering with either the setvbuf or setnbuf function, ignore the lost
information, or manage the buffer yourself.
• For output streams, a call to a write function in user code might leave a partially filled,
unflushed buffer. To ensure that the buffer is flushed, you can:
— Perform a flush operation, such as a call to the fflush() function, prior to calling
the __ns_fget_file_state() function.
— Ignore the effects of unflushed buffers, if the unflushed buffer contents are not
critical to the application.
5−16 Hewlett-Packard Company 527192-005