Guardian C Library Calls Reference Manual

Reference to Library Calls
Guardian TNS C Library Calls Reference Manual—128833 3-133
__ns_fset_file_state (supplementary)
Return Value
0 if the operation is successful, -1 if an error occurs.
Usage Guidelines
•
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 function to retrieve the file state information and sent the state
information through the $RECEIVE facility to the backup process.
•
The variable containing the file state information, not the pointer to the variable,
must be sent through the $RECEIVE facility from the primary process to the backup
process.
•
If the file specified in the stream argument is not open, errno is set to ENONSTOP.
•
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.
•
Disable buffering with the setvbuf or setnbuf function
•
In addition to either the CLARGE or CWIDE library file, you must bind the
CNONSTOP library file into programs that use this function.
•
This function can only be used in the Guardian environment.
•
Refer to the Guardian Programmer’s Guide for complete details on fault-tolerant
programming in C.