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

Guardian Native C Library Calls (n - r) __ns_backup_fopen(3)
NAME
__ns_backup_fopen - Performs a backup open for a file opened in the primary process
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>
FILE *__ns_backup_fopen (
__ns_std_io_file_open_state *file_open_state);
PARAMETERS
file_open_state Points to a variable that stores the file open state information.
DESCRIPTION
For active backup process pairs, the __ns_backup_fopen( ) function performs a backup open for
a file that was opened in the primary process using ANSI-model 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 perform a backup open of the file. Before cal-
ling this function, the primary process must first call the __ns_fget_file_open_state() function to
retrieve the file open state information. The primary process can send to the backup process the
state information using the $RECEIVE facility or other methods. 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 backup file open does not perform any fopen() function access_mode actions that create or
truncate a file. File-creation and truncation actions are not necessary because these actions were
performed by the initial fopen( ) call in the primary process.
The only meaningful operations on file open state information are retrieving with the
__ns_fget_file_open_state() function, starting a backup file open with the
__ns_backup_fopen() 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 open state infor-
mation are undefined.
Refer to the Guardian Programmer’s Guide for complete details on active backup programming
in C.
RETURN VALUES
Upon successful completion, a pointer to the FILE structure denoting the file is returned. Other-
wise, a null pointer is returned.
ERRORS
If any of the following conditions occur, the __ns_backup_fopen( ) function sets errno to the
corresponding value:
• [ENOIMEM], if insufficient memory is available.
• An fopen() function errno value, if an error occurs on the file open.
• A Guardian file system error code, if a file system error occurs. (Error 12 indicates the
backup open cannot obtain the same file number assigned to the primary open.)
527192-018 Hewlett-Packard Company 5−23