Guardian Native C Library Calls Reference Manual (G06.29+, H06.08+, J06.03+)

Guardian Native C Library Calls (n - r) __ns_fget_file_state(3)
NAME
__ns_fget_file_state - Returns 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_fget_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_fget_file_state() function returns 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 primary process to retrieve the current file state information. The
primary process sends the state information through the $RECEIVE facility or other methods to
the backup process. The backup process calls the __ns_fset_file_state( ) function to update its
state information for the file. 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 setbuf() 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.
527192-018 Hewlett-Packard Company 5−29