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

Guardian Native C Library Calls (n - r) __ns_fopen_special(3)
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 between zero and fifteen.
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.
The default number of secondary extents for files created by __ns_fopen_special() is 16. The
default number of maxextents for files created by __ns_fopen_special() is 500.
Refer to the Guardian Programmer’s Guide for complete details on active backup programming
in C.
527192-005 Hewlett-Packard Company 5−13