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

__ns_fopen_special(3) Guardian Native C Library Calls Reference Manual
NAME
__ns_fopen_special - Opens an ANSI I/O file to a specified sync depth
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_fopen_special (
char *file_name,
char *access_mode,
short sync_depth);
PARAMETERS
file_name Points to a string containing a valid Guardian filename.
access_mode Points to a string that specifies how you want to access the file. The possible
values for access_mode are described under the subheading "Access Mode
Values".
sync_depth Specifies the number of nonretryable write requests whose completion must be
remembered by the file system. sync_depth must conform to the operating sys-
tem limit of a value in the range of zero through fifteen. A value of 1 or greater
must be specified to recover from a path failure occuring during a write opera-
tion. The value of sync_depth also implies the number of write operations that
the primary process in a process pair can perform to this file without intervening
checkpoints to its backup process. If omitted, or if 0 (zero) is specified, internal
checkpointing does not occur and the file system does not automatically retry
disk path failures.
DESCRIPTION
The __ns_fopen_special() opens an ANSI I/O file to a specified sync depth.
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.
Other than allowing you to specify the sync depth, the __ns_fopen_special() operates the same
as the fopen() function.
For buffered file operations, a call to a write function in user code does not necessarily
correspond to one write operation at the operating system level where the sync-depth value is
meaningful. An operating system write operation is performed if the buffer is filled or a flush
operation is performed, such as a call to the fflush(), fclose(),orexit() function. You can disable
buffering with the setvbuf() or setbuf() function.
If a device does not support the sync-id mechanism and a sync_depth value is specified, a value
of 1 (one) is used for sync_depth.
If you include a system name in the filename, you must precede the system name with two
backslashes instead of one because backslash is an escape character in C. For example, to open
the file \SYS.$VOL.SVOL.FILE, you would use the C string: "\\SYS.$VOL.SVOL.FILE".
Unless you include "b" in the access string, the file is opened as a text file.
If the file does not already exist, __ns_fopen_special( ) creates a C binary file if you include "b"
in the access string; otherwise, it creates an Edit file.
5−18 Hewlett-Packard Company 527192-007