Open System Services Programmer's Guide

Guardian Procedures
You can (and in some cases must) use Guardian procedures when you cannot accomplish a task
with OSS functions. For example, to get the file code of a Guardian file, you must use a Guardian
file system procedure, such as FILE_GETINFO_ or FILE_GETINFOBYNAME_. You also might want
to use Guardian procedures in cases where the Guardian procedure provides more information.
For example, FILE_GETINFOLIST_ provides much more information than the stat() function about
Guardian or OSS files.
Many of the Guardian procedures can be called directly from an OSS C program by including
the cextdecs.h header file in the program. The cextdecs.h file contains function prototype
declarations for the Guardian procedures you can call directly from your C program. You must
use the EXTENSIONS pragma with this file and should compile using the -Wextensions flag.
For information about Guardian procedures, see the Guardian Procedure Calls Reference Manual,
the Guardian Programmer’s Guide, and the Open System Services Porting Guide. Some procedures
in the Guardian Procedure Calls Reference Manual are described as “superseded” by other
procedures. For example, the OPEN procedure is superseded by the FILE_OPEN_ procedure.
Superseded procedures do not take full advantage of more current features and you should not
use them. They are provided only for backward compatibility.
A call to a Guardian procedure usually either returns a return value or sets a condition code. Most
of the Guardian procedures you need to use fall into one of these two categories, and you can
call these procedures directly from an OSS program. Those procedures that return both a return
value and a condition code cannot be called directly from an OSS (or Guardian C) program.
Procedures That Return a Return Value
Example 2 (page 39) shows an OSS program that calls the Guardian procedure
FILE_GETINFOBYNAME_ to get information about a Guardian file, whose filename is provided
as an input parameter to the procedure. The procedure return value is assigned to retcode.
38 Overview of the OSS Programming Environment